SymPy Documentation

Release 1.3

SymPy Development Team

September 14, 2018

 CONTENTS

1 Installation 1
1.1 Anaconda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Run SymPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.5 Mpmath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.6 Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 SymPy Tutorial 5
2.1 Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4 Basic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5 Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6 Simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.7 Calculus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.8 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.9 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.10 Advanced Expression Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

3 Gotchas and Pitfalls 69

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.2 Equals Signs (=) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.3 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.4 Symbolic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.5 Special Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.6 Getting help from within SymPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4 SymPy User’s Guide 85

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.2 Learning SymPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.3 SymPy’s Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.4 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

5 SymPy Modules Reference 95

5.1 SymPy Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
5.2 Combinatorics Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
5.3 Number Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.4 Basic Cryptography Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
5.5 Concrete Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

i
 5.6 Discrete Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
5.7 Numerical evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
5.8 Structural Details of Code Generation with SymPy . . . . . . . . . . . . . . . . . . 400
5.9 Numeric Computation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
5.10 Functions Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
5.11 Geometry Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
5.12 Holonomic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
5.13 Symbolic Integrals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
5.14 Numeric Integrals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
5.15 Integration over Polytopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
5.16 Lie Algebra Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
5.17 Logic Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
5.18 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
5.19 Polynomials Manipulation Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
5.20 Printing System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
5.21 Plotting Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
5.22 Pyglet Plotting Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101
5.23 Assumptions Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
5.24 Term rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
5.25 Series Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
5.26 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
5.27 Simplify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185
5.28 Details on the Hypergeometric Function Expansion Module . . . . . . . . . . . . . 1211
5.29 Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
5.30 ODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1262
5.31 PDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1319
5.32 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328
5.33 Diophantine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347
5.34 Inequality Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
5.35 Solveset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
5.36 Tensor Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
5.37 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
5.38 Parsing input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496
5.39 Calculus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501
5.40 Physics Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510
5.41 Category Theory Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1814
5.42 Differential Geometry Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
5.43 Vector Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847
5.44 Contributions to docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887

6 SymPy Special Topics 1889

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889
6.2 Finite Difference Approximations to Derivatives . . . . . . . . . . . . . . . . . . . . 1889

7 Development Tips: Comparisons in Python 1895

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
7.2 Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
7.3 Method Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896
7.4 General Notes and Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898
7.5 Script To Verify This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898

8 Wiki 1903
8.1 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903

9 SymPy Papers 1905

ii
10 Planet SymPy 1907

11 SymPy logos 1909

12 Blogs, News, Magazines 1911

13 About 1913
13.1 SymPy Development Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
13.2 Financial and Infrastructure Support . . . . . . . . . . . . . . . . . . . . . . . . . . 1926
13.3 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1927

14 Citing SymPy 1931

Bibliography 1933

Python Module Index 1957

Index 1961

iii
iv
 CHAPTER

ONE

INSTALLATION

The SymPy CAS can be installed on virtually any computer with Python 2.7 or above. SymPy
does require mpmath Python library to be installed first. The recommended method of instal-
lation is through Anaconda, which includes mpmath, as well as several other useful libraries.
Alternatively, some Linux distributions have SymPy packages available.
SymPy officially supports Python 2.7, 3.4, 3.5, 3.6 and PyPy.

1.1 Anaconda

Anaconda is a free Python distribution from Continuum Analytics that includes SymPy, Mat-
plotlib, IPython, NumPy, and many more useful packages for scientific computing. This
is recommended because many nice features of SymPy are only enabled when certain li-
braries are installed. For example, without Matplotlib, only simple text-based plotting is
enabled. With the IPython notebook or qtconsole, you can get nicer LATEX printing by running
init_printing().
If you already have Anaconda and want to update SymPy to the latest version, use:

conda update sympy

1.2 Git

If you wish to contribute to SymPy or like to get the latest updates as they come, install SymPy
from git. To download the repository, execute the following from the command line:

git clone git://github.com/sympy/sympy.git

To update to the latest version, go into your repository and execute:

git pull origin master

If you want to install SymPy, but still want to use the git version, you can run from your
repository:

python setupegg.py develop

This will cause the installed version to always point to the version in the git directory.

1
SymPy Documentation, Release 1.3

1.3 Other Methods

Various Linux distributions have SymPy available as a package. You may also install SymPy
from source or using pip.

1.4 Run SymPy

After installation, it is best to verify that your freshly-installed SymPy works. To do this, start
up Python and import the SymPy libraries:

$ python
>>> from sympy import *

From here, execute some simple SymPy statements like the ones below:

>>> x = Symbol('x')
>>> limit(sin(x)/x, x, 0)
1
>>> integrate(1/x, x)
log(x)

For a starter guide on using SymPy effectively, refer to the SymPy Tutorial (page 5).

1.5 Mpmath

Versions of SymPy prior to 1.0 included mpmath, but it now depends on it as an external
dependency. If you installed SymPy with Anaconda, it will already include mpmath. Use:

conda install mpmath

to ensure that it is installed.

If you do not wish to use Anaconda, you can use pip install mpmath.
If you use mpmath via sympy.mpmath in your code, you will need to change this to use just
mpmath. If you depend on code that does this that you cannot easily change, you can work
around it by doing:

import sys
import mpmath
sys.modules['sympy.mpmath'] = mpmath

before the code that imports sympy.mpmath. It is recommended to change code that uses
sympy.mpmath to use mpmath directly wherever possible.

1.6 Questions

If you have a question about installation or SymPy in general, feel free to visit our chat on
Gitter. In addition, our mailing list is an excellent source of community support.

2 Chapter 1. Installation
 SymPy Documentation, Release 1.3

If you think there’s a bug or you would like to request a feature, please open an issue ticket.

1.6. Questions 3
SymPy Documentation, Release 1.3

4 Chapter 1. Installation
 CHAPTER

TWO

SYMPY TUTORIAL

2.1 Preliminaries

This tutorial assumes that the reader already knows the basics of the Python programming
language. If you do not, the official Python tutorial is excellent.
This tutorial assumes a decent mathematical background. Most examples require knowledge
lower than a calculus level, and some require knowledge at a calculus level. Some of the
advanced features require more than this. If you come across a section that uses some math-
ematical function you are not familiar with, you can probably skip over it, or replace it with a
similar one that you are more familiar with. Or look up the function on Wikipedia and learn
something new. Some important mathematical concepts that are not common knowledge will
be introduced as necessary.

2.1.1 Installation

Quick Tip

You do not need to install SymPy to try it. You can use the online shell at http://live.sympy.
org, or the shell at the bottom right of this documentation page.

You will need to install SymPy first. See the installation guide (page 1).
Alternately, you can just use the SymPy Live Sphinx extension to run the code blocks in the
browser. For example, click on the green “Run code block in SymPy Live” button below

>>> from sympy import *

>>> x = symbols('x')
>>> a = Integral(cos(x)*exp(x), x)
>>> Eq(a, a.doit())
Eq(Integral(exp(x)*cos(x), x), exp(x)*sin(x)/2 + exp(x)*cos(x)/2)

The SymPy Live shell in the bottom corner will pop up and evaluate the code block. You can
also click any individual line to evaluate it one at a time.
The SymPy Live shell is a fully interactive Python shell. You can type any expression in the
input box to evaluate it. Feel free to use it throughout the tutorial to experiment.
To show or hide the SymPy Live shell at any time, just click the green button on the bottom
right of the screen.

5
SymPy Documentation, Release 1.3

By default, the SymPy Live shell uses LATEX for output. If you want the output to look more like
the output in the documentation, change the output format to Str or Unicode in the settings.
If you wish to modify an example before evaluating it, change the evaluation mode to “copy”
in the SymPy Live settings. This will cause clicking on an example to copy the example to
the SymPy Live shell, but not evaluate it, allowing you to change it before execution. You can
also use the up/down arrow keys on your keyboard in the input box to move through the shell
history.
The SymPy Live shell is also available at http://live.sympy.org, with extra features, like a
mobile phone enhanced version and saved history.

2.1.2 Exercises

This tutorial was the basis for a tutorial given at the 2013 SciPy conference in Austin, TX.
The website for that tutorial is here. It has links to videos, materials, and IPython notebook
exercises. The IPython notebook exercises in particular are recommended to anyone going
through this tutorial.

2.1.3 About This Tutorial

This tutorial aims to give an introduction to SymPy for someone who has not used the library
before. Many features of SymPy will be introduced in this tutorial, but they will not be ex-
haustive. In fact, virtually every functionality shown in this tutorial will have more options
or capabilities than what will be shown. The rest of the SymPy documentation serves as API
documentation, which extensively lists every feature and option of each function.
These are the goals of this tutorial:
• To give a guide, suitable for someone who has never used SymPy (but who has used
Python and knows the necessary mathematics).
• To be written in a narrative format, which is both easy and fun to follow. It should read
like a book.
• To give insightful examples and exercises, to help the reader learn and to make it enter-
taining to work through.
• To introduce concepts in a logical order.
• To use good practices and idioms, and avoid antipatterns. Functions or methodologies
that tend to lead to antipatterns are avoided. Features that are only useful to advanced
users are not shown.
• To be consistent. If there are multiple ways to do it, only the best way is shown.
• To avoid unnecessary duplication, it is assumed that previous sections of the tutorial
have already been read.
Feedback on this tutorial, or on SymPy in general is always welcome. Just write to our mailing
list.

6 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

2.2 Introduction

2.2.1 What is Symbolic Computation?

Symbolic computation deals with the computation of mathematical objects symbolically. This
means that the mathematical objects are represented exactly, not approximately, and math-
ematical expressions with unevaluated variables are left in symbolic form.
Let’s take an example. Say we wanted to use the built-in Python functions to compute square
roots. We might do something like this

>>> import math

>>> math.sqrt(9)
3.0

9 is a perfect square, so we got the exact answer, 3. But suppose we computed the square
root of a number that isn’t a perfect square

>>> math.sqrt(8)
2.82842712475

Here we got an approximate result. 2.82842712475 is not the exact square root of 8 (indeed,
the actual square root of 8 cannot be represented by a finite decimal, since it is an irrational
number). If all we cared about was the decimal form of the square root of 8, we would be
done.
√ √ √
But suppose we want to go further. Recall that 8 = 4 · 2 = 2 2. We would have a hard
time deducing this from the above result. This is where symbolic computation comes in. With
a symbolic computation system like SymPy, square roots of numbers that are not perfect
squares are left unevaluated by default

>>> import sympy

>>> sympy.sqrt(3)
sqrt(3)

Furthermore—and this is where we start to see the real power of symbolic computation—
symbolic results can be symbolically simplified.

>>> sympy.sqrt(8)
2*sqrt(2)

2.2.2 A More Interesting Example

The above example starts to show how we can manipulate irrational numbers exactly using
SymPy. But it is much more powerful than that. Symbolic computation systems (which by
the way, are also often called computer algebra systems, or just CASs) such as SymPy are
capable of computing symbolic expressions with variables.
As we will see later, in SymPy, variables are defined using symbols. Unlike many symbolic
manipulation systems, variables in SymPy must be defined before they are used (the reason
for this will be discussed in the next section (page 10)).
Let us define a symbolic expression, representing the mathematical expression x + 2y.

2.2. Introduction 7
SymPy Documentation, Release 1.3

>>> from sympy import symbols

>>> x, y = symbols('x y')
>>> expr = x + 2*y
>>> expr
x + 2*y

Note that we wrote x + 2*y just as we would if x and y were ordinary Python variables. But
in this case, instead of evaluating to something, the expression remains as just x + 2*y. Now
let us play around with it:

>>> expr + 1
x + 2*y + 1
>>> expr - x
2*y

Notice something in the above example. When we typed expr - x, we did not get x + 2*y -
x, but rather just 2*y. The x and the -x automatically canceled one another. This is similar to
how sqrt(8) automatically turned into 2*sqrt(2) above. This isn’t always the case in SymPy,
however:

>>> x*expr
x*(x + 2*y)

Here, we might have expected x(x + 2y) to transform into x2 + 2xy, but instead we see that the
expression was left alone.
√ This√ is a common theme in SymPy. Aside from obvious simplifica-
tions like x − x = 0 and 8 = 2 2, most simplifications are not performed automatically. This
is because we might prefer the factored form x(x + 2y), or we might prefer the expanded form
x2 + 2xy. Both forms are useful in different circumstances. In SymPy, there are functions to
go from one form to the other

>>> from sympy import expand, factor

>>> expanded_expr = expand(x*expr)
>>> expanded_expr
x**2 + 2*x*y
>>> factor(expanded_expr)
x*(x + 2*y)

2.2.3 The Power of Symbolic Computation

The real power of a symbolic computation system such as SymPy is the ability to do all sorts
of computations symbolically. SymPy can simplify expressions, compute derivatives, inte-
grals, and limits, solve equations, work with matrices, and much, much more, and do it all
symbolically. It includes modules for plotting, printing (like 2D pretty printed output of math
formulas, or LATEX), code generation, physics, statistics, combinatorics, number theory, ge-
ometry, logic, and more. Here is a small sampling of the sort of symbolic power SymPy is
capable of, to whet your appetite.

>>> from sympy import *

>>> x, t, z, nu = symbols('x t z nu')

This will make all further examples pretty print with unicode characters.

>>> init_printing(use_unicode=True)

8 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

Take the derivative of sin (x)ex .

>>> diff(sin(x)*exp(x), x)
x x
e ⋅sin(x) + e ⋅cos(x)
∫
Compute (ex sin (x) + ex cos (x)) dx.

>>> integrate(exp(x)*sin(x) + exp(x)*cos(x), x)

x
e ⋅sin(x)
∫∞
Compute −∞
sin (x2 ) dx.

>>> integrate(sin(x**2), (x, -oo, oo))

√2⋅√π
─────
2

sin (x)
Find limx→0 x .

>>> limit(sin(x)/x, x, 0)
1

Solve x2 − 2 = 0.

>>> solve(x**2 - 2, x)
[-√2, √2]

Solve the differential equation y ′′ − y = et .

>>> y = Function('y')
>>> dsolve(Eq(y(t).diff(t, t) - y(t), exp(t)), y(t))
-t ⎛ t⎞ t
y(t) = C2 ⋅e + ⎜C1 + ─⎟⋅e
⎝ 2⎠

Find the eigenvalues of [ 12 22 ].

>>> Matrix([[1, 2], [2, 2]]).eigenvals()

⎧3 √17 √17 3 ⎫
⎨─ + ───: 1, - ─── + ─: 1⎬
⎩2 2 2 2 ⎭

Rewrite the Bessel function Jν (z) in terms of the spherical Bessel function jν (z).

>>> besselj(nu, z).rewrite(jn)

√2⋅√z⋅jn(ν - 1/2, z)
────────────────────
√π
∫π 2
Print 0
cos (x) dx using LATEX.

>>> latex(Integral(cos(x)**2, (x, 0, pi)))

\int_{0}^{\pi} \cos^{2}{\left (x \right )}\, dx

2.2. Introduction 9
SymPy Documentation, Release 1.3

2.2.4 Why SymPy?

There are many computer algebra systems out there. This Wikipedia article lists many of
them. What makes SymPy a better choice than the alternatives?
First off, SymPy is completely free. It is open source, and licensed under the liberal BSD
license, so you can modify the source code and even sell it if you want to. This contrasts
with popular commercial systems like Maple or Mathematica that cost hundreds of dollars in
licenses.
Second, SymPy uses Python. Most computer algebra systems invent their own language.
Not SymPy. SymPy is written entirely in Python, and is executed entirely in Python. This
means that if you already know Python, it is much easier to get started with SymPy, because
you already know the syntax (and if you don’t know Python, it is really easy to learn). We
already know that Python is a well-designed, battle-tested language. The SymPy developers
are confident in their abilities in writing mathematical software, but programming language
design is a completely different thing. By reusing an existing language, we are able to focus
on those things that matter: the mathematics.
Another computer algebra system, Sage also uses Python as its language. But Sage is large,
with a download of over a gigabyte. An advantage of SymPy is that it is lightweight. In
addition to being relatively small, it has no dependencies other than Python, so it can be used
almost anywhere easily. Furthermore, the goals of Sage and the goals of SymPy are different.
Sage aims to be a full featured system for mathematics, and aims to do so by compiling all the
major open source mathematical systems together into one. When you call some function in
Sage, such as integrate, it calls out to one of the open source packages that it includes. In
fact, SymPy is included in Sage. SymPy on the other hand aims to be an independent system,
with all the features implemented in SymPy itself.
A final important feature of SymPy is that it can be used as a library. Many computer algebra
systems focus on being usable in interactive environments, but if you wish to automate or
extend them, it is difficult to do. With SymPy, you can just as easily use it in an interactive
Python environment or import it in your own Python application. SymPy also provides APIs
to make it easy to extend it with your own custom functions.

2.3 Gotchas

To begin, we should make something about SymPy clear. SymPy is nothing more than a Python
library, like NumPy, Django, or even modules in the Python standard library sys or re. What
this means is that SymPy does not add anything to the Python language. Limitations that are
inherent in the Python language are also inherent in SymPy. It also means that SymPy tries
to use Python idioms whenever possible, making programming with SymPy easy for those
already familiar with programming with Python. As a simple example, SymPy uses Python
syntax to build expressions. Implicit multiplication (like 3x or 3 x) is not allowed in Python,
and thus not allowed in SymPy. To multiply 3 and x, you must type 3*x with the *.

2.3.1 Symbols

One consequence of this fact is that SymPy can be used in any environment where Python is
available. We just import it, like we would any other library:

>>> from sympy import *

10 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

This imports all the functions and classes from SymPy into our interactive Python session.
Now, suppose we start to do a computation.

>>> x + 1
Traceback (most recent call last):
...
NameError: name 'x' is not defined

Oops! What happened here? We tried to use the variable x, but it tells us that x is not defined.
In Python, variables have no meaning until they are defined. SymPy is no different. Unlike
many symbolic manipulation systems you may have used, in SymPy, variables are not defined
automatically. To define variables, we must use symbols.

>>> x = symbols('x')
>>> x + 1
x + 1

symbols takes a string of variable names separated by spaces or commas, and creates Sym-
bols out of them. We can then assign these to variable names. Later, we will investigate some
convenient ways we can work around this issue. For now, let us just define the most common
variable names, x, y, and z, for use through the rest of this section

>>> x, y, z = symbols('x y z')

As a final note, we note that the name of a Symbol and the name of the variable it is assigned
to need not have anything to do with one another.

>>> a, b = symbols('b a')

>>> a
b
>>> b
a

Here we have done the very confusing thing of assigning a Symbol with the name a to the
variable b, and a Symbol of the name b to the variable a. Now the Python variable named a
points to the SymPy Symbol named b, and visa versa. How confusing. We could have also
done something like

>>> crazy = symbols('unrelated')

>>> crazy + 1
unrelated + 1

This also shows that Symbols can have names longer than one character if we want.
Usually, the best practice is to assign Symbols to Python variables of the same name, although
there are exceptions: Symbol names can contain characters that are not allowed in Python
variable names, or may just want to avoid typing long names by assigning Symbols with long
names to single letter Python variables.
To avoid confusion, throughout this tutorial, Symbol names and Python variable names will
always coincide. Furthermore, the word “Symbol” will refer to a SymPy Symbol and the word
“variable” will refer to a Python variable.
Finally, let us be sure we understand the difference between SymPy Symbols and Python
variables. Consider the following:

2.3. Gotchas 11
SymPy Documentation, Release 1.3

x = symbols('x')
expr = x + 1
x = 2
print(expr)

What do you think the output of this code will be? If you thought 3, you’re wrong. Let’s see
what really happens

>>> x = symbols('x')
>>> expr = x + 1
>>> x = 2
>>> print(expr)
x + 1

Changing x to 2 had no effect on expr. This is because x = 2 changes the Python variable
x to 2, but has no effect on the SymPy Symbol x, which was what we used in creating expr.
When we created expr, the Python variable x was a Symbol. After we created, it, we changed
the Python variable x to 2. But expr remains the same. This behavior is not unique to SymPy.
All Python programs work this way: if a variable is changed, expressions that were already
created with that variable do not change automatically. For example

>>> x = 'abc'
>>> expr = x + 'def'
>>> expr
'abcdef'
>>> x = 'ABC'
>>> expr
'abcdef'

Quick Tip

To change the value of a Symbol in an expression, use subs

>>> x = symbols('x')
>>> expr = x + 1
>>> expr.subs(x, 2)
3

In this example, if we want to know what expr is with the new value of x, we need to reevaluate
the code that created expr, namely, expr = x + 1. This can be complicated if several lines
created expr. One advantage of using a symbolic computation system like SymPy is that we
can build a symbolic representation for expr, and then substitute x with values. The correct
way to do this in SymPy is to use subs, which will be discussed in more detail later.

>>> x = symbols('x')
>>> expr = x + 1
>>> expr.subs(x, 2)
3

2.3.2 Equals signs

Another very important consequence of the fact that SymPy does not extend Python syntax is
that = does not represent equality in SymPy. Rather it is Python variable assignment. This is

12 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

hard-coded into the Python language, and SymPy makes no attempts to change that.
You may think, however, that ==, which is used for equality testing in Python, is used for
SymPy as equality. This is not quite correct either. Let us see what happens when we use ==.

>>> x + 1 == 4
False

Instead of treating x + 1 == 4 symbolically, we just got False. In SymPy, == represents exact

structural equality testing. This means that a == b means that we are asking if a = b. We
always get a bool as the result of ==. There is a separate object, called Eq, which can be used
to create symbolic equalities

>>> Eq(x + 1, 4)
Eq(x + 1, 4)

There is one additional caveat about == as well. Suppose we want to know if (x+1)2 = x2 +2x+1.
We might try something like this:

>>> (x + 1)**2 == x**2 + 2*x + 1

False

We got False again. However, (x + 1)2 does equal x2 + 2x + 1. What is going on here? Did we
find a bug in SymPy, or is it just not powerful enough to recognize this basic algebraic fact?
Recall from above that == represents exact structural equality testing. “Exact” here means
that two expressions will compare equal with == only if they are exactly equal structurally.
Here, (x + 1)2 and x2 + 2x + 1 are not the same symbolically. One is the power of an addition of
two terms, and the other is the addition of three terms.
It turns out that when using SymPy as a library, having == test for exact structural equality is
far more useful than having it represent symbolic equality, or having it test for mathematical
equality. However, as a new user, you will probably care more about the latter two. We have
already seen an alternative to representing equalities symbolically, Eq. To test if two things
are equal, it is best to recall the basic fact that if a = b, then a − b = 0. Thus, the best way to
check if a = b is to take a − b and simplify it, and see if it goes to 0. We will learn later (page 25)
that the function to do this is called simplify. This method is not infallible—in fact, it can
be theoretically proven that it is impossible to determine if two symbolic expressions are
identically equal in general—but for most common expressions, it works quite well.

>>> a = (x + 1)**2
>>> b = x**2 + 2*x + 1
>>> simplify(a - b)
0
>>> c = x**2 - 2*x + 1
>>> simplify(a - c)
4*x

There is also a method called equals that tests if two expressions are equal by evaluating
them numerically at random points.

>>> a = cos(x)**2 - sin(x)**2

>>> b = cos(2*x)
>>> a.equals(b)
True

2.3. Gotchas 13
SymPy Documentation, Release 1.3

2.3.3 Two Final Notes: ^ and /

You may have noticed that we have been using ** for exponentiation instead of the standard ^.
That’s because SymPy follows Python’s conventions. In Python, ^ represents logical exclusive
or. SymPy follows this convention:

>>> True ^ False

True
>>> True ^ True
False
>>> x^y
Xor(x, y)

Finally, a small technical discussion on how SymPy works is in order. When you type some-
thing like x + 1, the SymPy Symbol x is added to the Python int 1. Python’s operator rules
then allow SymPy to tell Python that SymPy objects know how to be added to Python ints, and
so 1 is automatically converted to the SymPy Integer object.
This sort of operator magic happens automatically behind the scenes, and you rarely need to
even know that it is happening. However, there is one exception. Whenever you combine a
SymPy object and a SymPy object, or a SymPy object and a Python object, you get a SymPy
object, but whenever you combine two Python objects, SymPy never comes into play, and so
you get a Python object.

>>> type(Integer(1) + 1)
<class 'sympy.core.numbers.Integer'>
>>> type(1 + 1)
<... 'int'>

Note: On running the example above in SymPy Live, (1+1) is wrapped by Integer, so it does
not show the correct output.

This is usually not a big deal. Python ints work much the same as SymPy Integers, but there
is one important exception: division. In SymPy, the division of two Integers gives a Rational:

>>> Integer(1)/Integer(3)
1/3
>>> type(Integer(1)/Integer(3))
<class 'sympy.core.numbers.Rational'>

But in Python / represents either integer division or floating point division, depending on
whether you are in Python 2 or Python 3, and depending on whether or not you have run from
__future__ import division:

>>> from __future__ import division

>>> 1/2 #doctest: +SKIP
0.5

Note: On running the example above in SymPy Live, (1/2) is wrapped by Integer, so it does
not show the correct output.

To avoid this, we can construct the rational object explicitly

14 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> Rational(1, 2)
1/2

This problem also comes up whenever we have a larger symbolic expression with int/int in
it. For example:

>>> x + 1/2 #doctest: +SKIP

x + 0.5

Note: On running the example above in SymPy Live, (1/2) is wrapped by Integer, so it does
not show the correct output.

This happens because Python first evaluates 1/2 into 0.5, and then that is cast into a SymPy
type when it is added to x. Again, we can get around this by explicitly creating a Rational:

>>> x + Rational(1, 2)
x + 1/2

There are several tips on avoiding this situation in the Gotchas and Pitfalls (page 69) docu-
ment.

2.3.4 Further Reading

For more discussion on the topics covered in this section, see Gotchas and Pitfalls (page 69).

2.4 Basic Operations

Here we discuss some of the most basic operations needed for expression manipulation in
SymPy. Some more advanced operations will be discussed later in the advanced expression
manipulation (page 60) section.

>>> from sympy import *

>>> x, y, z = symbols(”x y z”)

2.4.1 Substitution

One of the most common things you might want to do with a mathematical expression is
substitution. Substitution replaces all instances of something in an expression with something
else. It is done using the subs method. For example

>>> expr = cos(x) + 1

>>> expr.subs(x, y)
cos(y) + 1

Substitution is usually done for one of two reasons:

1. Evaluating an expression at a point. For example, if our expression is cos(x) + 1 and
we want to evaluate it at the point x = 0, so that we get cos(0) + 1, which is 2.

2.4. Basic Operations 15

SymPy Documentation, Release 1.3

>>> expr.subs(x, 0)
2

2. Replacing a subexpression with another subexpression. There are two reasons we might
want to do this. The first is if we are trying to build an expression that has some symme-
xx
try, such as xx . To build this, we might start with x**y, and replace y with x**y. We
would then get x**(x**y). If we replaced y in this new expression with x**x, we would
get x**(x**(x**x)), the desired expression.

>>> expr = x**y

>>> expr
x**y
>>> expr = expr.subs(y, x**y)
>>> expr
x**(x**y)
>>> expr = expr.subs(y, x**x)
>>> expr
x**(x**(x**x))

The second is if we want to perform a very controlled simplification, or perhaps a simpli-

fication that SymPy is otherwise unable to do. For example, say we have sin(2x)+cos(2x),
and we want to replace sin(2x) with 2 sin(x) cos(x). As we will learn later, the function
expand_trig does this. However, this function will also expand cos(2x), which we may
not want. While there are ways to perform such precise simplification, and we will learn
some of them in the advanced expression manipulation (page 60) section, an easy way
is to just replace sin(2x) with 2 sin(x) cos(x).

>>> expr = sin(2*x) + cos(2*x)

>>> expand_trig(expr)
2*sin(x)*cos(x) + 2*cos(x)**2 - 1
>>> expr.subs(sin(2*x), 2*sin(x)*cos(x))
2*sin(x)*cos(x) + cos(2*x)

There are two important things to note about subs. First, it returns a new expression. SymPy
objects are immutable. That means that subs does not modify it in-place. For example

>>> expr = cos(x)

>>> expr.subs(x, 0)
1
>>> expr
cos(x)
>>> x
x

Quick Tip

SymPy expressions are immutable. No function will change them in-place.

Here, we see that performing expr.subs(x, 0) leaves expr unchanged. In fact, since SymPy
expressions are immutable, no function will change them in-place. All functions will return
new expressions.
To perform multiple substitutions at once, pass a list of (old, new) pairs to subs.

16 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> expr = x**3 + 4*x*y - z

>>> expr.subs([(x, 2), (y, 4), (z, 0)])
40

It is often useful to combine this with a list comprehension to do a large set of similar replace-
ments all at once. For example, say we had x4 − 4x3 + 4x2 − 2x + 3 and we wanted to replace
all instances of x that have an even power with y, to get y 4 − 4x3 + 4y 2 − 2x + 3.
>>> expr = x**4 - 4*x**3 + 4*x**2 - 2*x + 3
>>> replacements = [(x**i, y**i) for i in range(5) if i % 2 == 0]
>>> expr.subs(replacements)
-4*x**3 - 2*x + y**4 + 4*y**2 + 3

2.4.2 Converting Strings to SymPy Expressions

The sympify function (that’s sympify, not to be confused with simplify) can be used to
convert strings into SymPy expressions.
For example
>>> str_expr = ”x**2 + 3*x - 1/2”
>>> expr = sympify(str_expr)
>>> expr
x**2 + 3*x - 1/2
>>> expr.subs(x, 2)
19/2

Warning: sympify uses eval. Don’t use it on unsanitized input.

2.4.3 evalf

To evaluate a numerical expression into a floating point number, use evalf.

>>> expr = sqrt(8)
>>> expr.evalf()
2.82842712474619

SymPy can evaluate floating point expressions to arbitrary precision. By default, 15 digits of
precision are used, but you can pass any number as the argument to evalf. Let’s compute
the first 100 digits of π.
>>> pi.evalf(100)
3.
,→141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117068

To numerically evaluate an expression with a Symbol at a point, we might use subs followed
by evalf, but it is more efficient and numerically stable to pass the substitution to evalf
using the subs flag, which takes a dictionary of Symbol: point pairs.
>>> expr = cos(2*x)
>>> expr.evalf(subs={x: 2.4})
0.0874989834394464

2.4. Basic Operations 17

SymPy Documentation, Release 1.3

Sometimes there are roundoff errors smaller than the desired precision that remain after an
expression is evaluated. Such numbers can be removed at the user’s discretion by setting the
chop flag to True.

>>> one = cos(1)**2 + sin(1)**2

>>> (one - 1).evalf()
-0.e-124
>>> (one - 1).evalf(chop=True)
0

2.4.4 lambdify

subs and evalf are good if you want to do simple evaluation, but if you intend to evaluate
an expression at many points, there are more efficient ways. For example, if you wanted to
evaluate an expression at a thousand points, using SymPy would be far slower than it needs
to be, especially if you only care about machine precision. Instead, you should use libraries
like NumPy and SciPy.
The easiest way to convert a SymPy expression to an expression that can be numerically
evaluated is to use the lambdify function. lambdify acts like a lambda function, except it
converts the SymPy names to the names of the given numerical library, usually NumPy. For
example

>>> import numpy # doctest:+SKIP

>>> a = numpy.arange(10) # doctest:+SKIP
>>> expr = sin(x)
>>> f = lambdify(x, expr, ”numpy”) # doctest:+SKIP
>>> f(a) # doctest:+SKIP
[ 0. 0.84147098 0.90929743 0.14112001 -0.7568025 -0.95892427
-0.2794155 0.6569866 0.98935825 0.41211849]

Warning: lambdify uses eval. Don’t use it on unsanitized input.

You can use other libraries than NumPy. For example, to use the standard library math mod-
ule, use ”math”.

>>> f = lambdify(x, expr, ”math”)

>>> f(0.1)
0.0998334166468

To use lambdify with numerical libraries that it does not know about, pass a dictionary of
sympy_name:numerical_function pairs. For example

>>> def mysin(x):

... ”””
... My sine. Note that this is only accurate for small x.
... ”””
... return x
>>> f = lambdify(x, expr, {”sin”:mysin})
>>> f(0.1)
0.1

18 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

2.5 Printing

As we have already seen, SymPy can pretty print its output using Unicode characters. This
is a short introduction to the most common printing options available in SymPy.

2.5.1 Printers

There are several printers available in SymPy. The most common ones are
• str
• srepr
• ASCII pretty printer
• Unicode pretty printer
• LaTeX
• MathML
• Dot
In addition to these, there are also “printers” that can output SymPy objects to code, such as
C, Fortran, Javascript, Theano, and Python. These are not discussed in this tutorial.

2.5.2 Setting up Pretty Printing

If all you want is the best pretty printing, use the init_printing() function. This will auto-
matically enable the best printer available in your environment.

>>> from sympy import init_printing

>>> init_printing() # doctest: +SKIP

Quick Tip

You can also change the printer used in SymPy Live. Just change the “Output Format” in
the settings.

If you plan to work in an interactive calculator-type session, the init_session() function will
automatically import everything in SymPy, create some common Symbols, setup plotting, and
run init_printing().

>>> from sympy import init_session

>>> init_session() # doctest: +SKIP

Python console for SymPy 0.7.3 (Python 2.7.5-64-bit) (ground types: gmpy)

These commands were executed:

>>> from __future__ import division
>>> from sympy import *
>>> x, y, z, t = symbols('x y z t')
>>> k, m, n = symbols('k m n', integer=True)
(continues on next page)

2.5. Printing 19
SymPy Documentation, Release 1.3

(continued from previous page)

>>> f, g, h = symbols('f g h', cls=Function)
>>> init_printing() # doctest: +SKIP

Documentation can be found at http://www.sympy.org

>>>

In any case, this is what will happen:

• In the IPython QTConsole, if LATEX is installed, it will enable a printer that uses LATEX.

If LATEX is not installed, but Matplotlib is installed, it will use the Matplotlib rendering
engine. If Matplotlib is not installed, it uses the Unicode pretty printer.
• In the IPython notebook, it will use MathJax to render LATEX.

20 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

• In an IPython console session, or a regular Python session, it will use the Unicode pretty
printer if the terminal supports Unicode.

• In a terminal that does not support Unicode, the ASCII pretty printer is used.

2.5. Printing 21
SymPy Documentation, Release 1.3

To explicitly not use LATEX, pass use_latex=False to init_printing() or init_session().

To explicitly not use Unicode, pass use_unicode=False.

2.5.3 Printing Functions

In addition to automatic printing, you can explicitly use any one of the printers by calling the
appropriate function.

str

To get a string form of an expression, use str(expr). This is also the form that is produced
by print(expr). String forms are designed to be easy to read, but in a form that is correct
Python syntax so that it can be copied and pasted. The str() form of an expression will
usually look exactly the same as the expression as you would enter it.

>>> from sympy import *

>>> x, y, z = symbols('x y z')
>>> str(Integral(sqrt(1/x), x))
'Integral(sqrt(1/x), x)'
>>> print(Integral(sqrt(1/x), x))
Integral(sqrt(1/x), x)

22 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

srepr

The srepr form of an expression is designed to show the exact form of an expression. It will
be discussed more in the Advanced Expression Manipulation (page 60) section. To get it, use
srepr()1 .

>>> srepr(Integral(sqrt(1/x), x))

”Integral(Pow(Pow(Symbol('x'), Integer(-1)), Rational(1, 2)), Tuple(Symbol('x')))”

The srepr form is mostly useful for understanding how an expression is built internally.

ASCII Pretty Printer

The ASCII pretty printer is accessed from pprint(). If the terminal does not support Unicode,
the ASCII printer is used by default. Otherwise, you must pass use_unicode=False.

>>> pprint(Integral(sqrt(1/x), x), use_unicode=False)

/
|
| ___
| / 1
| / - dx
| \/ x
|
/

pprint() prints the output to the screen. If you want the string form, use pretty().

>>> pretty(Integral(sqrt(1/x), x), use_unicode=False)

' / \n | \n | ___ \n | / 1 \n | / - dx\n | \\/ ␣
,→x \n | \n/ '
>>> print(pretty(Integral(sqrt(1/x), x), use_unicode=False))
/
|
| ___
| / 1
| / - dx
| \/ x
|
/

Unicode Pretty Printer

The Unicode pretty printer is also accessed from pprint() and pretty(). If the terminal
supports Unicode, it is used automatically. If pprint() is not able to detect that the terminal
supports unicode, you can pass use_unicode=True to force it to use Unicode.

>>> pprint(Integral(sqrt(1/x), x), use_unicode=True)

⌠
⎮ ___
(continues on next page)
1 SymPy does not use the Python builtin repr() function for repr printing, because in Python str(list) calls

repr() on the elements of the list, and some SymPy functions return lists (such as solve()). Since srepr() is so
verbose, it is unlikely that anyone would want it called by default on the output of solve().

2.5. Printing 23
SymPy Documentation, Release 1.3

(continued from previous page)

⎮ ╱ 1
⎮ ╱ ─ dx
⎮ ╲╱ x
⌡

LATEX

To get the LATEX form of an expression, use latex().

>>> print(latex(Integral(sqrt(1/x), x)))
\int \sqrt{\frac{1}{x}}\, dx

The latex() function has many options to change the formatting of different things. See its
documentation (page 1072) for more details.

MathML

There is also a printer to MathML, called print_mathml(). It must be imported from sympy.
printing.mathml.
>>> from sympy.printing.mathml import print_mathml
>>> print_mathml(Integral(sqrt(1/x), x))
<apply>
<int/>
<bvar>
<ci>x</ci>
</bvar>
<apply>
<root/>
<apply>
<power/>
<ci>x</ci>
<cn>-1</cn>
</apply>
</apply>
</apply>

print_mathml() prints the output. If you want the string, use the function mathml().

Dot

The dotprint() function in sympy.printing.dot prints output to dot format, which can be
rendered with Graphviz. See the Advanced Expression Manipulation (page 60) section for
some examples of the output of this printer.
>>> from sympy.printing.dot import dotprint
>>> from sympy.abc import x
>>> print(dotprint(x+2))
digraph{
# Graph style
”ordering”=”out”
(continues on next page)

24 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

”rankdir”=”TD”
#########
# Nodes #
#########
”Add(Integer(2), Symbol(x))_()” [”color”=”black”, ”label”=”Add”, ”shape”=”ellipse”];
”Integer(2)_(0,)” [”color”=”black”, ”label”=”2”, ”shape”=”ellipse”];
”Symbol(x)_(1,)” [”color”=”black”, ”label”=”x”, ”shape”=”ellipse”];
#########
# Edges #
#########
”Add(Integer(2), Symbol(x))_()” -> ”Integer(2)_(0,)”;
”Add(Integer(2), Symbol(x))_()” -> ”Symbol(x)_(1,)”;
}

2.6 Simplification

To make this document easier to read, we are going to enable pretty printing.

>>> from sympy import *

>>> x, y, z = symbols('x y z')
>>> init_printing(use_unicode=True)

2.6.1 simplify

Now let’s jump in and do some interesting mathematics. One of the most useful features of
a symbolic manipulation system is the ability to simplify mathematical expressions. SymPy
has dozens of functions to perform various kinds of simplification. There is also one general
function called simplify() that attempts to apply all of these functions in an intelligent way
to arrive at the simplest form of an expression. Here are some examples

>>> simplify(sin(x)**2 + cos(x)**2)

1
>>> simplify((x**3 + x**2 - x - 1)/(x**2 + 2*x + 1))
x - 1
>>> simplify(gamma(x)/gamma(x - 2))
(x - 2)⋅(x - 1)

Here, gamma(x) is Γ(x), the gamma function. We see that simplify() is capable of handling
a large class of expressions.
But simplify() has a pitfall. It just applies all the major simplification operations in SymPy,
and uses heuristics to determine the simplest result. But “simplest” is not a well-defined
term. For example, say we wanted to “simplify” x2 + 2x + 1 into (x + 1)2 :

>>> simplify(x**2 + 2*x + 1)

2
x + 2⋅x + 1

We did not get what we want. There is a function to perform this simplification, called fac-
tor(), which will be discussed below.

2.6. Simplification 25
SymPy Documentation, Release 1.3

Another pitfall to simplify() is that it can be unnecessarily slow, since it tries many kinds
of simplifications before picking the best one. If you already know exactly what kind of sim-
plification you are after, it is better to apply the specific simplification function(s) that apply
those simplifications.
Applying specific simplification functions instead of simplify() also has the advantage that
specific functions have certain guarantees about the form of their output. These will be dis-
cussed with each function below. For example, factor(), when called on a polynomial with
rational coefficients, is guaranteed to factor the polynomial into irreducible factors. sim-
plify() has no guarantees. It is entirely heuristical, and, as we saw above, it may even miss
a possible type of simplification that SymPy is capable of doing.
simplify() is best when used interactively, when you just want to whittle down an expres-
sion to a simpler form. You may then choose to apply specific functions once you see what
simplify() returns, to get a more precise result. It is also useful when you have no idea what
form an expression will take, and you need a catchall function to simplify it.

2.6.2 Polynomial/Rational Function Simplification

expand

expand() is one of the most common simplification functions in SymPy. Although it has a lot
of scopes, for now, we will consider its function in expanding polynomial expressions. For
example:

>>> expand((x + 1)**2)

2
x + 2⋅x + 1
>>> expand((x + 2)*(x - 3))
2
x - x - 6

Given a polynomial, expand() will put it into a canonical form of a sum of monomials.
expand() may not sound like a simplification function. After all, by its very name, it makes
expressions bigger, not smaller. Usually this is the case, but often an expression will become
smaller upon calling expand() on it due to cancellation.

>>> expand((x + 1)*(x - 2) - (x - 1)*x)

-2

factor

factor() takes a polynomial and factors it into irreducible factors over the rational numbers.
For example:

>>> factor(x**3 - x**2 + x - 1)

⎛ 2 ⎞
(x - 1)⋅⎝x + 1⎠
>>> factor(x**2*z + 4*x*y*z + 4*y**2*z)
2
z⋅(x + 2⋅y)

26 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

For polynomials, factor() is the opposite of expand(). factor() uses a complete multivari-
ate factorization algorithm over the rational numbers, which means that each of the factors
returned by factor() is guaranteed to be irreducible.
If you are interested in the factors themselves, factor_list returns a more structured output.

>>> factor_list(x**2*z + 4*x*y*z + 4*y**2*z)

(1, [(z, 1), (x + 2⋅y, 2)])

Note that the input to factor and expand need not be polynomials in the strict sense. They
will intelligently factor or expand any kind of expression (though note that the factors may
not be irreducible if the input is no longer a polynomial over the rationals).

>>> expand((cos(x) + sin(x))**2)

2 2
sin (x) + 2⋅sin(x)⋅cos(x) + cos (x)
>>> factor(cos(x)**2 + 2*cos(x)*sin(x) + sin(x)**2)
2
(sin(x) + cos(x))

collect

collect() collects common powers of a term in an expression. For example

>>> expr = x*y + x - 3 + 2*x**2 - z*x**2 + x**3

>>> expr
3 2 2
x - x ⋅z + 2⋅x + x⋅y + x - 3
>>> collected_expr = collect(expr, x)
>>> collected_expr
3 2
x + x ⋅(-z + 2) + x⋅(y + 1) - 3

collect() is particularly useful in conjunction with the .coeff() method. expr.coeff(x,

n) gives the coefficient of x**n in expr:

>>> collected_expr.coeff(x, 2)
-z + 2

cancel

cancel() will take any rational function and put it into the standard canonical form, pq , where
p and q are expanded polynomials with no common factors, and the leading coefficients of p
and q do not have denominators (i.e., are integers).

>>> cancel((x**2 + 2*x + 1)/(x**2 + x))

x + 1
─────
x

>>> expr = 1/x + (3*x/2 - 2)/(x - 4)

>>> expr
3⋅x
(continues on next page)

2.6. Simplification 27
SymPy Documentation, Release 1.3

(continued from previous page)

─── - 2
2 1
─────── + ─
x - 4 x
>>> cancel(expr)
2
3⋅x - 2⋅x - 8
──────────────
2
2⋅x - 8⋅x

>>> expr = (x*y**2 - 2*x*y*z + x*z**2 + y**2 - 2*y*z + z**2)/(x**2 - 1)

>>> expr
2 2 2 2
x⋅y - 2⋅x⋅y⋅z + x⋅z + y - 2⋅y⋅z + z
───────────────────────────────────────
2
x - 1
>>> cancel(expr)
2 2
y - 2⋅y⋅z + z
───────────────
x - 1

Note that since factor() will completely factorize both the numerator and the denominator
of an expression, it can also be used to do the same thing:

>>> factor(expr)
2
(y - z)
────────
x - 1

However, if you are only interested in making sure that the expression is in canceled form,
cancel() is more efficient than factor().

apart

apart() performs a partial fraction decomposition on a rational function.

>>> expr = (4*x**3 + 21*x**2 + 10*x + 12)/(x**4 + 5*x**3 + 5*x**2 + 4*x)

>>> expr
3 2
4⋅x + 21⋅x + 10⋅x + 12
────────────────────────
4 3 2
x + 5⋅x + 5⋅x + 4⋅x
>>> apart(expr)
2⋅x - 1 1 3
────────── - ───── + ─
2 x + 4 x
x + x + 1

28 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

2.6.3 Trigonometric Simplification

Note: SymPy follows Python’s naming conventions for inverse trigonometric functions,
which is to append an a to the front of the function’s name. For example, the inverse co-
sine, or arc cosine, is called acos().

>>> acos(x)
acos(x)
>>> cos(acos(x))
x
>>> asin(1)
π
─
2

trigsimp

To simplify expressions using trigonometric identities, use trigsimp().

>>> trigsimp(sin(x)**2 + cos(x)**2)

1
>>> trigsimp(sin(x)**4 - 2*cos(x)**2*sin(x)**2 + cos(x)**4)
cos(4⋅x) 1
──────── + ─
2 2
>>> trigsimp(sin(x)*tan(x)/sec(x))
2
sin (x)

trigsimp() also works with hyperbolic trig functions.

>>> trigsimp(cosh(x)**2 + sinh(x)**2)

cosh(2⋅x)
>>> trigsimp(sinh(x)/tanh(x))
cosh(x)

Much like simplify(), trigsimp() applies various trigonometric identities to the input ex-
pression, and then uses a heuristic to return the “best” one.

expand_trig

To expand trigonometric functions, that is, apply the sum or double angle identities, use
expand_trig().

>>> expand_trig(sin(x + y))

sin(x)⋅cos(y) + sin(y)⋅cos(x)
>>> expand_trig(tan(2*x))
2⋅tan(x)
─────────────
2
- tan (x) + 1

2.6. Simplification 29
SymPy Documentation, Release 1.3

Because expand_trig() tends to make trigonometric expressions larger, and trigsimp()

tends to make them smaller, these identities can be applied in reverse using trigsimp()
>>> trigsimp(sin(x)*cos(y) + sin(y)*cos(x))
sin(x + y)

2.6.4 Powers

Before we introduce the power simplification functions, a mathematical discussion on the

identities held by powers is in order. There are three kinds of identities satisfied by exponents
1. xa xb = xa+b
2. xa y a = (xy)a
3. (xa )b = xab
Identity 1 is always true.
√ √
Identity 2 is not always true. For example, if x = y = −1 and a = 21 , then xa y a = −1 −1 =
√ √
i · i = −1, whereas (xy)a = −1 · −1 = 1 = 1. However, identity 2 is true at least if x and y
are nonnegative and a is real (it may also be true√ under other conditions as well). A common
√ √
consequence of the failure of identity 2 is that x y ̸= xy.
( )1/2
Identity 3 is not always true. For example, if x = −1, a = 2, and b = 12 , then (xa )b = (−1)2 =
√
1 = 1 and xab = (−1)2·1/2 = (−1)1 = −1. However, identity 3 is true when b is an integer (again,
it may also hold in other cases √ as well). Two common consequences of the failure of identity
√
3 are that x2 ̸= x and that x1 ̸= √1x .

To summarize

Identity Sufficient conditions Counterexample Important conse-

to hold when conditions are quences
not met
Always true None None
1. xa xb = xa+b
√ √ √
a a a
x, y ≥ 0 and a ∈ R (−1)1/2 (−1)1/2 ̸= (−1 · x y ̸= xy in gen-
2. x y = (xy) −1)1/2 eral
( )1/2 √ √
a b ab
b∈Z (−1)2 ̸= (−1)2·1/2 x2 ̸= x and x1 ̸= √1x
3. (x ) = x
in general

This is important to remember, because by default, SymPy will not perform simplifications if
they are not true in general.
In order to make SymPy perform simplifications involving identities that are only true under
certain assumptions, we need to put assumptions on our Symbols. We will undertake a full
discussion of the assumptions system later, but for now, all we need to know are the following.
• By default, SymPy Symbols are assumed to be complex (elements of C). That is, a sim-
plification will not be applied to an expression with a given Symbol unless it holds for all
complex numbers.
• Symbols can be given different assumptions by passing the assumption to symbols().
For the rest of this section, we will be assuming that x and y are positive, and that a and

30 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

b are real. We will leave z, t, and c as arbitrary complex Symbols to demonstrate what
happens in that case.

>>> x, y = symbols('x y', positive=True)

>>> a, b = symbols('a b', real=True)
>>> z, t, c = symbols('z t c')

Note: In SymPy, sqrt(x) is just a shortcut to x**Rational(1, 2). They are exactly the
same object.

>>> sqrt(x) == x**Rational(1, 2)

True

powsimp

powsimp() applies identities 1 and 2 from above, from left to right.

>>> powsimp(x**a*x**b)
a + b
x
>>> powsimp(x**a*y**a)
a
(x⋅y)

Notice that powsimp() refuses to do the simplification if it is not valid.

>>> powsimp(t**c*z**c)
c c
t ⋅z

If you know that you want to apply this simplification, but you don’t want to mess with as-
sumptions, you can pass the force=True flag. This will force the simplification to take place,
regardless of assumptions.

>>> powsimp(t**c*z**c, force=True)

c
(t⋅z)

Note that in some instances, in particular, when the exponents are integers or rational num-
bers, and identity 2 holds, it will be applied automatically.

>>> (z*t)**2
2 2
t ⋅z
>>> sqrt(x*y)
√x⋅√y

This means that it will be impossible to undo this identity with powsimp(), because even if
powsimp() were to put the bases together, they would be automatically split apart again.

>>> powsimp(z**2*t**2)
2 2
t ⋅z
(continues on next page)

2.6. Simplification 31
SymPy Documentation, Release 1.3

(continued from previous page)

>>> powsimp(sqrt(x)*sqrt(y))
√x⋅√y

expand_power_exp / expand_power_base

expand_power_exp() and expand_power_base() apply identities 1 and 2 from right to left,

respectively.

>>> expand_power_exp(x**(a + b))

a b
x ⋅x

>>> expand_power_base((x*y)**a)
a a
x ⋅y

As with powsimp(), identity 2 is not applied if it is not valid.

>>> expand_power_base((z*t)**c)
c
(t⋅z)

And as with powsimp(), you can force the expansion to happen without fiddling with assump-
tions by using force=True.

>>> expand_power_base((z*t)**c, force=True)

c c
t ⋅z

As with identity 2, identity 1 is applied automatically if the power is a number, and hence
cannot be undone with expand_power_exp().

>>> x**2*x**3
5
x
>>> expand_power_exp(x**5)
5
x

powdenest

powdenest() applies identity 3, from left to right.

>>> powdenest((x**a)**b)
a⋅b
x

As before, the identity is not applied if it is not true under the given assumptions.

>>> powdenest((z**a)**b)
b
(continues on next page)

32 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

⎛ a⎞
⎝z ⎠

And as before, this can be manually overridden with force=True.

>>> powdenest((z**a)**b, force=True)

a⋅b
z

2.6.5 Exponentials and logarithms

Note: In SymPy, as in Python and most programming languages, log is the natural logarithm,
also known as ln. SymPy automatically provides an alias ln = log in case you forget this.

>>> ln(x)
log(x)

Logarithms have similar issues as powers. There are two main identities
1. log (xy) = log (x) + log (y)
2. log (xn ) = n log (x)
Neither identity is true for arbitrary complex x and y, due to the branch cut in the complex
plane for the complex logarithm. However, sufficient conditions for the identities to hold are
if x and y are positive and n is real.

>>> x, y = symbols('x y', positive=True)

>>> n = symbols('n', real=True)

As before, z and t will be Symbols with no additional assumptions.

( ) ( )
Note that the identity log xy = log(x)−log(y) is a special case of identities 1 and 2 by log xy =
( ) ( )
log x · y1 = log(x) + log y −1 = log(x) − log(y), and thus it also holds if x and y are positive,
but may not hold in general.
We also see that log (ex ) = x comes from log (ex ) = x log(e) = x, and thus holds when x is real
(and
( it can
) be verified that it does not hold in general for arbitrary complex x, for example,
log ex+2πi = log (ex ) = x ̸= x + 2πi).

expand_log

To apply identities 1 and 2 from left to right, use expand_log(). As always, the identities will
not be applied unless they are valid.

>>> expand_log(log(x*y))
log(x) + log(y)
>>> expand_log(log(x/y))
log(x) - log(y)
>>> expand_log(log(x**2))
(continues on next page)

2.6. Simplification 33
SymPy Documentation, Release 1.3

(continued from previous page)

2⋅log(x)
>>> expand_log(log(x**n))
n⋅log(x)
>>> expand_log(log(z*t))
log(t⋅z)

As with powsimp() and powdenest(), expand_log() has a force option that can be used to
ignore assumptions.

>>> expand_log(log(z**2))
⎛ 2⎞
log⎝z ⎠
>>> expand_log(log(z**2), force=True)
2⋅log(z)

logcombine

To apply identities 1 and 2 from right to left, use logcombine().

>>> logcombine(log(x) + log(y))

log(x⋅y)
>>> logcombine(n*log(x))
⎛ n⎞
log⎝x ⎠
>>> logcombine(n*log(z))
n⋅log(z)

logcombine() also has a force option that can be used to ignore assumptions.

>>> logcombine(n*log(z), force=True)

⎛ n⎞
log⎝z ⎠

2.6.6 Special Functions

SymPy implements dozens of special functions, ranging from functions in combinatorics to

mathematical physics.
An extensive list of the special functions included with SymPy and their documentation is at
the Functions Module (page 447) page.
For the purposes of this tutorial, let’s introduce a few special functions in SymPy.
Let’s define x, y, and z as regular, complex Symbols, removing any assumptions we put on
them in the previous section. We will also define k, m, and n.

>>> x, y, z = symbols('x y z')

>>> k, m, n = symbols('k m n')

The factorial function is factorial. factorial(n) represents n! = 1 · 2 · · · (n − 1) · n. n! repre-

sents the number of permutations of n distinct items.

34 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> factorial(n)
n!
( )
The binomial coefficient function is binomial. binomial(n, k) represents nk , the number
of ways to choose k items from a set of n distinct items. It is also often written as nCk, and is
pronounced “n choose k”.

>>> binomial(n, k)
⎛n⎞
⎜ ⎟
⎝k⎠

The factorial
∫∞ function is closely related to the gamma function, gamma. gamma(z) represents
Γ(z) = 0 tz−1 e−t dt, which for positive integer z is the same as (z − 1)!.

>>> gamma(z)
Γ(z)

The generalized hypergeometric

( function
) is hyper. hyper([a_1, ..., a_p], [b_1, ...,
a1 , · · · , ap
b_q], z) represents p Fq z . The most common case is 2 F1 , which is often referred
b1 , · · · , b q
to as the ordinary hypergeometric function.

>>> hyper([1, 2], [3], z)

┌─ ⎛1, 2 │ ⎞
├─ ⎜ │ z⎟
2╵ 1 ⎝ 3 │ ⎠

rewrite

A common way to deal with special functions is to rewrite them in terms of one another. This
works for any function in SymPy, not just special functions. To rewrite an expression in terms
of a function, use expr.rewrite(function). For example,

>>> tan(x).rewrite(sin)
2
2⋅sin (x)
─────────
sin(2⋅x)
>>> factorial(x).rewrite(gamma)
Γ(x + 1)

For some tips on applying more targeted rewriting, see the Advanced Expression Manipula-
tion (page 60) section.

expand_func

To expand special functions in terms of some identities, use expand_func(). For example

>>> expand_func(gamma(x + 3))

x⋅(x + 1)⋅(x + 2)⋅Γ(x)

2.6. Simplification 35
SymPy Documentation, Release 1.3

hyperexpand

To rewrite hyper in terms of more standard functions, use hyperexpand().

>>> hyperexpand(hyper([1, 1], [2], z))

-log(-z + 1)
─────────────
z

hyperexpand() also works on the more general Meijer G-function (see its documentation
(page 555) for more information).

>>> expr = meijerg([[1],[1]], [[1],[]], -z)

>>> expr
╭─╮1, 1 ⎛1 1 │ ⎞
│╶┐ ⎜ │ -z⎟
╰─╯2, 1 ⎝1 │ ⎠
>>> hyperexpand(expr)
1
─
z
e

combsimp

To simplify combinatorial expressions, use combsimp().

>>> n, k = symbols('n k', integer = True)

>>> combsimp(factorial(n)/factorial(n - 3))
n⋅(n - 2)⋅(n - 1)
>>> combsimp(binomial(n+1, k+1)/binomial(n, k))
n + 1
─────
k + 1

gammasimp

To simplify expressions with gamma functions or combinatorial functions with non-integer

argument, use gammasimp().

>>> gammasimp(gamma(x)*gamma(1 - x))

π
────────
sin(π⋅x)

36 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

2.6.7 Example: Continued Fractions

Let’s use SymPy to explore continued fractions. A continued fraction is an expression of the
form
1
a0 +
1
a1 +
1
a2 +
.. 1
.+
an

where a0 , . . . , an are integers, and a1 , . . . , an are positive. A continued fraction can also be infi-
nite, but infinite objects are more difficult to represent in computers, so we will only examine
the finite case here.
A continued fraction of the above form is often represented as a list [a0 ; a1 , . . . , an ]. Let’s write
a simple function that converts such a list to its continued fraction form. The easiest way
to construct a continued fraction from a list is to work backwards. Note that despite the
apparent symmetry of the definition, the first element, a0 , must usually be handled differently
from the rest.

>>> def list_to_frac(l):

... expr = Integer(0)
... for i in reversed(l[1:]):
... expr += i
... expr = 1/expr
... return l[0] + expr
>>> list_to_frac([x, y, z])
1
x + ─────
1
y + ─
z

We use Integer(0) in list_to_frac so that the result will always be a SymPy object, even if
we only pass in Python ints.

>>> list_to_frac([1, 2, 3, 4])

43
──
30

Every finite continued fraction is a rational number, but we are interested in symbolics here,
so let’s create a symbolic continued fraction. The symbols() function that we have been using
has a shortcut to create numbered symbols. symbols('a0:5') will create the symbols a0, a1,
…, a4.

>>> syms = symbols('a0:5')

>>> syms
(a0 , a1 , a2 , a3 , a4 )
>>> a0, a1, a2, a3, a4 = syms
>>> frac = list_to_frac(syms)
>>> frac
1
a0 + ─────────────────
1
(continues on next page)

2.6. Simplification 37
SymPy Documentation, Release 1.3

(continued from previous page)

a1 + ────────────
1
a2 + ───────
1
a3 + ──
a4

This form is useful for understanding continued fractions, but lets put it into standard rational
function form using cancel().
>>> frac = cancel(frac)
>>> frac
a0 ⋅a1 ⋅a2 ⋅a3 ⋅a4 + a0 ⋅a1 ⋅a2 + a0 ⋅a1 ⋅a4 + a0 ⋅a3 ⋅a4 + a0 + a2 ⋅a3 ⋅a4 + a2 + a4
─────────────────────────────────────────────────────────────────────────
a1 ⋅a2 ⋅a3 ⋅a4 + a1 ⋅a2 + a1 ⋅a4 + a3 ⋅a4 + 1

Now suppose we were given frac in the above canceled form. In fact, we might be given the
fraction in any form, but we can always put it into the above canonical form with cancel().
Suppose that we knew that it could be rewritten as a continued fraction. How could we do
this with SymPy? A continued fraction is recursively c + f1 , where c is an integer and f is
a (smaller) continued fraction. If we could write the expression in this form, we could pull
out each c recursively and add it to a list. We could then get a continued fraction with our
list_to_frac() function.
The key observation here is that we can convert an expression to the form c + f1 by doing a
partial fraction decomposition with respect to c. This is because f does not contain c. This
means we need to use the apart() function. We use apart() to pull the term out, then
subtract it from the expression, and take the reciprocal to get the f part.
>>> l = []
>>> frac = apart(frac, a0)
>>> frac
a2 ⋅a3 ⋅a4 + a2 + a4
a0 + ───────────────────────────────────────
a1 ⋅a2 ⋅a3 ⋅a4 + a1 ⋅a2 + a1 ⋅a4 + a3 ⋅a4 + 1
>>> l.append(a0)
>>> frac = 1/(frac - a0)
>>> frac
a1 ⋅a2 ⋅a3 ⋅a4 + a1 ⋅a2 + a1 ⋅a4 + a3 ⋅a4 + 1
───────────────────────────────────────
a2 ⋅a3 ⋅a4 + a2 + a4

Now we repeat this process

>>> frac = apart(frac, a1)
>>> frac
a3 ⋅a4 + 1
a1 + ──────────────────
a2 ⋅a3 ⋅a4 + a2 + a4
>>> l.append(a1)
>>> frac = 1/(frac - a1)
>>> frac = apart(frac, a2)
>>> frac
a4
a2 + ─────────
a3 ⋅a4 + 1
(continues on next page)

38 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> l.append(a2)
>>> frac = 1/(frac - a2)
>>> frac = apart(frac, a3)
>>> frac
1
a3 + ──
a4
>>> l.append(a3)
>>> frac = 1/(frac - a3)
>>> frac = apart(frac, a4)
>>> frac
a4
>>> l.append(a4)
>>> list_to_frac(l)
1
a0 + ─────────────────
1
a1 + ────────────
1
a2 + ───────
1
a3 + ──
a4

Quick Tip

You can execute multiple lines at once in SymPy Live. Typing Shift-Enter instead of Enter
will enter a newline instead of executing.

Of course, this exercise seems pointless, because we already know that our frac is
list_to_frac([a0, a1, a2, a3, a4]). So try the following exercise. Take a list of sym-
bols and randomize them, and create the canceled continued fraction, and see if you can
reproduce the original list. For example

>>> import random

>>> l = list(symbols('a0:5'))
>>> random.shuffle(l)
>>> orig_frac = frac = cancel(list_to_frac(l))
>>> del l

Click on “Run code block in SymPy Live” on the definition of list_to_frac() above, and
then on the above example, and try to reproduce l from frac. I have deleted l at the
end to remove the temptation for peeking (you can check your answer at the end by call-
ing cancel(list_to_frac(l)) on the list that you generate at the end, and comparing it to
orig_frac.
See if you can think of a way to figure out what symbol to pass to apart() at each stage (hint:
1
think of what happens to a0 in the formula a0 + a1 +··· when it is canceled).

2.6. Simplification 39
SymPy Documentation, Release 1.3

2.7 Calculus

This section covers how to do basic calculus tasks such as derivatives, integrals, limits, and
series expansions in SymPy. If you are not familiar with the math of any part of this section,
you may safely skip it.

>>> from sympy import *

>>> x, y, z = symbols('x y z')
>>> init_printing(use_unicode=True)

2.7.1 Derivatives

To take derivatives, use the diff function.

>>> diff(cos(x), x)
-sin(x)
>>> diff(exp(x**2), x)
⎛ 2⎞
⎝x ⎠
2⋅x⋅e

diff can take multiple derivatives at once. To take multiple derivatives, pass the variable as
many times as you wish to differentiate, or pass a number after the variable. For example,
both of the following find the third derivative of x4 .

>>> diff(x**4, x, x, x)
24⋅x
>>> diff(x**4, x, 3)
24⋅x

You can also take derivatives with respect to many variables at once. Just pass each derivative
in order, using the same syntax as for single variable derivatives. For example, each of the
7
following will compute ∂x∂y∂ 2 ∂z4 exyz .

>>> expr = exp(x*y*z)

>>> diff(expr, x, y, y, z, z, z, z)
3 2 ⎛ 3 3 3 2 2 2 ⎞ x⋅y⋅z
x ⋅y ⋅⎝x ⋅y ⋅z + 14⋅x ⋅y ⋅z + 52⋅x⋅y⋅z + 48⎠⋅e
>>> diff(expr, x, y, 2, z, 4)
3 2 ⎛ 3 3 3 2 2 2 ⎞ x⋅y⋅z
x ⋅y ⋅⎝x ⋅y ⋅z + 14⋅x ⋅y ⋅z + 52⋅x⋅y⋅z + 48⎠⋅e
>>> diff(expr, x, y, y, z, 4)
3 2 ⎛ 3 3 3 2 2 2 ⎞ x⋅y⋅z
x ⋅y ⋅⎝x ⋅y ⋅z + 14⋅x ⋅y ⋅z + 52⋅x⋅y⋅z + 48⎠⋅e

diff can also be called as a method. The two ways of calling diff are exactly the same, and
are provided only for convenience.

>>> expr.diff(x, y, y, z, 4)
3 2 ⎛ 3 3 3 2 2 2 ⎞ x⋅y⋅z
x ⋅y ⋅⎝x ⋅y ⋅z + 14⋅x ⋅y ⋅z + 52⋅x⋅y⋅z + 48⎠⋅e

To create an unevaluated derivative, use the Derivative class. It has the same syntax as
diff.

40 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> deriv = Derivative(expr, x, y, y, z, 4)

>>> deriv
7
∂ ⎛ x⋅y⋅z⎞
──────────⎝e ⎠
4 2
∂z ∂y ∂x

To evaluate an unevaluated derivative, use the doit method.

>>> deriv.doit()
3 2 ⎛ 3 3 3 2 2 2 ⎞ x⋅y⋅z
x ⋅y ⋅⎝x ⋅y ⋅z + 14⋅x ⋅y ⋅z + 52⋅x⋅y⋅z + 48⎠⋅e

These unevaluated objects are useful for delaying the evaluation of the derivative, or for print-
ing purposes. They are also used when SymPy does not know how to compute the derivative
of an expression (for example, if it contains an undefined function, which are described in the
Solving Differential Equations (page 49) section).
Derivatives of unspecified order can be created using tuple (x, n) where n is the order of
the derivative with respect to x.
>>> m, n, a, b = symbols('m n a b')
>>> expr = (a*x + b)**m
>>> expr.diff((x, n))
n
∂ ⎛ m⎞
───⎝(a⋅x + b) ⎠
n
∂x

2.7.2 Integrals

To compute an integral, use the integrate function. There are two kinds of integrals, definite
and indefinite. To compute an indefinite integral, that is, an antiderivative, or primitive, just
pass the variable after the expression.
>>> integrate(cos(x), x)
sin(x)

Note that SymPy does not include the constant of integration. If you want it, you can add
one yourself, or rephrase your problem as a differential equation and use dsolve to solve it,
which does add the constant (see Solving Differential Equations (page 49)).

Quick Tip

∞ in SymPy is oo (that’s the lowercase letter “oh” twice). This is because oo looks like ∞,
and is easy to type.

To compute a definite integral, pass the argument (integration_variable, lower_limit,

upper_limit). For example, to compute
∫ ∞
e−x dx,
0

2.7. Calculus 41
SymPy Documentation, Release 1.3

we would do

>>> integrate(exp(-x), (x, 0, oo))

1

As with indefinite integrals, you can pass multiple limit tuples to perform a multiple integral.
For example, to compute
∫ ∞∫ ∞
e−x −y dx dy,
2 2

−∞ −∞

do

>>> integrate(exp(-x**2 - y**2), (x, -oo, oo), (y, -oo, oo))

π

If integrate is unable to compute an integral, it returns an unevaluated Integral object.

>>> expr = integrate(x**x, x)

>>> print(expr)
Integral(x**x, x)
>>> expr
⌠
⎮ x
⎮ x dx
⌡

As with Derivative, you can create an unevaluated integral using Integral. To later evaluate
this integral, call doit.

>>> expr = Integral(log(x)**2, x)

>>> expr
⌠
⎮ 2
⎮ log (x) dx
⌡
>>> expr.doit()
2
x⋅log (x) - 2⋅x⋅log(x) + 2⋅x

integrate uses powerful algorithms that are always improving to compute both definite and
indefinite integrals, including heuristic pattern matching type algorithms, a partial imple-
mentation of the Risch algorithm, and an algorithm using Meijer G-functions that is useful
for computing integrals in terms of special functions, especially definite integrals. Here is a
sampling of some of the power of integrate.

>>> integ = Integral((x**4 + x**2*exp(x) - x**2 - 2*x*exp(x) - 2*x -

... exp(x))*exp(x)/((x - 1)**2*(x + 1)**2*(exp(x) + 1)), x)
>>> integ
⌠
⎮ ⎛ 4 2 x 2 x x⎞ x
⎮ ⎝x + x ⋅e - x - 2⋅x⋅e - 2⋅x - e ⎠⋅e
⎮ ──────────────────────────────────────── dx
⎮ 2 2 ⎛ x ⎞
⎮ (x - 1) ⋅(x + 1) ⋅⎝e + 1⎠
⌡
(continues on next page)

42 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> integ.doit()
x
⎛ x ⎞ e
log⎝e + 1⎠ + ──────
2
x - 1

>>> integ = Integral(sin(x**2), x)

>>> integ
⌠
⎮ ⎛ 2⎞
⎮ sin⎝x ⎠ dx
⌡
>>> integ.doit()
⎛√2⋅x⎞
3⋅√2⋅√π⋅fresnels⎜────⎟⋅Γ(3/4)
⎝ √π ⎠
─────────────────────────────
8⋅Γ(7/4)

>>> integ = Integral(x**y*exp(-x), (x, 0, oo))

>>> integ
∞
⌠
⎮ y -x
⎮ x ⋅e dx
⌡
0
>>> integ.doit()
⎧ Γ(y + 1) for -re(y) < 1
⎪
⎪∞
⎪⌠
⎨⎮ y -x
⎪⎮ x ⋅e dx otherwise
⎪⌡
⎪0
⎩

This last example returned a Piecewise expression because the integral does not converge
unless ℜ(y) > 1.

2.7.3 Limits

SymPy can compute symbolic limits with the limit function. The syntax to compute

lim f (x)
x→x0

is limit(f(x), x, x0).

>>> limit(sin(x)/x, x, 0)
1

2.7. Calculus 43
SymPy Documentation, Release 1.3

limit should be used instead of subs whenever the point of evaluation is a singularity. Even
though SymPy has objects to represent ∞, using them for evaluation is not reliable because
they do not keep track of things like rate of growth. Also, things like ∞ − ∞ and ∞
∞ return nan
(not-a-number). For example
>>> expr = x**2/exp(x)
>>> expr.subs(x, oo)
nan
>>> limit(expr, x, oo)
0

Like Derivative and Integral, limit has an unevaluated counterpart, Limit. To evaluate
it, use doit.
>>> expr = Limit((cos(x) - 1)/x, x, 0)
>>> expr
⎛cos(x) - 1⎞
lim ⎜──────────⎟
x─→0⁺⎝ x ⎠
>>> expr.doit()
0

To evaluate a limit at one side only, pass '+' or '-' as a third argument to limit. For example,
to compute
1
lim ,
x→0+ x
do
>>> limit(1/x, x, 0, '+')
∞

As opposed to
>>> limit(1/x, x, 0, '-')
-∞

2.7.4 Series Expansion

SymPy can compute asymptotic series expansions of functions around a point. To compute
the expansion of f (x) around the point x = x0 terms of order xn , use f(x).series(x, x0, n).
x0 and n can be omitted, in which case the defaults x0=0 and n=6 will be used.
>>> expr = exp(sin(x))
>>> expr.series(x, 0, 4)
2
x ⎛ 4⎞
1 + x + ── + O⎝x ⎠
2
( )
The O x4 term at the end represents the Landau order term at x = 0 (not to be confused with
big O notation used in computer science, which generally represents the Landau order term
at x = ∞). It means that all x terms with power greater than or equal to x4 are omitted. Order
terms can be created and manipulated outside of series. They automatically absorb higher
order terms.

44 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> x + x**3 + x**6 + O(x**4)

3 ⎛ 4⎞
x + x + O⎝x ⎠
>>> x*O(1)
O(x)

If you do not want the order term, use the removeO method.

>>> expr.series(x, 0, 4).removeO()

2
x
── + x + 1
2

The O notation supports arbitrary limit points (other than 0):

>>> exp(x - 6).series(x, x0=6)

2 3 4 5
(x - 6) (x - 6) (x - 6) (x - 6) ⎛ 6 ⎞
-5 + ──────── + ──────── + ──────── + ──────── + x + O⎝(x - 6) ; x → 6⎠
2 6 24 120

2.7.5 Finite differences

So far we have looked at expressions with analytic derivatives and primitive functions respec-
tively. But what if we want to have an expression to estimate a derivative of a curve for which
we lack a closed form representation, or for which we don’t know the functional values for
yet. One approach would be to use a finite difference approach.
The simplest way the differentiate using finite differences is to use the differentiate_finite
function:

>>> f, g = symbols('f g', cls=Function)

>>> differentiate_finite(f(x)*g(x))
-f(x - 1/2)⋅g(x - 1/2) + f(x + 1/2)⋅g(x + 1/2)

If we want to expand the intermediate derivative we may pass the flag evaluate=True:

>>> differentiate_finite(f(x)*g(x), evaluate=True)

(-f(x - 1/2) + f(x + 1/2))⋅g(x) + (-g(x - 1/2) + g(x + 1/2))⋅f(x)

This form however does not respect the product rule.

If you already have a Derivative instance, you can use the as_finite_difference method
to generate approximations of the derivative to arbitrary order:

>>> f = Function('f')
>>> dfdx = f(x).diff(x)
>>> dfdx.as_finite_difference()
-f(x - 1/2) + f(x + 1/2)

here the first order derivative was approximated around x using a minimum number of points
(2 for 1st order derivative) evaluated equidistantly using a step-size of 1. We can use arbitrary
steps (possibly containing symbolic expressions):

2.7. Calculus 45
SymPy Documentation, Release 1.3

>>> f = Function('f')
>>> d2fdx2 = f(x).diff(x, 2)
>>> h = Symbol('h')
>>> d2fdx2.as_finite_difference([-3*h,-h,2*h])
f(-3⋅h) f(-h) 2⋅f(2⋅h)
─────── - ───── + ────────
2 2 2
5⋅h 3⋅h 15⋅h

If you are just interested in evaluating the weights, you can do so manually:

>>> finite_diff_weights(2, [-3, -1, 2], 0)[-1][-1]

[1/5, -1/3, 2/15]

note that we only need the last element in the last sublist returned from fi-
nite_diff_weights. The reason for this is that the function also generates weights for lower
derivatives and using fewer points (see the documentation of finite_diff_weights for more
details).
If using finite_diff_weights directly looks complicated, and the as_finite_difference
method of Derivative instances is not flexible enough, you can use apply_finite_diff
which takes order, x_list, y_list and x0 as parameters:

>>> x_list = [-3, 1, 2]

>>> y_list = symbols('a b c')
>>> apply_finite_diff(1, x_list, y_list, 0)
3⋅a b 2⋅c
- ─── - ─ + ───
20 4 5

2.8 Solvers

>>> from sympy import *

>>> x, y, z = symbols('x y z')
>>> init_printing(use_unicode=True)

2.8.1 A Note about Equations

Recall from the gotchas (page 12) section of this tutorial that symbolic equations in SymPy
are not represented by = or ==, but by Eq.

>>> Eq(x, y)
x = y

However, there is an even easier way. In SymPy, any expression not in an Eq is automatically
assumed to equal 0 by the solving functions. Since a = b if and only if a − b = 0, this means
that instead of using x == y, you can just use x - y. For example

>>> solveset(Eq(x**2, 1), x)

{-1, 1}
>>> solveset(Eq(x**2 - 1, 0), x)
(continues on next page)

46 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

{-1, 1}
>>> solveset(x**2 - 1, x)
{-1, 1}

This is particularly useful if the equation you wish to solve is already equal to 0. Instead of
typing solveset(Eq(expr, 0), x), you can just use solveset(expr, x).

2.8.2 Solving Equations Algebraically

The main function for solving algebraic equations is solveset. The syntax for solveset is
solveset(equation, variable=None, domain=S.Complexes) Where equations may be in
the form of Eq instances or expressions that are assumed to be equal to zero.
Please note that there is another function called solve which can also be used to solve equa-
tions. The syntax is solve(equations, variables) However, it is recommended to use
solveset instead.
When solving a single equation, the output of solveset is a FiniteSet or an Interval or
ImageSet of the solutions.

>>> solveset(x**2 - x, x)
{0, 1}
>>> solveset(x - x, x, domain=S.Reals)
ℝ
>>> solveset(sin(x) - 1, x, domain=S.Reals)
⎧ π ⎫
⎨2⋅n⋅π + ─ | n ∊ ℤ⎬
⎩ 2 ⎭

If there are no solutions, an EmptySet is returned and if it is not able to find solutions then a
ConditionSet is returned.

>>> solveset(exp(x), x) # No solution exists

∅
>>> solveset(cos(x) - x, x) # Not able to find solution
{x | x ∊ ℂ ∧ -x + cos(x) = 0}

In the solveset module, the linear system of equations is solved using linsolve. In future we
would be able to use linsolve directly from solveset. Following is an example of the syntax
of linsolve.
• List of Equations Form:

>>> linsolve([x + y + z - 1, x + y + 2*z - 3 ], (x, y, z))

{(-y - 1, y, 2)}

• Augmented Matrix Form:

>>> linsolve(Matrix(([1, 1, 1, 1], [1, 1, 2, 3])), (x, y, z))

{(-y - 1, y, 2)}

• A*x = b Form

2.8. Solvers 47
SymPy Documentation, Release 1.3

>>> M = Matrix(((1, 1, 1, 1), (1, 1, 2, 3)))

>>> system = A, b = M[:, :-1], M[:, -1]
>>> linsolve(system, x, y, z)
{(-y - 1, y, 2)}

Note: The order of solution corresponds the order of given symbols.

In the solveset module, the non linear system of equations is solved using nonlinsolve.
Following are examples of nonlinsolve.
1. When only real solution is present:

>>> a, b, c, d = symbols('a, b, c, d', real=True)

>>> nonlinsolve([a**2 + a, a - b], [a, b])
{(-1, -1), (0, 0)}
>>> nonlinsolve([x*y - 1, x - 2], x, y)
{(2, 1/2)}

2. When only complex solution is present:

>>> nonlinsolve([x**2 + 1, y**2 + 1], [x, y])

{(-i, -i), (-i, i), (i, -i), (i, i)}

3. When both real and complex solution is present:

>>> from sympy import sqrt

>>> system = [x**2 - 2*y**2 -2, x*y - 2]
>>> vars = [x, y]
>>> nonlinsolve(system, vars)
{(-2, -1), (2, 1), (-√2⋅i, √2⋅i), (√2⋅i, -√2⋅i)}

>>> n = Dummy('n')
>>> system = [exp(x) - sin(y), 1/y - 3]
>>> real_soln = (log(sin(S(1)/3)), S(1)/3)
>>> img_lamda = Lambda(n, 2*n*I*pi + Mod(log(sin(S(1)/3)), 2*I*pi))
>>> complex_soln = (ImageSet(img_lamda, S.Integers), S(1)/3)
>>> soln = FiniteSet(real_soln, complex_soln)
>>> nonlinsolve(system, [x, y]) == soln
True

4. If non linear system of equations is Positive dimensional system (A system with infinitely
many solutions is said to be positive-dimensional):

>>> nonlinsolve([x*y, x*y - x], [x, y])

{(0, y)}

>>> system = [a**2 + a*c, a - b]

>>> nonlinsolve(system, [a, b])
{(0, 0), (-c, -c)}

Note:
1. The order of solution corresponds the order of given symbols.

48 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

2. Currently nonlinsolve doesn’t return solution in form of LambertW (if there is solution
present in the form of LambertW).
solve can be used for such cases:

>>> solve([x**2 - y**2/exp(x)], [x, y], dict=True)

⎡⎧ ⎛y⎞⎫⎤
⎢⎨x: 2⋅LambertW⎜─⎟⎬⎥
⎣⎩ ⎝2⎠⎭⎦

3. Currently nonlinsolve is not properly capable of solving the system of equations having
trigonometric functions.
solve can be used for such cases(not all solution):

>>> solve([sin(x + y), cos(x - y)], [x, y])

⎡⎛-3⋅π 3⋅π⎞ ⎛-π π⎞ ⎛π 3⋅π⎞ ⎛3⋅π π⎞⎤
⎢⎜─────, ───⎟, ⎜───, ─⎟, ⎜─, ───⎟, ⎜───, ─⎟⎥
⎣⎝ 4 4 ⎠ ⎝ 4 4⎠ ⎝4 4 ⎠ ⎝ 4 4⎠⎦

solveset reports each solution only once. To get the solutions of a polynomial including
multiplicity use roots.

>>> solveset(x**3 - 6*x**2 + 9*x, x)

{0, 3}
>>> roots(x**3 - 6*x**2 + 9*x, x)
{0: 1, 3: 2}

The output {0: 1, 3: 2} of roots means that 0 is a root of multiplicity 1 and 3 is a root of
multiplicity 2.

Note: Currently solveset is not capable of solving the following types of equations:
• Equations solvable by LambertW (Transcendental equation solver).
solve can be used for such cases:

>>> solve(x*exp(x) - 1, x )
[LambertW(1)]

2.8.3 Solving Differential Equations

To solve differential equations, use dsolve. First, create an undefined function by passing
cls=Function to the symbols function.

>>> f, g = symbols('f g', cls=Function)

f and g are now undefined functions. We can call f(x), and it will represent an unknown
function.

>>> f(x)
f(x)

Derivatives of f(x) are unevaluated.

2.8. Solvers 49
SymPy Documentation, Release 1.3

>>> f(x).diff(x)
d
──(f(x))
dx

(see the Derivatives (page 40) section for more on derivatives).

To represent the differential equation f ′′ (x) − 2f ′ (x) + f (x) = sin(x), we would thus use

>>> diffeq = Eq(f(x).diff(x, x) - 2*f(x).diff(x) + f(x), sin(x))

>>> diffeq
2
d d
f(x) - 2⋅──(f(x)) + ───(f(x)) = sin(x)
dx 2
dx

To solve the ODE, pass it and the function to solve for to dsolve.

>>> dsolve(diffeq, f(x))

x cos(x)
f(x) = (C1 + C2 ⋅x)⋅e + ──────
2

dsolve returns an instance of Eq. This is because in general, solutions to differential equa-
tions cannot be solved explicitly for the function.

>>> dsolve(f(x).diff(x)*(1 - sin(f(x))), f(x))

f(x) + cos(f(x)) = C1

The arbitrary constants in the solutions from dsolve are symbols of the form C1, C2, C3, and
so on.

2.9 Matrices

>>> from sympy import *

>>> init_printing(use_unicode=True)

To make a matrix in SymPy, use the Matrix object. A matrix is constructed by providing a list
of row vectors that make up the matrix. For example, to construct the matrix
 
1 −1
 3 4 
0 2
use

>>> Matrix([[1, -1], [3, 4], [0, 2]])

⎡1 -1⎤
⎢ ⎥
⎢3 4 ⎥
⎢ ⎥
⎣0 2 ⎦

To make it easy to make column vectors, a list of elements is considered to be a column vector.

50 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> Matrix([1, 2, 3])

⎡1⎤
⎢ ⎥
⎢2⎥
⎢ ⎥
⎣3⎦

Matrices are manipulated just like any other object in SymPy or Python.

>>> M = Matrix([[1, 2, 3], [3, 2, 1]])

>>> N = Matrix([0, 1, 1])
>>> M*N
⎡5⎤
⎢ ⎥
⎣3⎦

One important thing to note about SymPy matrices is that, unlike every other object in SymPy,
they are mutable. This means that they can be modified in place, as we will see below. The
downside to this is that Matrix cannot be used in places that require immutability, such as
inside other SymPy expressions or as keys to dictionaries. If you need an immutable version
of Matrix, use ImmutableMatrix.

2.9.1 Basic Operations

Shape

Here are some basic operations on Matrix. To get the shape of a matrix use shape

>>> M = Matrix([[1, 2, 3], [-2, 0, 4]])

>>> M
⎡1 2 3⎤
⎢ ⎥
⎣-2 0 4⎦
>>> M.shape
(2, 3)

Accessing Rows and Columns

To get an individual row or column of a matrix, use row or col. For example, M.row(0) will
get the first row. M.col(-1) will get the last column.

>>> M.row(0)
[1 2 3]
>>> M.col(-1)
⎡3⎤
⎢ ⎥
⎣4⎦

2.9. Matrices 51
SymPy Documentation, Release 1.3

Deleting and Inserting Rows and Columns

To delete a row or column, use row_del or col_del. These operations will modify the Matrix
in place.

>>> M.col_del(0)
>>> M
⎡2 3⎤
⎢ ⎥
⎣0 4⎦
>>> M.row_del(1)
>>> M
[2 3]

To insert rows or columns, use row_insert or col_insert. These operations do not operate
in place.

>>> M
[2 3]
>>> M = M.row_insert(1, Matrix([[0, 4]]))
>>> M
⎡2 3⎤
⎢ ⎥
⎣0 4⎦
>>> M = M.col_insert(0, Matrix([1, -2]))
>>> M
⎡1 2 3⎤
⎢ ⎥
⎣-2 0 4⎦

Unless explicitly stated, the methods mentioned below do not operate in place. In general,
a method that does not operate in place will return a new Matrix and a method that does
operate in place will return None.

2.9.2 Basic Methods

As noted above, simple operations like addition and multiplication are done just by using +,
*, and **. To find the inverse of a matrix, just raise it to the -1 power.

>>> M = Matrix([[1, 3], [-2, 3]])

>>> N = Matrix([[0, 3], [0, 7]])
>>> M + N
⎡1 6 ⎤
⎢ ⎥
⎣-2 10⎦
>>> M*N
⎡0 24⎤
⎢ ⎥
⎣0 15⎦
>>> 3*M
⎡3 9⎤
⎢ ⎥
⎣-6 9⎦
>>> M**2
(continues on next page)

52 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

⎡-5 12⎤
⎢ ⎥
⎣-8 3 ⎦
>>> M**-1
⎡1/3 -1/3⎤
⎢ ⎥
⎣2/9 1/9 ⎦
>>> N**-1
Traceback (most recent call last):
...
ValueError: Matrix det == 0; not invertible.

To take the transpose of a Matrix, use T.

>>> M = Matrix([[1, 2, 3], [4, 5, 6]])

>>> M
⎡1 2 3⎤
⎢ ⎥
⎣4 5 6⎦
>>> M.T
⎡1 4⎤
⎢ ⎥
⎢2 5⎥
⎢ ⎥
⎣3 6⎦

2.9.3 Matrix Constructors

Several constructors exist for creating common matrices. To create an identity matrix, use
eye. eye(n) will create an n × n identity matrix.

>>> eye(3)
⎡1 0 0⎤
⎢ ⎥
⎢0 1 0⎥
⎢ ⎥
⎣0 0 1⎦
>>> eye(4)
⎡1 0 0 0⎤
⎢ ⎥
⎢0 1 0 0⎥
⎢ ⎥
⎢0 0 1 0⎥
⎢ ⎥
⎣0 0 0 1⎦

To create a matrix of all zeros, use zeros. zeros(n, m) creates an n × m matrix of 0s.

>>> zeros(2, 3)
⎡0 0 0⎤
⎢ ⎥
⎣0 0 0⎦

2.9. Matrices 53
SymPy Documentation, Release 1.3

Similarly, ones creates a matrix of ones.

>>> ones(3, 2)
⎡1 1⎤
⎢ ⎥
⎢1 1⎥
⎢ ⎥
⎣1 1⎦

To create diagonal matrices, use diag. The arguments to diag can be either numbers or
matrices. A number is interpreted as a 1 × 1 matrix. The matrices are stacked diagonally. The
remaining elements are filled with 0s.

>>> diag(1, 2, 3)
⎡1 0 0⎤
⎢ ⎥
⎢0 2 0⎥
⎢ ⎥
⎣0 0 3⎦
>>> diag(-1, ones(2, 2), Matrix([5, 7, 5]))
⎡-1 0 0 0⎤
⎢ ⎥
⎢0 1 1 0⎥
⎢ ⎥
⎢0 1 1 0⎥
⎢ ⎥
⎢0 0 0 5⎥
⎢ ⎥
⎢0 0 0 7⎥
⎢ ⎥
⎣0 0 0 5⎦

2.9.4 Advanced Methods

Determinant

To compute the determinant of a matrix, use det.

>>> M = Matrix([[1, 0, 1], [2, -1, 3], [4, 3, 2]])

>>> M
⎡1 0 1⎤
⎢ ⎥
⎢2 -1 3⎥
⎢ ⎥
⎣4 3 2⎦
>>> M.det()
-1

RREF

To put a matrix into reduced row echelon form, use rref. rref returns a tuple of two elements.
The first is the reduced row echelon form, and the second is a tuple of indices of the pivot

54 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

columns.

>>> M = Matrix([[1, 0, 1, 3], [2, 3, 4, 7], [-1, -3, -3, -4]])

>>> M
⎡1 0 1 3 ⎤
⎢ ⎥
⎢2 3 4 7 ⎥
⎢ ⎥
⎣-1 -3 -3 -4⎦
>>> M.rref()
⎛⎡1 0 1 3 ⎤ ⎞
⎜⎢ ⎥ ⎟
⎜⎢0 1 2/3 1/3⎥, (0, 1)⎟
⎜⎢ ⎥ ⎟
⎝⎣0 0 0 0 ⎦ ⎠

Note: The first element of the tuple returned by rref is of type Matrix. The second is of
type tuple.

Nullspace

To find the nullspace of a matrix, use nullspace. nullspace returns a list of column vectors
that span the nullspace of the matrix.

>>> M = Matrix([[1, 2, 3, 0, 0], [4, 10, 0, 0, 1]])

>>> M
⎡1 2 3 0 0⎤
⎢ ⎥
⎣4 10 0 0 1⎦
>>> M.nullspace()
⎡⎡-15⎤ ⎡0⎤ ⎡ 1 ⎤⎤
⎢⎢ ⎥ ⎢ ⎥ ⎢ ⎥⎥
⎢⎢ 6 ⎥ ⎢0⎥ ⎢-1/2⎥⎥
⎢⎢ ⎥ ⎢ ⎥ ⎢ ⎥⎥
⎢⎢ 1 ⎥, ⎢0⎥, ⎢ 0 ⎥⎥
⎢⎢ ⎥ ⎢ ⎥ ⎢ ⎥⎥
⎢⎢ 0 ⎥ ⎢1⎥ ⎢ 0 ⎥⎥
⎢⎢ ⎥ ⎢ ⎥ ⎢ ⎥⎥
⎣⎣ 0 ⎦ ⎣0⎦ ⎣ 1 ⎦⎦

Columnspace

To find the columnspace of a matrix, use columnspace. columnspace returns a list of column
vectors that span the columnspace of the matrix.

>>> M = Matrix([[1, 1, 2], [2 ,1 , 3], [3 , 1, 4]])

>>> M
⎡1 1 2⎤
⎢ ⎥
⎢2 1 3⎥
(continues on next page)

2.9. Matrices 55
SymPy Documentation, Release 1.3

(continued from previous page)

⎢ ⎥
⎣3 1 4⎦
>>> M.columnspace()
⎡⎡1⎤ ⎡1⎤⎤
⎢⎢ ⎥ ⎢ ⎥⎥
⎢⎢2⎥, ⎢1⎥⎥
⎢⎢ ⎥ ⎢ ⎥⎥
⎣⎣3⎦ ⎣1⎦⎦

Eigenvalues, Eigenvectors, and Diagonalization

To find the eigenvalues of a matrix, use eigenvals. eigenvals returns a dictionary of eigen-
value:algebraic multiplicity pairs (similar to the output of roots (page 49)).

>>> M = Matrix([[3, -2, 4, -2], [5, 3, -3, -2], [5, -2, 2, -2], [5, -2, -3, 3]])
>>> M
⎡3 -2 4 -2⎤
⎢ ⎥
⎢5 3 -3 -2⎥
⎢ ⎥
⎢5 -2 2 -2⎥
⎢ ⎥
⎣5 -2 -3 3 ⎦
>>> M.eigenvals()
{-2: 1, 3: 1, 5: 2}

This means that M has eigenvalues -2, 3, and 5, and that the eigenvalues -2 and 3 have alge-
braic multiplicity 1 and that the eigenvalue 5 has algebraic multiplicity 2.
To find the eigenvectors of a matrix, use eigenvects. eigenvects returns a list of tuples of
the form (eigenvalue:algebraic multiplicity, [eigenvectors]).

>>> M.eigenvects()
⎡⎛ ⎡⎡0⎤⎤⎞ ⎛ ⎡⎡1⎤⎤⎞ ⎛ ⎡⎡1⎤ ⎡0 ⎤⎤⎞⎤
⎢⎜ ⎢⎢ ⎥⎥⎟ ⎜ ⎢⎢ ⎥⎥⎟ ⎜ ⎢⎢ ⎥ ⎢ ⎥⎥⎟⎥
⎢⎜ ⎢⎢1⎥⎥⎟ ⎜ ⎢⎢1⎥⎥⎟ ⎜ ⎢⎢1⎥ ⎢-1⎥⎥⎟⎥
⎢⎜-2, 1, ⎢⎢ ⎥⎥⎟, ⎜3, 1, ⎢⎢ ⎥⎥⎟, ⎜5, 2, ⎢⎢ ⎥, ⎢ ⎥⎥⎟⎥
⎢⎜ ⎢⎢1⎥⎥⎟ ⎜ ⎢⎢1⎥⎥⎟ ⎜ ⎢⎢1⎥ ⎢0 ⎥⎥⎟⎥
⎢⎜ ⎢⎢ ⎥⎥⎟ ⎜ ⎢⎢ ⎥⎥⎟ ⎜ ⎢⎢ ⎥ ⎢ ⎥⎥⎟⎥
⎣⎝ ⎣⎣1⎦⎦⎠ ⎝ ⎣⎣1⎦⎦⎠ ⎝ ⎣⎣0⎦ ⎣1 ⎦⎦⎠⎦

This shows us that, for example, the eigenvalue 5 also has geometric multiplicity 2, because
it has two eigenvectors. Because the algebraic and geometric multiplicities are the same for
all the eigenvalues, M is diagonalizable.
To diagonalize a matrix, use diagonalize. diagonalize returns a tuple (P, D), where D is
diagonal and M = P DP −1 .

>>> P, D = M.diagonalize()
>>> P
⎡0 1 1 0 ⎤
⎢ ⎥
⎢1 1 1 -1⎥
(continues on next page)

56 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

(continued from previous page)

⎢ ⎥
⎢1 1 1 0 ⎥
⎢ ⎥
⎣1 1 0 1 ⎦
>>> D
⎡-2 0 0 0⎤
⎢ ⎥
⎢0 3 0 0⎥
⎢ ⎥
⎢0 0 5 0⎥
⎢ ⎥
⎣0 0 0 5⎦
>>> P*D*P**-1
⎡3 -2 4 -2⎤
⎢ ⎥
⎢5 3 -3 -2⎥
⎢ ⎥
⎢5 -2 2 -2⎥
⎢ ⎥
⎣5 -2 -3 3 ⎦
>>> P*D*P**-1 == M
True

Quick Tip

lambda is a reserved keyword in Python, so to create a Symbol called λ, while using the
same names for SymPy Symbols and Python variables, use lamda (without the b). It will
still pretty print as λ.

Note that since eigenvects also includes the eigenvalues, you should use it instead of eigen-
vals if you also want the eigenvectors. However, as computing the eigenvectors may often
be costly, eigenvals should be preferred if you only wish to find the eigenvalues.
If all you want is the characteristic polynomial, use charpoly. This is more efficient than
eigenvals, because sometimes symbolic roots can be expensive to calculate.

>>> lamda = symbols('lamda')

>>> p = M.charpoly(lamda)
>>> factor(p)
2
(λ - 5) ⋅(λ - 3)⋅(λ + 2)

2.9.5 Possible Issues

Zero Testing

If your matrix operations are failing or returning wrong answers, the common reasons would
likely be from zero testing. If there is an expression not properly zero-tested, it can possibly
bring issues in finding pivots for gaussian elimination, or deciding whether the matrix is
inversible, or any high level functions which relies on the prior procedures.

2.9. Matrices 57
SymPy Documentation, Release 1.3

Currently, the SymPy’s default method of zero testing _iszero is only guaranteed to be ac-
curate in some limited domain of numerics and symbols, and any complicated expressions
beyond its decidability are treated as None, which behaves similarly to logical False.
The list of methods using zero testing procedures are as followings.
echelon_form , is_echelon , rank , rref , nullspace , eigenvects , inverse_ADJ , in-
verse_GE , inverse_LU , LUdecomposition , LUdecomposition_Simple , LUsolve
They have property iszerofunc opened up for user to specify zero testing method, which can
accept any function with single input and boolean output, while being defaulted with _iszero.
Here is an example of solving an issue caused by undertested zero.1 2

>>> from sympy import *

>>> q = Symbol(”q”, positive = True)
>>> m = Matrix([
... [-2*cosh(q/3), exp(-q), 1],
... [ exp(q), -2*cosh(q/3), 1],
... [ 1, 1, -2*cosh(q/3)]])
>>> m.nullspace()
[]

You can trace down which expression is being underevaluated, by injecting a custom zero test
with warnings enabled.

>>> import warnings

>>>
>>> def my_iszero(x):
... try:
... result = x.is_zero
... except AttributeError:
... result = None
...
... # Warnings if evaluated into None
... if result == None:
... warnings.warn(”Zero testing of {} evaluated into {}”.format(x, result))
... return result
...
>>> m.nullspace(iszerofunc=my_iszero) # doctest: +SKIP
__main__:9: UserWarning: Zero testing of 4*cosh(q/3)**2 - 1 evaluated into None
__main__:9: UserWarning: Zero testing of (-exp(q) - 2*cosh(q/3))*(-2*cosh(q/3) - exp(-
,→q)) - (4*cosh(q/3)**2 - 1)**2 evaluated into None

__main__:9: UserWarning: Zero testing of 2*exp(q)*cosh(q/3) - 16*cosh(q/3)**4 +␣

,→12*cosh(q/3)**2 + 2*exp(-q)*cosh(q/3) evaluated into None

__main__:9: UserWarning: Zero testing of -(4*cosh(q/3)**2 - 1)*exp(-q) - 2*cosh(q/3) -

,→ exp(-q) evaluated into None

[]

In this case, (-exp(q) - 2*cosh(q/3))*(-2*cosh(q/3) - exp(-q)) - (4*cosh(q/3)**2

- 1)**2 should yield zero, but the zero testing had failed to catch. possibly meaning that a
stronger zero test should be introduced. For this specific example, rewriting to exponentials
and applying simplify would make zero test stronger for hyperbolics, while being harmless to
other polynomials or transcendental functions.

1 Inspired by https://gitter.im/sympy/sympy?at=5b7c3e8ee5b40332abdb206c
2
Discovered from https://github.com/sympy/sympy/issues/15141

58 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> def my_iszero(x):

... try:
... result = x.rewrite(exp).simplify().is_zero
... except AttributeError:
... result = None
...
... # Warnings if evaluated into None
... if result == None:
... warnings.warn(”Zero testing of {} evaluated into {}”.format(x, result))
... return result
...
>>> m.nullspace(iszerofunc=my_iszero) # doctest: +SKIP
__main__:9: UserWarning: Zero testing of -2*cosh(q/3) - exp(-q) evaluated into None
⎡⎡ ⎛ q ⎛q⎞⎞ -q 2⎛q⎞ ⎤⎤
⎢⎢- ⎜- e - 2⋅cosh⎜─⎟⎟⋅e + 4⋅cosh ⎜─⎟ - 1⎥⎥
⎢⎢ ⎝ ⎝3⎠⎠ ⎝3⎠ ⎥⎥
⎢⎢─────────────────────────────────────────⎥⎥
⎢⎢ ⎛ 2⎛q⎞ ⎞ ⎛q⎞ ⎥⎥
⎢⎢ 2⋅⎜4⋅cosh ⎜─⎟ - 1⎟⋅cosh⎜─⎟ ⎥⎥
⎢⎢ ⎝ ⎝3⎠ ⎠ ⎝3⎠ ⎥⎥
⎢⎢ ⎥⎥
⎢⎢ ⎛ q ⎛q⎞⎞ ⎥⎥
⎢⎢ -⎜- e - 2⋅cosh⎜─⎟⎟ ⎥⎥
⎢⎢ ⎝ ⎝3⎠⎠ ⎥⎥
⎢⎢ ──────────────────── ⎥⎥
⎢⎢ 2⎛q⎞ ⎥⎥
⎢⎢ 4⋅cosh ⎜─⎟ - 1 ⎥⎥
⎢⎢ ⎝3⎠ ⎥⎥
⎢⎢ ⎥⎥
⎣⎣ 1 ⎦⎦

You can clearly see nullspace returning proper result, after injecting an alternative zero test.
Note that this approach is only valid for some limited cases of matrices containing only nu-
merics, hyperbolics, and exponentials. For other matrices, you should use different method
opted for their domains.
Possible suggestions would be either taking advantage of rewriting and simplifying, with
tradeoff of speed3 , or using random numeric testing, with tradeoff of accuracy4 .
If you wonder why there is no generic algorithm for zero testing that can work with any sym-
bolic entities, it’s because of the constant problem stating that zero testing is undecidable5
, and not only the SymPy, but also other computer algebra systems67 would face the same
fundamental issue.
However, discovery of any zero test failings can provide some good examples to improve
SymPy, so if you have encountered one, you can report the issue to SymPy issue tracker8 to
get detailed help from the community.
3 Suggested from https://github.com/sympy/sympy/issues/10120
4
Suggested from https://github.com/sympy/sympy/issues/10279
5
https://en.wikipedia.org/wiki/Constant_problem
6
How mathematica tests zero https://reference.wolfram.com/language/ref/PossibleZeroQ.html
7
How matlab tests zero https://www.mathworks.com/help/symbolic/mupad_ref/iszero.html
8
https://github.com/sympy/sympy/issues

2.9. Matrices 59
SymPy Documentation, Release 1.3

2.10 Advanced Expression Manipulation

In this section, we discuss some ways that we can perform advanced manipulation of expres-
sions.

2.10.1 Understanding Expression Trees

Quick Tip

To play with the srepr form of expressions in the SymPy Live shell, change the output
format to Repr in the settings.

Before we can do this, we need to understand how expressions are represented in SymPy.
A mathematical expression is represented as a tree. Let us take the expression 2x + xy, i.e.,
2**x + x*y. We can see what this expression looks like internally by using srepr

>>> from sympy import *

>>> x, y, z = symbols('x y z')

>>> expr = 2**x + x*y

>>> srepr(expr)
”Add(Pow(Integer(2), Symbol('x')), Mul(Symbol('x'), Symbol('y')))”

The easiest way to tear this apart is to look at a diagram of the expression tree:

Add

Mul Pow

Symbol('x') Symbol('y') Integer(2) Symbol('x')

Note: The above diagram was made using Graphviz and the dotprint (page 1086) function.

First, let’s look at the leaves of this tree. Symbols are instances of the class Symbol. While
we have been doing

60 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> x = symbols('x')

we could have also done

>>> x = Symbol('x')

Either way, we get a Symbol with the name “x”1 . For the number in the expression, 2, we got
Integer(2). Integer is the SymPy class for integers. It is similar to the Python built-in type
int, except that Integer plays nicely with other SymPy types.
When we write 2**x, this creates a Pow object. Pow is short for “power”.

>>> srepr(2**x)
”Pow(Integer(2), Symbol('x'))”

We could have created the same object by calling Pow(2, x)

>>> Pow(2, x)
2**x

Note that in the srepr output, we see Integer(2), the SymPy version of integers, even though
technically, we input 2, a Python int. In general, whenever you combine a SymPy object with
a non-SymPy object via some function or operation, the non-SymPy object will be converted
into a SymPy object. The function that does this is sympify2 .

>>> type(2)
<... 'int'>
>>> type(sympify(2))
<class 'sympy.core.numbers.Integer'>

We have seen that 2**x is represented as Pow(2, x). What about x*y? As we might expect,
this is the multiplication of x and y. The SymPy class for multiplication is Mul.

>>> srepr(x*y)
”Mul(Symbol('x'), Symbol('y'))”

Thus, we could have created the same object by writing Mul(x, y).

>>> Mul(x, y)
x*y

Now we get to our final expression, 2**x + x*y. This is the addition of our last two objects,
Pow(2, x), and Mul(x, y). The SymPy class for addition is Add, so, as you might expect, to
create this object, we use Add(Pow(2, x), Mul(x, y)).

>>> Add(Pow(2, x), Mul(x, y))

2**x + x*y

SymPy expression trees can have many branches, and can be quite deep or quite broad. Here
is a more complicated example

1 We have been using symbols instead of Symbol because it automatically splits apart strings into multiple Symbols.

symbols('x y z') returns a tuple of three Symbols. Symbol('x y z') returns a single Symbol called x y z.
2 Technically, it is an internal function called _sympify, which differs from sympify in that it does not convert

strings. x + '2' is not allowed.

2.10. Advanced Expression Manipulation 61

SymPy Documentation, Release 1.3

>>> expr = sin(x*y)/2 - x**2 + 1/y

>>> srepr(expr)
”Add(Mul(Integer(-1), Pow(Symbol('x'), Integer(2))), Mul(Rational(1, 2),
sin(Mul(Symbol('x'), Symbol('y')))), Pow(Symbol('y'), Integer(-1)))”

Here is a diagram

Add

Pow Mul Mul

Symbol('y') Integer(-1) Rational(1, 2) sin Integer(-1) Pow

Mul Symbol('x') Integer(2)

Symbol('y') Symbol('x')

This expression reveals some interesting things about SymPy expression trees. Let’s go
through them one by one.
Let’s first look at the term x**2. As we expected, we see Pow(x, 2). One level up, we see we
have Mul(-1, Pow(x, 2)). There is no subtraction class in SymPy. x - y is represented as
x + -y, or, more completely, x + -1*y, i.e., Add(x, Mul(-1, y)).

>>> srepr(x - y)
”Add(Symbol('x'), Mul(Integer(-1), Symbol('y')))”

62 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

Add

Symbol('x') Mul

Symbol('y') Integer(-1)

Next, look at 1/y. We might expect to see something like Div(1, y), but similar to subtrac-
tion, there is no class in SymPy for division. Rather, division is represented by a power of -1.
Hence, we have Pow(y, -1). What if we had divided something other than 1 by y, like x/y?
Let’s see.

>>> expr = x/y

>>> srepr(expr)
”Mul(Symbol('x'), Pow(Symbol('y'), Integer(-1)))”

Mul

Symbol('x') Pow

Symbol('y') Integer(-1)

We see that x/y is represented as x*y**-1, i.e., Mul(x, Pow(y, -1)).

2.10. Advanced Expression Manipulation 63

SymPy Documentation, Release 1.3

Finally, let’s look at the sin(x*y)/2 term. Following the pattern of the previous exam-
ple, we might expect to see Mul(sin(x*y), Pow(Integer(2), -1)). But instead, we have
Mul(Rational(1, 2), sin(x*y)). Rational numbers are always combined into a single term
in a multiplication, so that when we divide by 2, it is represented as multiplying by 1/2.
Finally, one last note. You may have noticed that the order we entered our expression and the
order that it came out from srepr or in the graph were different. You may have also noticed
this phenomenon earlier in the tutorial. For example

>>> 1 + x
x + 1

This because in SymPy, the arguments of the commutative operations Add and Mul are stored
in an arbitrary (but consistent!) order, which is independent of the order inputted (if you’re
worried about noncommutative multiplication, don’t be. In SymPy, you can create noncom-
mutative Symbols using Symbol('A', commutative=False), and the order of multiplication
for noncommutative Symbols is kept the same as the input). Furthermore, as we shall see in
the next section, the printing order and the order in which things are stored internally need
not be the same either.

Quick Tip

The way an expression is represented internally and the way it is printed are often not the
same.

In general, an important thing to keep in mind when working with SymPy expression trees
is this: the internal representation of an expression and the way it is printed need not be the
same. The same is true for the input form. If some expression manipulation algorithm is not
working in the way you expected it to, chances are, the internal representation of the object
is different from what you thought it was.

2.10.2 Recursing through an Expression Tree

Now that you know how expression trees work in SymPy, let’s look at how to dig our way
through an expression tree. Every object in SymPy has two very important attributes, func,
and args.

func

func is the head of the object. For example, (x*y).func is Mul. Usually it is the same as the
class of the object (though there are exceptions to this rule).
Two notes about func. First, the class of an object need not be the same as the one used to
create it. For example

>>> expr = Add(x, x)

>>> expr.func
<class 'sympy.core.mul.Mul'>

We created Add(x, x), so we might expect expr.func to be Add, but instead we got Mul. Why
is that? Let’s take a closer look at expr.

64 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> expr
2*x

Add(x, x), i.e., x + x, was automatically converted into Mul(2, x), i.e., 2*x, which is a Mul.
SymPy classes make heavy use of the __new__ class constructor, which, unlike __init__,
allows a different class to be returned from the constructor.
Second, some classes are special-cased, usually for efficiency reasons3 .

>>> Integer(2).func
<class 'sympy.core.numbers.Integer'>
>>> Integer(0).func
<class 'sympy.core.numbers.Zero'>
>>> Integer(-1).func
<class 'sympy.core.numbers.NegativeOne'>

For the most part, these issues will not bother us. The special classes Zero, One, NegativeOne,
and so on are subclasses of Integer, so as long as you use isinstance, it will not be an issue.

args

args are the top-level arguments of the object. (x*y).args would be (x, y). Let’s look at
some examples

>>> expr = 3*y**2*x

>>> expr.func
<class 'sympy.core.mul.Mul'>
>>> expr.args
(3, x, y**2)

From this, we can see that expr == Mul(3, y**2, x). In fact, we can see that we can com-
pletely reconstruct expr from its func and its args.

>>> expr.func(*expr.args)
3*x*y**2
>>> expr == expr.func(*expr.args)
True

Note that although we entered 3*y**2*x, the args are (3, x, y**2). In a Mul, the Rational
coefficient will come first in the args, but other than that, the order of everything else follows
no special pattern. To be sure, though, there is an order.

>>> expr = y**2*3*x

>>> expr.args
(3, x, y**2)

Mul’s args are sorted, so that the same Mul will have the same args. But the sorting is based
on some criteria designed to make the sorting unique and efficient that has no mathematical
significance.
3 Classes like One and Zero are singletonized, meaning that only one object is ever created, no matter how many

times the class is called. This is done for space efficiency, as these classes are very common. For example, Zero
might occur very often in a sparse matrix represented densely. As we have seen, NegativeOne occurs any time we
have -x or 1/x. It is also done for speed efficiency because singletonized objects can be compared by is. The unique
objects for each singletonized class can be accessed from the S object.

2.10. Advanced Expression Manipulation 65

SymPy Documentation, Release 1.3

The srepr form of our expr is Mul(3, x, Pow(y, 2)). What if we want to get at the args of
Pow(y, 2). Notice that the y**2 is in the third slot of expr.args, i.e., expr.args[2].

>>> expr.args[2]
y**2

So to get the args of this, we call expr.args[2].args.

>>> expr.args[2].args
(y, 2)

Now what if we try to go deeper. What are the args of y. Or 2. Let’s see.

>>> y.args
()
>>> Integer(2).args
()

They both have empty args. In SymPy, empty args signal that we have hit a leaf of the
expression tree.
So there are two possibilities for a SymPy expression. Either it has empty args, in which case
it is a leaf node in any expression tree, or it has args, in which case, it is a branch node of any
expression tree. When it has args, it can be completely rebuilt from its func and its args.
This is expressed in the key invariant.

Key Invariant

Every well-formed SymPy expression must either have empty args or satisfy expr == expr.
func(*expr.args).

(Recall that in Python if a is a tuple, then f(*a) means to call f with arguments from the
elements of a, e.g., f(*(1, 2, 3)) is the same as f(1, 2, 3).)
This key invariant allows us to write simple algorithms that walk expression trees, change
them, and rebuild them into new expressions.

Walking the Tree

With this knowledge, let’s look at how we can recurse through an expression tree. The nested
nature of args is a perfect fit for recursive functions. The base case will be empty args. Let’s
write a simple function that goes through an expression and prints all the args at each level.

>>> def pre(expr):

... print(expr)
... for arg in expr.args:
... pre(arg)

See how nice it is that () signals leaves in the expression tree. We don’t even have to write
a base case for our recursion; it is handled automatically by the for loop.
Let’s test our function.

66 Chapter 2. SymPy Tutorial

 SymPy Documentation, Release 1.3

>>> expr = x*y + 1

>>> pre(expr)
x*y + 1
1
x*y
x
y

Can you guess why we called our function pre? We just wrote a pre-order traversal function
for our expression tree. See if you can write a post-order traversal function.
Such traversals are so common in SymPy that the generator functions preorder_traversal
and postorder_traversal are provided to make such traversals easy. We could have also
written our algorithm as

>>> for arg in preorder_traversal(expr):

... print(arg)
x*y + 1
1
x*y
x
y

2.10.3 Prevent expression evaluation

There are generally two ways to prevent the evaluation, either pass an evaluate=False pa-
rameter while constructing the expression, or create an evaluation stopper by wrapping the
expression with UnevaluatedExpr.
For example:

>>> from sympy import Add

>>> from sympy.abc import x, y, z
>>> x + x
2*x
>>> Add(x, x)
2*x
>>> Add(x, x, evaluate=False)
x + x

If you don’t remember the class corresponding to the expression you want to build (operator
overloading usually assumes evaluate=True), just use sympify and pass a string:

>>> from sympy import sympify

>>> sympify(”x + x”, evaluate=False)
x + x

Note that evaluate=False won’t prevent future evaluation in later usages of the expression:

>>> expr = Add(x, x, evaluate=False)

>>> expr
x + x
>>> expr + x
3*x

2.10. Advanced Expression Manipulation 67

SymPy Documentation, Release 1.3

That’s why the class UnevaluatedExpr comes handy. UnevaluatedExpr is a method provided
by SymPy which lets the user keep an expression unevaluated. By unevaluated it is meant
that the value inside of it will not interact with the expressions outside of it to give simplified
outputs. For example:

>>> from sympy import UnevaluatedExpr

>>> expr = x + UnevaluatedExpr(x)
>>> expr
x + x
>>> x + expr
2*x + x

The x remaining alone is the x wrapped by UnevaluatedExpr. To release it:

>>> (x + expr).doit()
3*x

Other examples:

>>> from sympy import *

>>> from sympy.abc import x, y, z
>>> uexpr = UnevaluatedExpr(S.One*5/7)*UnevaluatedExpr(S.One*3/4)
>>> uexpr
(5/7)*(3/4)
>>> x*UnevaluatedExpr(1/x)
x*1/x

A point to be noted is that UnevaluatedExpr cannot prevent the evaluation of an expression

which is given as argument. For example:

>>> expr1 = UnevaluatedExpr(x + x)

>>> expr1
2*x
>>> expr2 = sympify('x + x', evaluate=False)
>>> expr2
x + x

Remember that expr2 will be evaluated if included into another expression. Combine both of
the methods to prevent both inside and outside evaluations:

>>> UnevaluatedExpr(sympify(”x + x”, evaluate=False)) + y

y + x + x

UnevalutedExpr is supported by SymPy printers and can be used to print the result in differ-
ent output forms. For example

>>> from sympy import latex

>>> uexpr = UnevaluatedExpr(S.One*5/7)*UnevaluatedExpr(S.One*3/4)
>>> print(latex(uexpr))
\frac{5}{7} \frac{3}{4}

In order to release the expression and get the evaluated LaTeX form, just use .doit():

>>> print(latex(uexpr.doit()))
\frac{15}{28}

68 Chapter 2. SymPy Tutorial

 CHAPTER

THREE

GOTCHAS AND PITFALLS

3.1 Introduction

SymPy runs under the Python Programming Language, so there are some things that may
behave differently than they do in other, independent computer algebra systems like Maple
or Mathematica. These are some of the gotchas and pitfalls that you may encounter when
using SymPy. See also the FAQ, the Tutorial (page 5), the remainder of the SymPy Docs, and
the official Python Tutorial.
If you are already familiar with C or Java, you might also want to look at this 4 minute Python
tutorial.
Ignore #doctest: +SKIP in the examples. That has to do with internal testing of the examples.

3.2 Equals Signs (=)

3.2.1 Single Equals Sign

The equals sign (=) is the assignment operator, not equality. If you want to do x = y, use
Eq(x, y) for equality. Alternatively, all expressions are assumed to equal zero, so you can
just subtract one side and use x - y.
The proper use of the equals sign is to assign expressions to variables.
For example:

>>> from sympy.abc import x, y

>>> a = x - y
>>> print(a)
x - y

3.2.2 Double Equals Signs

Double equals signs (==) are used to test equality. However, this tests expressions exactly,
not symbolically. For example:

69
SymPy Documentation, Release 1.3

>>> (x + 1)**2 == x**2 + 2*x + 1

False
>>> (x + 1)**2 == (x + 1)**2
True

If you want to test for symbolic equality, one way is to subtract one expression from the
other and run it through functions like expand(), simplify(), and trigsimp() and see if the
equation reduces to 0.
>>> from sympy import simplify, cos, sin, expand
>>> simplify((x + 1)**2 - (x**2 + 2*x + 1))
0
>>> eq = sin(2*x) - 2*sin(x)*cos(x)
>>> simplify(eq)
0
>>> expand(eq, trig=True)
0

Note: See also Why does SymPy say that two equal expressions are unequal? in the FAQ.

3.3 Variables

3.3.1 Variables Assignment does not Create a Relation Between Ex-

pressions

When you use = to do assignment, remember that in Python, as in most programming lan-
guages, the variable does not change if you change the value you assigned to it. The equa-
tions you are typing use the values present at the time of creation to “fill in” values, just like
regular Python definitions. They are not altered by changes made afterwards. Consider the
following:
>>> from sympy import Symbol
>>> a = Symbol('a') # Symbol, `a`, stored as variable ”a”
>>> b = a + 1 # an expression involving `a` stored as variable ”b”
>>> print(b)
a + 1
>>> a = 4 # ”a” now points to literal integer 4, not Symbol('a')
>>> print(a)
4
>>> print(b) # ”b” is still pointing at the expression involving `a`
a + 1

Changing quantity a does not change b; you are not working with a set of simultaneous equa-
tions. It might be helpful to remember that the string that gets printed when you print a
variable referring to a SymPy object is the string that was given to it when it was created;
that string does not have to be the same as the variable that you assign it to.
>>> from sympy import var
>>> r, t, d = var('rate time short_life')
>>> d = r*t
>>> print(d)
(continues on next page)

70 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

(continued from previous page)

rate*time
>>> r = 80
>>> t = 2
>>> print(d) # We haven't changed d, only r and t
rate*time
>>> d = r*t
>>> print(d) # Now d is using the current values of r and t
160

If you need variables that have dependence on each other, you can define functions. Use the
def operator. Indent the body of the function. See the Python docs for more information on
defining functions.

>>> c, d = var('c d')

>>> print(c)
c
>>> print(d)
d
>>> def ctimesd():
... ”””
... This function returns whatever c is times whatever d is.
... ”””
... return c*d
...
>>> ctimesd()
c*d
>>> c = 2
>>> print(c)
2
>>> ctimesd()
2*d

If you define a circular relationship, you will get a RuntimeError.

>>> def a():

... return b()
...
>>> def b():
... return a()
...
>>> a() #doctest: +SKIP
Traceback (most recent call last):
File ”...”, line ..., in ...
compileflags, 1) in test.globs
File ”<...>”, line 1, in <module>
a()
File ”<...>”, line 2, in a
return b()
File ”<...>”, line 2, in b
return a()
File ”<...>”, line 2, in a
return b()
...
RuntimeError: maximum recursion depth exceeded

Note: See also Why doesn’t changing one variable change another that depends on it? in

3.3. Variables 71
SymPy Documentation, Release 1.3

the FAQ.

3.3.2 Symbols

Symbols are variables, and like all other variables, they need to be assigned before you can
use them. For example:

>>> import sympy

>>> z**2 # z is not defined yet #doctest: +SKIP
Traceback (most recent call last):
File ”<stdin>”, line 1, in <module>
NameError: name 'z' is not defined
>>> sympy.var('z') # This is the easiest way to define z as a standard symbol
z
>>> z**2
z**2

If you use isympy, it runs the following commands for you, giving you some default Symbols
and Functions.

>>> from __future__ import division

>>> from sympy import *
>>> x, y, z, t = symbols('x y z t')
>>> k, m, n = symbols('k m n', integer=True)
>>> f, g, h = symbols('f g h', cls=Function)

You can also import common symbol names from sympy.abc.

>>> from sympy.abc import w

>>> w
w
>>> import sympy
>>> dir(sympy.abc) #doctest: +SKIP
['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O',
'P', 'Q', 'R', 'S', 'Symbol', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
'__builtins__', '__doc__', '__file__', '__name__', '__package__', '_greek',
'_latin', 'a', 'alpha', 'b', 'beta', 'c', 'chi', 'd', 'delta', 'e',
'epsilon', 'eta', 'f', 'g', 'gamma', 'h', 'i', 'iota', 'j', 'k', 'kappa',
'l', 'm', 'mu', 'n', 'nu', 'o', 'omega', 'omicron', 'p', 'phi', 'pi',
'psi', 'q', 'r', 'rho', 's', 'sigma', 't', 'tau', 'theta', 'u', 'upsilon',
'v', 'w', 'x', 'xi', 'y', 'z', 'zeta']

If you want control over the assumptions of the variables, use Symbol() and symbols(). See
Keyword Arguments (page 80) below.
Lastly, it is recommended that you not use I, E, S, N, C, O, or Q for variable or symbol names, as
those are used for the imaginary unit (i), the base of the natural logarithm (e), the sympify()
function (see Symbolic Expressions (page 73) below), numeric evaluation (N() is equivalent to
evalf() (page 393) ), the big O order symbol (as in O(n log n)), and the assumptions object that
holds a list of supported ask keys (such as Q.real), respectively. You can use the mnemonic
OSINEQ to remember what Symbols are defined by default in SymPy. Or better yet, always
use lowercase letters for Symbol names. Python will not prevent you from overriding default
SymPy names or functions, so be careful.

72 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

>>> cos(pi) # cos and pi are a built-in sympy names.

-1
>>> pi = 3 # Notice that there is no warning for overriding pi.
>>> cos(pi)
cos(3)
>>> def cos(x): # No warning for overriding built-in functions either.
... return 5*x
...
>>> cos(pi)
15
>>> from sympy import cos # reimport to restore normal behavior

To get a full list of all default names in SymPy do:

>>> import sympy

>>> dir(sympy) #doctest: +SKIP
# A big list of all default sympy names and functions follows.
# Ignore everything that starts and ends with __.

If you have IPython installed and use isympy, you can also press the TAB key to get a list of all
built-in names and to autocomplete. Also, see this page for a trick for getting tab completion
in the regular Python console.

Note: See also What is the best way to create symbols? in the FAQ.

3.4 Symbolic Expressions

3.4.1 Python numbers vs. SymPy Numbers

SymPy uses its own classes for integers, rational numbers, and floating point numbers instead
of the default Python int and float types because it allows for more control. But you have
to be careful. If you type an expression that just has numbers in it, it will default to a Python
expression. Use the sympify() function, or just S(), to ensure that something is a SymPy
expression.

>>> 6.2 # Python float. Notice the floating point accuracy problems.
6.2000000000000002
>>> type(6.2) # <type 'float'> in Python 2.x, <class 'float'> in Py3k
<... 'float'>
>>> S(6.2) # SymPy Float has no such problems because of arbitrary precision.
6.20000000000000
>>> type(S(6.2))
<class 'sympy.core.numbers.Float'>

If you include numbers in a SymPy expression, they will be sympified automatically, but there
is one gotcha you should be aware of. If you do <number>/<number> inside of a SymPy ex-
pression, Python will evaluate the two numbers before SymPy has a chance to get to them.
The solution is to sympify() one of the numbers, or use Rational.

>>> x**(1/2) # evaluates to x**0 or x**0.5

x**0.5
(continues on next page)

3.4. Symbolic Expressions 73

SymPy Documentation, Release 1.3

(continued from previous page)

>>> x**(S(1)/2) # sympyify one of the ints
sqrt(x)
>>> x**Rational(1, 2) # use the Rational class
sqrt(x)

With a power of 1/2 you can also use sqrt shorthand:

>>> sqrt(x) == x**Rational(1, 2)

True

If the two integers are not directly separated by a division sign then you don’t have to worry
about this problem:

>>> x**(2*x/3)
x**(2*x/3)

Note: A common mistake is copying an expression that is printed and reusing it. If the
expression has a Rational (i.e., <number>/<number>) in it, you will not get the same result,
obtaining the Python result for the division rather than a SymPy Rational.

>>> x = Symbol('x')
>>> print(solve(7*x -22, x))
[22/7]
>>> 22/7 # If we just copy and paste we get int 3 or a float
3.142857142857143
>>> # One solution is to just assign the expression to a variable
>>> # if we need to use it again.
>>> a = solve(7*x - 22, x)[0]
>>> a
22/7

The other solution is to put quotes around the expression and run it through S() (i.e., sympify
it):

>>> S(”22/7”)
22/7

Also, if you do not use isympy, you could use from __future__ import division to prevent
the / sign from performing integer division.

>>> from __future__ import division

>>> 1/2 # With division imported it evaluates to a python float
0.5
>>> 1//2 # You can still achieve integer division with //
0

But be careful: you will now receive floats where you might have desired a Rational:

>>> x**(1/2)
x**0.5

Rational only works for number/number and is only meant for rational numbers. If you
want a fraction with symbols or expressions in it, just use /. If you do number/expression or

74 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

expression/number, then the number will automatically be converted into a SymPy Number.
You only need to be careful with number/number.
>>> Rational(2, x)
Traceback (most recent call last):
...
TypeError: invalid input: x
>>> 2/x
2/x

3.4.2 Evaluating Expressions with Floats and Rationals

SymPy keeps track of the precision of Float objects. The default precision is 15 digits. When
an expression involving a Float is evaluated, the result will be expressed to 15 digits of
precision but those digits (depending on the numbers involved with the calculation) may not
all be significant.
The first issue to keep in mind is how the Float is created: it is created with a value and
a precision. The precision indicates how precise of a value to use when that Float (or an
expression it appears in) is evaluated.
The values can be given as strings, integers, floats, or rationals.
• strings and integers are interpreted as exact
>>> Float(100)
100.000000000000
>>> Float('100', 5)
100.00

• to have the precision match the number of digits, the null string can be used
for the precision
>>> Float(100, '')
100.
>>> Float('12.34')
12.3400000000000
>>> Float('12.34', '')
12.34

>>> s, r = [Float(j, 3) for j in ('0.25', Rational(1, 7))]

>>> for f in [s, r]:
... print(f)
0.250
0.143

Next, notice that each of those values looks correct to 3 digits. But if we try to evaluate them
to 20 digits, a difference will become apparent:
The 0.25 (with precision of 3) represents a number that has a non-repeating binary
decimal; 1/7 is repeating in binary and decimal – it cannot be represented accurately
too far past those first 3 digits (the correct decimal is a repeating 142857):
>>> s.n(20)
0.25000000000000000000
>>> r.n(20)
0.14285278320312500000

3.4. Symbolic Expressions 75

SymPy Documentation, Release 1.3

It is important to realize that although a Float is being displayed in decimal at arbi-

trary precision, it is actually stored in binary. Once the Float is created, its binary
information is set at the given precision. The accuracy of that value cannot be sub-
sequently changed; so 1/7, at a precision of 3 digits, can be padded with binary
zeros, but these will not make it a more accurate value of 1/7.
If inexact, low-precision numbers are involved in a calculation with higher precision values,
the evalf engine will increase the precision of the low precision values and inexact results will
be obtained. This is feature of calculations with limited precision:

>>> Float('0.1', 10) + Float('0.1', 3)

0.2000061035

Although the evalf engine tried to maintain 10 digits of precision (since that was the highest
precision represented) the 3-digit precision used limits the accuracy to about 4 digits – not all
the digits you see are significant. evalf doesn’t try to keep track of the number of significant
digits.
That very simple expression involving the addition of two numbers with different precisions
will hopefully be instructive in helping you understand why more complicated expressions
(like trig expressions that may not be simplified) will not evaluate to an exact zero even
though, with the right simplification, they should be zero. Consider this unsimplified trig
identity, multiplied by a big number:

>>> big = 12345678901234567890

>>> big_trig_identity = big*cos(x)**2 + big*sin(x)**2 - big*1
>>> abs(big_trig_identity.subs(x, .1).n(2)) > 1000
True

When the cos and sin terms were evaluated to 15 digits of precision and multiplied by the
big number, they gave a large number that was only precise to 15 digits (approximately) and
when the 20 digit big number was subtracted the result was not zero.
There are three things that will help you obtain more precise numerical values for expressions:
1) Pass the desired substitutions with the call to evaluate. By doing the subs first,
the Float values cannot be updated as necessary. By passing the desired substitu-
tions with the call to evalf the ability to re-evaluate as necessary is gained and the
results are impressively better:

>>> big_trig_identity.n(2, {x: 0.1})

-0.e-91

2) Use Rationals, not Floats. During the evaluation process, the Rational can be
computed to an arbitrary precision while the Float, once created – at a default of
15 digits – cannot. Compare the value of -1.4e+3 above with the nearly zero value
obtained when replacing x with a Rational representing 1/10 – before the call to
evaluate:

>>> big_trig_identity.subs(x, S('1/10')).n(2)

0.e-91

3) Try to simplify the expression. In this case, SymPy will recognize the trig identity
and simplify it to zero so you don’t even have to evaluate it numerically:

>>> big_trig_identity.simplify()
0

76 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

3.4.3 Immutability of Expressions

Expressions in SymPy are immutable, and cannot be modified by an in-place operation. This
means that a function will always return an object, and the original expression will not be
modified. The following example snippet demonstrates how this works:

def main():
var('x y a b')
expr = 3*x + 4*y
print('original =', expr)
expr_modified = expr.subs({x: a, y: b})
print('modified =', expr_modified)

if __name__ == ”__main__”:
main()

The output shows that the subs() function has replaced variable x with variable a, and vari-
able y with variable b:

original = 3*x + 4*y

modified = 3*a + 4*b

The subs() function does not modify the original expression expr. Rather, a modified copy of
the expression is returned. This returned object is stored in the variable expr_modified. Note
that unlike C/C++ and other high-level languages, Python does not require you to declare a
variable before it is used.

3.4.4 Mathematical Operators

SymPy uses the same default operators as Python. Most of these, like */+-, are standard.
Aside from integer division discussed in Python numbers vs. SymPy Numbers (page 73) above,
you should also be aware that implied multiplication is not allowed. You need to use * when-
ever you wish to multiply something. Also, to raise something to a power, use **, not ^ as
many computer algebra systems use. Parentheses () change operator precedence as you
would normally expect.
In isympy, with the ipython shell:

>>> 2x
Traceback (most recent call last):
...
SyntaxError: invalid syntax
>>> 2*x
2*x
>>> (x + 1)^2 # This is not power. Use ** instead.
Traceback (most recent call last):
...
TypeError: unsupported operand type(s) for ^: 'Add' and 'int'
>>> (x + 1)**2
(x + 1)**2
>>> pprint(3 - x**(2*x)/(x + 1))
2*x
x
- ----- + 3
x + 1

3.4. Symbolic Expressions 77

SymPy Documentation, Release 1.3

3.4.5 Inverse Trig Functions

SymPy uses different names for some functions than most computer algebra systems. In par-
ticular, the inverse trig functions use the python names of asin(), acos() and so on instead
of the usual arcsin and arccos. Use the methods described in Symbols (page 72) above to
see the names of all SymPy functions.

3.5 Special Symbols

The symbols [], {}, =, and () have special meanings in Python, and thus in SymPy. See the
Python docs linked to above for additional information.

3.5.1 Lists

Square brackets [] denote a list. A list is a container that holds any number of different
objects. A list can contain anything, including items of different types. Lists are mutable,
which means that you can change the elements of a list after it has been created. You access
the items of a list also using square brackets, placing them after the list or list variable. Items
are numbered using the space before the item.

Note: List indexes begin at 0.

Example:
>>> a = [x, 1] # A simple list of two items
>>> a
[x, 1]
>>> a[0] # This is the first item
x
>>> a[0] = 2 # You can change values of lists after they have been created
>>> print(a)
[2, 1]
>>> print(solve(x**2 + 2*x - 1, x)) # Some functions return lists
[-1 + sqrt(2), -sqrt(2) - 1]

Note: See the Python docs for more information on lists and the square bracket notation for
accessing elements of a list.

3.5.2 Dictionaries

Curly brackets {} denote a dictionary, or a dict for short. A dictionary is an unordered list of
non-duplicate keys and values. The syntax is {key: value}. You can access values of keys
using square bracket notation.
>>> d = {'a': 1, 'b': 2} # A dictionary.
>>> d
{'a': 1, 'b': 2}
(continues on next page)

78 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> d['a'] # How to access items in a dict
1
>>> roots((x - 1)**2*(x - 2), x) # Some functions return dicts
{1: 2, 2: 1}
>>> # Some SymPy functions return dictionaries. For example,
>>> # roots returns a dictionary of root:multiplicity items.
>>> roots((x - 5)**2*(x + 3), x)
{-3: 1, 5: 2}
>>> # This means that the root -3 occurs once and the root 5 occurs twice.

Note: See the Python docs for more information on dictionaries.

3.5.3 Tuples

Parentheses (), aside from changing operator precedence and their use in function calls, (like
cos(x)), are also used for tuples. A tuple is identical to a list (page 78), except that it is not
mutable. That means that you cannot change their values after they have been created. In
general, you will not need tuples in SymPy, but sometimes it can be more convenient to type
parentheses instead of square brackets.

>>> t = (1, 2, x) # Tuples are like lists

>>> t
(1, 2, x)
>>> t[0]
1
>>> t[0] = 4 # Except you cannot change them after they have been created
Traceback (most recent call last):
File ”<console>”, line 1, in <module>
TypeError: 'tuple' object does not support item assignment

Single element tuples, unlike lists, must have a comma in them:

>>> (x,)
(x,)

Without the comma, a single expression without a comma is not a tuple:

>>> (x)
x

integrate takes a sequence as the second argument if you want to integrate with
limits (and a tuple or list will work):

>>> integrate(x**2, (x, 0, 1))

1/3
>>> integrate(x**2, [x, 0, 1])
1/3

Note: See the Python docs for more information on tuples.

3.5. Special Symbols 79

SymPy Documentation, Release 1.3

3.5.4 Keyword Arguments

Aside from the usage described above (page 69), equals signs (=) are also used to give named
arguments to functions. Any function that has key=value in its parameters list (see below
on how to find this out), then key is set to value by default. You can change the value of the
key by supplying your own value using the equals sign in the function call. Also, functions
that have ** followed by a name in the parameters list (usually **kwargs or **assumptions)
allow you to add any number of key=value pairs that you want, and they will all be evaluated
according to the function.
sqrt(x**2) doesn’t auto simplify to x because x is assumed to be complex by de-
fault, and, for example, sqrt((-1)**2) == sqrt(1) == 1 != -1:

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

Giving assumptions to Symbols is an example of using the keyword argument:

>>> x = Symbol('x', positive=True)

The square root will now simplify since it knows that x >= 0:

>>> sqrt(x**2)
x

powsimp has a default argument of combine='all':

>>> pprint(powsimp(x**n*x**m*y**n*y**m))
m + n
(x*y)

Setting combine to the default value is the same as not setting it.

>>> pprint(powsimp(x**n*x**m*y**n*y**m, combine='all'))

m + n
(x*y)

The non-default options are 'exp', which combines exponents…

>>> pprint(powsimp(x**n*x**m*y**n*y**m, combine='exp'))

m + n m + n
x *y

…and ‘base’, which combines bases.

>>> pprint(powsimp(x**n*x**m*y**n*y**m, combine='base'))

m n
(x*y) *(x*y)

Note: See the Python docs for more information on function parameters.

80 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

3.6 Getting help from within SymPy

3.6.1 help()

Although all docs are available at docs.sympy.org or on the SymPy Wiki, you can also get info
on functions from within the Python interpreter that runs SymPy. The easiest way to do this
is to do help(function), or function? if you are using ipython:

In [1]: help(powsimp) # help() works everywhere

In [2]: # But in ipython, you can also use ?, which is better because it
In [3]: # it gives you more information
In [4]: powsimp?

These will give you the function parameters and docstring for powsimp(). The output will
look something like this:
sympy.simplify.simplify.powsimp(expr, deep=False, combine=’all’, force=False,
measure=<function count_ops>)
reduces expression by combining powers with similar bases and exponents.

Notes

If deep is True then powsimp() will also simplify arguments of functions. By default deep
is set to False.
If force is True then bases will be combined without checking for assumptions, e.g.
sqrt(x)*sqrt(y) -> sqrt(x*y) which is not true if x and y are both negative.
You can make powsimp() only combine bases or only combine exponents by changing
combine=’base’ or combine=’exp’. By default, combine=’all’, which does both. com-
bine=’base’ will only combine:

a a a 2x x
x * y => (x*y) as well as things like 2 => 4

and combine=’exp’ will only combine

a b (a + b)
x * x => x

combine=’exp’ will strictly only combine exponents in the way that used to be automatic.
Also use deep=True if you need the old behavior.
When combine=’all’, ‘exp’ is evaluated first. Consider the first example below for when
there could be an ambiguity relating to this. This is done so things like the second
example can be completely combined. If you want ‘base’ combined first, do something
like powsimp(powsimp(expr, combine=’base’), combine=’exp’).

Examples

3.6. Getting help from within SymPy 81

SymPy Documentation, Release 1.3

>>> from sympy import powsimp, exp, log, symbols

>>> from sympy.abc import x, y, z, n
>>> powsimp(x**y*x**z*y**z, combine='all')
x**(y + z)*y**z
>>> powsimp(x**y*x**z*y**z, combine='exp')
x**(y + z)*y**z
>>> powsimp(x**y*x**z*y**z, combine='base', force=True)
x**y*(x*y)**z

>>> powsimp(x**z*x**y*n**z*n**y, combine='all', force=True)

(n*x)**(y + z)
>>> powsimp(x**z*x**y*n**z*n**y, combine='exp')
n**(y + z)*x**(y + z)
>>> powsimp(x**z*x**y*n**z*n**y, combine='base', force=True)
(n*x)**y*(n*x)**z

>>> x, y = symbols('x y', positive=True)

>>> powsimp(log(exp(x)*exp(y)))
log(exp(x)*exp(y))
>>> powsimp(log(exp(x)*exp(y)), deep=True)
x + y

Radicals with Mul bases will be combined if combine=’exp’

>>> from sympy import sqrt, Mul

>>> x, y = symbols('x y')

Two radicals are automatically joined through Mul:

>>> a=sqrt(x*sqrt(y))
>>> a*a**3 == a**4
True

But if an integer power of that radical has been autoexpanded then Mul does not join
the resulting factors:

>>> a**4 # auto expands to a Mul, no longer a Pow

x**2*y
>>> _*a # so Mul doesn't combine them
x**2*y*sqrt(x*sqrt(y))
>>> powsimp(_) # but powsimp will
(x*sqrt(y))**(5/2)
>>> powsimp(x*y*a) # but won't when doing so would violate assumptions
x*y*sqrt(x*sqrt(y))

3.6.2 source()

Another useful option is the source() function. This will print the source code of a func-
tion, including any docstring that it may have. You can also do function?? in ipython. For
example, from SymPy 0.6.5:

>>> source(simplify) # simplify() is actually only 2 lines of code. #doctest: +SKIP

In file: ./sympy/simplify/simplify.py
def simplify(expr):
(continues on next page)

82 Chapter 3. Gotchas and Pitfalls

 SymPy Documentation, Release 1.3

(continued from previous page)

”””Naively simplifies the given expression.
...
Simplification is not a well defined term and the exact strategies
this function tries can change in the future versions of SymPy. If
your algorithm relies on ”simplification” (whatever it is), try to
determine what you need exactly - is it powsimp()? radsimp()?
together()?, logcombine()?, or something else? And use this particular
function directly, because those are well defined and thus your algorithm
will be robust.
...
”””
expr = Poly.cancel(powsimp(expr))
return powsimp(together(expr.expand()), combine='exp', deep=True)

3.6. Getting help from within SymPy 83

SymPy Documentation, Release 1.3

84 Chapter 3. Gotchas and Pitfalls

 CHAPTER

FOUR

SYMPY USER’S GUIDE

4.1 Introduction

If you are new to SymPy, start with the Tutorial (page 5). If you went through it, now it’s time
to learn how SymPy works internally, which is what this guide is about. Once you grasp the
ideas behind SymPy, you will be able to use it effectively and also know how to extend it and
fix it. You may also be just interested in SymPy Modules Reference (page 95).

4.2 Learning SymPy

Everyone has different ways of understanding the code written by others.

4.2.1 Ondřej’s approach

Let’s say I’d like to understand how x + y + x works and how it is possible that it gets sim-
plified to 2*x + y.
I write a simple script, I usually call it t.py (I don’t remember anymore why I call it that way):

from sympy.abc import x, y

e = x + y + x

print e

And I try if it works

$ python t.py
y + 2*x
Now I start winpdb on it (if you’ve never used winpdb – it’s an excellent multiplatform debug-
ger, works on Linux, Windows and Mac OS X):
$ winpdb t.py
y + 2*x
and a winpdb window will popup, I move to the next line using F6:

85
SymPy Documentation, Release 1.3

Then I step into (F7) and after a little debugging I get for example:

86 Chapter 4. SymPy User’s Guide

 SymPy Documentation, Release 1.3

Tip: Make the winpdb window larger on your screen, it was just made smaller to fit in this
guide.

I see values of all local variables in the left panel, so it’s very easy to see what’s happening. You
can see, that the y + 2*x is emerging in the obj variable. Observing that obj is constructed
from c_part and nc_part and seeing what c_part contains (y and 2*x). So looking at the line
28 (the whole line is not visible on the screenshot, so here it is):

c_part, nc_part, lambda_args, order_symbols = cls.flatten(map(_sympify, args))

you can see that the simplification happens in cls.flatten. Now you can set the breakpoint
on the line 28, quit winpdb (it will remember the breakpoint), start it again, hit F5, this will
stop at this breakpoint, hit F7, this will go into the function Add.flatten():

@classmethod
def flatten(cls, seq):
”””
Takes the sequence ”seq” of nested Adds and returns a flatten list.

Returns: (commutative_part, noncommutative_part, lambda_args,

order_symbols)

Applies associativity, all terms are commutable with respect to

addition.
”””
terms = {} # term -> coeff
# e.g. x**2 -> 5 for ... + 5*x**2 + ...

coeff = S.Zero # standalone term

# e.g. 3 + ...
lambda_args = None
order_factors = []
while seq:
o = seq.pop(0)

and then you can study how it works. I am going to stop here, this should be enough to get
you going – with the above technique, I am able to understand almost any Python code.

4.3 SymPy’s Architecture

We try to make the sources easily understandable, so you can look into the sources and read
the doctests, it should be well documented and if you don’t understand something, ask on the
mailinglist.
You can find all the decisions archived in the issues, to see rationale for doing this and that.

4.3.1 Basics

All symbolic things are implemented using subclasses of the Basic class. First, you need to
create symbols using Symbol(”x”) or numbers using Integer(5) or Float(34.3). Then you

4.3. SymPy’s Architecture 87

SymPy Documentation, Release 1.3

construct the expression using any class from SymPy. For example Add(Symbol(”a”), Sym-
bol(”b”)) gives an instance of the Add class. You can call all methods, which the particular
class supports.
For easier use, there is a syntactic sugar for expressions.
For example, cos(x) + 1 is equal to cos(x).__add__(1) is equal to Add(cos(x), Inte-
ger(1))
This works becauses Python allows you to override the behavior of built-in operations +, *,
-, / etc., by defining methods with names __add__, __mul__ etc., so cos(x) + 1 is evaluated
as cos(x).__add__(1).
Then, in the __add__, __mul__ methods defined for SymPy objects, new Add or Mul objects
are constructed. Python types are also converted to SymPy types through the sympify()
function. Thus, cos(x).__add__(1) returns Add(cos(x), Integer(1)).
Similarly, 2/cos(x) is equal to cos(x).__rdiv__(2) is equal to Mul(Integer(2),
Pow(cos(x), Integer(-1))).
Note that 2/cos(x) calls cos(x).__rdiv__(2) instead of (2).__div__(cos(x)) because 2
(type int) does not know how to be divided by cos(x). (Note: In Python 3, __div__ is replaced
by __truediv__ and __rdiv__ is replaced by __rtruediv__.)
So, you can write normal expressions using python arithmetics like this:

a = Symbol(”a”)
b = Symbol(”b”)
e = (a + b)**2
print e

but from the SymPy point of view, we just need the classes Add, Mul, Pow, Rational, Integer.

4.3.2 Automatic evaluation to canonical form

For computation, all expressions need to be in a canonical form, this is done during the cre-
ation of the particular instance and only inexpensive operations are performed, necessary to
put the expression in the canonical form. So the canonical form doesn’t mean the simplest
possible expression. The exact list of operations performed depend on the implementation.
Obviously, the definition of the canonical form is arbitrary, the only requirement is that all
equivalent expressions must have the same canonical form. We tried the conversion to a
canonical (standard) form to be as fast as possible and also in a way so that the result is what
you would write by hand - so for example b*a + -4 + b + a*b + 4 + (a + b)**2 becomes
2*a*b + b + (a + b)**2.
Whenever you construct an expression, for example Add(x, x), the Add.__new__() is called
and it determines what to return. In this case:

>>> from sympy import Add

>>> from sympy.abc import x
>>> e = Add(x, x)
>>> e
2*x

>>> type(e)
<class 'sympy.core.mul.Mul'>

e is actually an instance of Mul(2, x), because Add.__new__() returned Mul.

88 Chapter 4. SymPy User’s Guide

 SymPy Documentation, Release 1.3

4.3.3 Comparisons

Expressions can be compared using a regular python syntax:

>>> from sympy.abc import x, y

>>> x + y == y + x
True

>>> x + y == y - x
False

We made the following decision in SymPy: a = Symbol(”x”) and another b = Symbol(”x”)

(with the same string “x”) is the same thing, i.e. a == b is True. We chose a == b, because
it is more natural - exp(x) == exp(x) is also True for the same instance of x but different
instances of exp, so we chose to have exp(x) == exp(x) even for different instances of x.
Sometimes, you need to have a unique symbol, for example as a temporary one in some
calculation, which is going to be substituted for something else at the end anyway. This is
achieved using Dummy(”x”). So, to sum it up:

>>> from sympy import Symbol, Dummy

>>> Symbol(”x”) == Symbol(”x”)
True

>>> Dummy(”x”) == Dummy(”x”)

False

4.3.4 Debugging

Starting with 0.6.4, you can turn on/off debug messages with the environment variable
SYMPY_DEBUG, which is expected to have the values True or False. For example, to turn on
debugging, you would issue:

[user@localhost]: SYMPY_DEBUG=True ./bin/isympy

4.3.5 Functionality

There are no given requirements on classes in the library. For example, if they don’t imple-
ment the fdiff() method and you construct an expression using such a class, then trying to
use the Basic.series() method will raise an exception of not finding the fdiff() method
in your class. This “duck typing” has an advantage that you just implement the functionality
which you need.
You can define the cos class like this:

class cos(Function):
pass

and use it like 1 + cos(x), but if you don’t implement the fdiff() method, you will not be
able to call (1 + cos(x)).series().
The symbolic object is characterized (defined) by the things which it can do, so implementing
more methods like fdiff(), subs() etc., you are creating a “shape” of the symbolic object.
Useful things to implement in new classes are: hash() (to use the class in comparisons),

4.3. SymPy’s Architecture 89

SymPy Documentation, Release 1.3

fdiff() (to use it in series expansion), subs() (to use it in expressions, where some parts are
being substituted) and series() (if the series cannot be computed using the general Basic.
series() method). When you create a new class, don’t worry about this too much - just try to
use it in your code and you will realize immediately which methods need to be implemented
in each situation.
All objects in sympy are immutable - in the sense that any operation just returns a new in-
stance (it can return the same instance only if it didn’t change). This is a common mistake to
change the current instance, like self.arg = self.arg + 1 (wrong!). Use arg = self.arg
+ 1; return arg instead. The object is immutable in the sense of the symbolic expression it
represents. It can modify itself to keep track of, for example, its hash. Or it can recalculate
anything regarding the expression it contains. But the expression cannot be changed. So you
can pass any instance to other objects, because you don’t have to worry that it will change,
or that this would break anything.

4.3.6 Conclusion

Above are the main ideas behind SymPy that we try to obey. The rest depends on the current
implementation and may possibly change in the future. The point of all of this is that the
interdependencies inside SymPy should be kept to a minimum. If one wants to add new
functionality to SymPy, all that is necessary is to create a subclass of Basic and implement
what you want.

4.3.7 Functions

How to create a new function with one variable:

class sign(Function):

nargs = 1

@classmethod
def eval(cls, arg):
if isinstance(arg, Basic.NaN):
return S.NaN
if isinstance(arg, Basic.Zero):
return S.Zero
if arg.is_positive:
return S.One
if arg.is_negative:
return S.NegativeOne
if isinstance(arg, Basic.Mul):
coeff, terms = arg.as_coeff_mul()
if not isinstance(coeff, Basic.One):
return cls(coeff) * cls(Basic.Mul(*terms))

is_finite = True

def _eval_conjugate(self):
return self

def _eval_is_zero(self):
return isinstance(self[0], Basic.Zero)

90 Chapter 4. SymPy User’s Guide

 SymPy Documentation, Release 1.3

and that’s it. The _eval_* functions are called when something is needed. The eval is
called when the class is about to be instantiated and it should return either some simpli-
fied instance of some other class or if the class should be unmodified, return None (see
core/function.py in Function.__new__ for implementation details). See also tests in
sympy/functions/elementary/tests/test_interface.py that test this interface. You can use them
to create your own new functions.
The applied function sign(x) is constructed using

sign(x)

both inside and outside of SymPy. Unapplied functions sign is just the class itself:

sign

both inside and outside of SymPy. This is the current structure of classes in SymPy:

class BasicType(type):
pass
class MetaBasicMeths(BasicType):
...
class BasicMeths(AssumeMeths):
__metaclass__ = MetaBasicMeths
...
class Basic(BasicMeths):
...
class FunctionClass(MetaBasicMeths):
...
class Function(Basic, RelMeths, ArithMeths):
__metaclass__ = FunctionClass
...

The exact names of the classes and the names of the methods and how they work can be
changed in the future.
This is how to create a function with two variables:

class chebyshevt_root(Function):
nargs = 2

@classmethod
def eval(cls, n, k):
if not 0 <= k < n:
raise ValueError(”must have 0 <= k < n”)
return cos(S.Pi*(2*k + 1)/(2*n))

Note: the first argument of a @classmethod should be cls (i.e. not self).

Here it’s how to define a derivative of the function:

>>> from sympy import Function, sympify, cos

>>> class my_function(Function):
... nargs = 1
...
... def fdiff(self, argindex = 1):
... return cos(self.args[0])
(continues on next page)

4.3. SymPy’s Architecture 91

SymPy Documentation, Release 1.3

(continued from previous page)

...
... @classmethod
... def eval(cls, arg):
... arg = sympify(arg)
... if arg == 0:
... return sympify(0)

So guess what this my_function is going to be? Well, it’s derivative is cos and the function
value at 0 is 0, but let’s pretend we don’t know:
>>> from sympy import pprint
>>> pprint(my_function(x).series(x, 0, 10))
3 5 7 9
x x x x / 10\
x - -- + --- - ---- + ------ + O\x /
6 120 5040 362880

Looks familiar indeed:

>>> from sympy import sin
>>> pprint(sin(x).series(x, 0, 10))
3 5 7 9
x x x x / 10\
x - -- + --- - ---- + ------ + O\x /
6 120 5040 362880

Let’s try a more complicated example. Let’s define the derivative in terms of the function
itself:
>>> class what_am_i(Function):
... nargs = 1
...
... def fdiff(self, argindex = 1):
... return 1 - what_am_i(self.args[0])**2
...
... @classmethod
... def eval(cls, arg):
... arg = sympify(arg)
... if arg == 0:
... return sympify(0)

So what is what_am_i? Let’s try it:

>>> pprint(what_am_i(x).series(x, 0, 10))
3 5 7 9
x 2*x 17*x 62*x / 10\
x - -- + ---- - ----- + ----- + O\x /
3 15 315 2835

Well, it’s tanh:

>>> from sympy import tanh
>>> pprint(tanh(x).series(x, 0, 10))
3 5 7 9
x 2*x 17*x 62*x / 10\
x - -- + ---- - ----- + ----- + O\x /
3 15 315 2835

92 Chapter 4. SymPy User’s Guide

 SymPy Documentation, Release 1.3

The new functions we just defined are regular SymPy objects, you can use them all over
SymPy, e.g.:

>>> from sympy import limit

>>> limit(what_am_i(x)/x, x, 0)
1

4.3.8 Common tasks

Please use the same way as is shown below all across SymPy.
accessing parameters:

>>> from sympy import sign, sin

>>> from sympy.abc import x, y, z

>>> e = sign(x**2)
>>> e.args
(x**2,)

>>> e.args[0]
x**2

Number arguments (in Adds and Muls) will always be the first argument;
other arguments might be in arbitrary order:
>>> (1 + x + y*z).args[0]
1
>>> (1 + x + y*z).args[1] in (x, y*z)
True

>>> (y*z).args
(y, z)

>>> sin(y*z).args
(y*z,)

Never use internal methods or variables, prefixed with “_” (example: don’t use _args, use
.args instead).
testing the structure of a SymPy expression
Applied functions:

>>> from sympy import sign, exp, Function

>>> e = sign(x**2)

>>> isinstance(e, sign)

True

>>> isinstance(e, exp)

False

>>> isinstance(e, Function)

True

So e is a sign(z) function, but not exp(z) function.

Unapplied functions:

4.3. SymPy’s Architecture 93

SymPy Documentation, Release 1.3

>>> from sympy import sign, exp, FunctionClass

>>> e = sign

>>> f = exp

>>> g = Add

>>> isinstance(e, FunctionClass)

True

>>> isinstance(f, FunctionClass)

True

>>> isinstance(g, FunctionClass)

False

>>> g is Add
True

So e and f are functions, g is not a function.

4.4 Contributing

We welcome every SymPy user to participate in it’s development. Don’t worry if you’ve never
contributed to any open source project, we’ll help you learn anything necessary, just ask on
our mailinglist.
Don’t be afraid to ask anything and don’t worry that you are wasting our time if you are new
to SymPy and ask questions that maybe most of the people know the answer to – you are
not, because that’s exactly what the mailinglist is for and people answer your emails because
they want to. Also we try hard to answer every email, so you’ll always get some feedback and
pointers what to do next.

4.4.1 Improving the code

Go to issues that are sorted by priority and simply find something that you would like to get
fixed and fix it. If you find something odd, please report it into issues first before fixing it.
Feel free to consult with us on the mailinglist. Then send your patch either to the issues or
the mailinglist.
Please read our excellent SymPy Patches Tutorial at our wiki for a guide on how to write
patches to SymPy, how to work with Git, and how to make your life easier as you get started
with SymPy.

4.4.2 Improving the docs

Please see the documentation (page 95) how to fix and improve SymPy’s documentation. All
contribution is very welcome.

94 Chapter 4. SymPy User’s Guide

 CHAPTER

FIVE

SYMPY MODULES REFERENCE

Because every feature of SymPy must have a test case, when you are not sure how to use
something, just look into the tests/ directories, find that feature and read the tests for it,
that will tell you everything you need to know.
Most of the things are already documented though in this document, that is automatically
generated using SymPy’s docstrings.
Click the “modules” (modindex) link in the top right corner to easily access any SymPy module,
or use the list below:

5.1 SymPy Core

5.1.1 sympify

sympify

sympy.core.sympify.sympify(a, locals=None, convert_xor=True, strict=False, ratio-

nal=False, evaluate=None)
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 in-
stances 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 “2e-19”)
• booleans, including None (will leave None unchanged)
• lists, sets or tuples containing any of the above

Warning: Note that this function uses eval, and thus shouldn’t be used on unsani-
tized 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.

95
SymPy Documentation, Release 1.3

>>> 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(”2e-45”).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'”

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

Locals

The sympification happens with access to everything that is loaded by from sympy im-
port *; anything used in a string that is not defined by that import will be converted
to a symbol. In the following, the bitcount function is treated as a symbol and the O
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”)
(continues on next page)

96 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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 dic-
tionary. 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 single-letter and Greek-letter variables to be symbols then you can use the
clashing-symbols dictionaries that have been defined there as private variables: _clash1
(single-letter variables), _clash2 (the multi-letter Greek names) or _clash (both single
and multi-letter 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 to True, 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 to False, then arithmetic and operators will be converted
into their SymPy equivalents and the evaluate=False option will be added. Nested Add
or Mul will be denested first. This is done via an AST transformation that replaces oper-
ators with their SymPy equivalents, so if an operand redefines any of those operations,
the redefined operators will not be used.

5.1. SymPy Core 97

SymPy Documentation, Release 1.3

>>> 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 from Basic), 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]])

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

98 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> 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 opera-
tion.
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 [R51]. Please note, that 0 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 [R50].
prime object is a natural number greater than 1 that has no positive divisors other than 1
and itself. See [R54].
composite object is a positive integer that has at least one positive divisor other than 1 or
the number itself. See [R52].
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 numbers11 .
transcendental object can have only values from the set of transcendental numbers10 .
irrational object value cannot be represented exactly by Rational, see [R53].
finite
infinite object absolute value is bounded (arbitrarily large). See [R55], [R56], [R57].
negative
nonnegative object can have only negative (nonnegative) values [R49].
positive
11 http://en.wikipedia.org/wiki/Algebraic_number
10
http://en.wikipedia.org/wiki/Transcendental_number

5.1. SymPy Core 99

SymPy Documentation, Release 1.3

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

See also:
sympy.core.numbers.ImaginaryUnit (page 154) sympy.core.numbers.Zero (page 149)
sympy.core.numbers.One (page 150)

Notes

Assumption values are stored in obj._assumptions dictionary or are returned by getter meth-
ods (with property decorators) or are attributes of objects/classes.

References

5.1.3 cache

cacheit

sympy.core.cache.cacheit(func)

5.1.4 basic

Basic

class sympy.core.basic.Basic
Base class for all objects in SymPy.
Conventions:
1) Always use .args, when accessing parameters of some instance:

>>> from sympy import cot

>>> from sympy.abc import x, y

100 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> cot(x).args
(x,)

>>> cot(x).args[0]
x

>>> (x*y).args
(x, y)

>>> (x*y).args[1]
y

2) 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’.

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

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

as_content_primitive(radical=False, clear=True)
A stub to allow Basic args (like Tuple) to be skipped when computing the content
and primitive components of an expression.
See also:
sympy.core.expr.Expr.as_content_primitive (page 118)
as_poly(*gens, **args)
Converts self to a polynomial or returns None.

5.1. SymPy Core 101

SymPy Documentation, Release 1.3

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

102 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> (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 but type(S(1)) is One, a special type of sympy atom, while
type(S(2)) is type Integer 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.variables as underscore-
suffixed numbers corresponding to their position in self.variables. Enough un-
derscores are added to ensure that there will be no clash with existing free symbols.

Examples

>>> from sympy import Lambda

>>> from sympy.abc import x
>>> Lambda(x, 2*x).canonical_variables
{x: 0_}

5.1. SymPy Core 103

SymPy Documentation, Release 1.3

classmethod class_key()
Nice order of classes.
compare(other)
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

count(query)
Count the number of matching subexpressions.
count_ops(visual=None)
wrapper for count_ops that returns the operation count.
doit(**hints)
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)
Compare two expressions and handle dummy symbols.

Examples

>>> from sympy import Dummy

>>> from sympy.abc import x, y

>>> u = Dummy('u')

104 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

find(query, group=False)
Find all subexpressions matching a query.
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)
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 top-level 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
(continues on next page)

5.1. SymPy Core 105

SymPy Documentation, Release 1.3

(continued from previous page)

>>> a == a.func(*a.args)
True

has(*patterns)
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 half-open 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 to any(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
(continues on next page)

106 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> (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)
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 old-style pattern matching where expressions and patterns
are essentially solved to give the match. Both of the following give None unless
old=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)

Helper method for match() that looks for a match between Wild symbols in self and
expressions in expr.

5.1. SymPy Core 107

SymPy Documentation, Release 1.3

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

Replace matching subexpressions of self with value.
If map = True then also return the mapping {old: new} where old was a sub-
expression found with query and new is the replacement value for it. If the expression
itself doesn’t match the query, then the returned value will be self.xreplace(map)
otherwise it should be self.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 replace-
ment 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 subex-
pressions and the exact flag is True, then the match will only succeed if non-zero
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:
See also:

subs (page 111) substitution of subexpressions as defined by the objects them-

selves.
xreplace (page 113) exact node replacement in expr tree; also capable of using
matching rules

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

108 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

1.1. type -> type obj.replace(type, newtype)

When object of type type is found, replace it with the result of passing its argu-
ment(s) to newtype.

>>> 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, apply func to its argument(s). func must be
written to handle the number of arguments of type.

>>> 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 in pattern.

>>> 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, non-intuitive 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 non-zero 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))

5.1. SymPy Core 109

SymPy Documentation, Release 1.3

3.1. func -> func obj.replace(filter, func)

Replace subexpression e with func(e) if filter(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)
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 De-
finedFunction 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)
Return a sort key.

110 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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)
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.
See also:

replace (page 108) replacement capable of doing wildcard-like matching, parsing

of match, and conditional replacements
xreplace (page 113) exact node replacement in expr tree; also capable of using
matching rules
evalf calculates the given formula to a desired level of precision

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
(continues on next page)

5.1. SymPy Core 111

SymPy Documentation, Release 1.3

(continued from previous page)

>>> (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 simul-
taneous 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

112 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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)
Replace occurrences of objects within the expression.
Parameters rule : dict-like
Expresses a replacement rule
Returns xreplace : the result of the replacement
See also:

replace (page 108) replacement capable of doing wildcard-like matching, parsing

of match, and conditional replacements
subs (page 111) substitution of subexpressions as defined by the objects them-
selves.

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:

5.1. SymPy Core 113

SymPy Documentation, Release 1.3

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

Atom

class sympy.core.basic.Atom
A parent class for atomic things. An atom is an expression with no subexpressions.

Examples

Symbol, Number, Rational, Integer, … But not: Add, Mul, Pow, …

5.1.5 core

5.1.6 singleton

class sympy.core.singleton.SingletonRegistry
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 the sympy.core.singleton.Singleton class
for details). For instance, every time you create Integer(0), this will return the same
instance, sympy.core.numbers.Zero (page 149). All singleton instances are attributes
of the S object, so Integer(0) can also be accessed as S.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 of S for end users is the

114 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

convenient access to certain instances that are otherwise difficult to type, like S.Half
(instead of Rational(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 use-cases:

>>> 0 == S.Zero
True

The second thing S is is a shortcut for sympy.core.sympify.sympify() (page 95).

sympy.core.sympify.sympify() (page 95) is the function that converts Python objects
such as int(1) into SymPy objects such as Integer(1). It also converts the string form
of an expression into a SymPy expression, like sympify(”x**2”) -> Symbol(”x”)**2.
S(1) is the same thing as sympify(1) (basically, S.__call__ has been defined to call
sympify).
This is for convenience, since S is a single letter. It’s mostly useful for defining rational
numbers. Consider an expression like x + 1/2. If you enter this directly in Python, it
will evaluate the 1/2 and give 0.5 (or just 0 in Python 2, because of integer division),
because both arguments are ints (see also Two Final Notes: ^ and / (page 14)). 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 as x + Rational(1,
2), but this is a lot more typing. A shorter version is x + S(1)/2. Since S(1) returns
Integer(1), the division will return a Rational type, since it will call Integer.__div__,
which knows how to return a Rational.

5.1.7 expr

5.1.8 Expr

class sympy.core.expr.Expr
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 manip-
ulation, i.e. pattern matching, substitutions, etc).
See also:
sympy.core.basic.Basic (page 100)
apart(x=None, **args)
See the apart function in sympy.polys
args_cnc(cset=False, warn=True, split_1=True)
Return [commutative factors, non-commutative 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 setting warn to False.
Note: -1 is always separated from a Number unless split_1 is False.

5.1. SymPy Core 115

SymPy Documentation, Release 1.3

>>> 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(rational=False)
Efficiently extract the coefficient of a summation.
as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a product.
as_coeff_add(*deps)
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_exponent(x)
c*x**e -> c,e where x can be any symbolic expression.

116 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

as_coeff_mul(*deps, **kwargs)
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)
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 separa-
tion is not possible it will return None.
See also:

coeff (page 123) return sum of terms have a given factor

as_coeff_Add (page 116) separate the additive constant from an expression
as_coeff_Mul (page 116) separate the multiplicative constant from an expression
as_independent (page 120) separate x-dependent 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

Examples

>>> from sympy import E, pi, sin, I, Poly

>>> from sympy.abc import x

5.1. SymPy Core 117

SymPy Documentation, Release 1.3

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

as_coefficients_dict()
Return a dictionary mapping terms to their Rational coefficient. Since the dictio-
nary 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)
This method should recursively remove a Rational from all arguments and return
that (content) and the new self (primitive). The content should always be posi-
tive and Mul(*foo.as_content_primitive()) == foo. The primitive need not be

118 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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)
Convert a polynomial to a SymPy expression.

5.1. SymPy Core 119

SymPy Documentation, Release 1.3

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)
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 non-naive 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
See also:
separatevars (page 1187), expand (page 126), Add.as_two_terms, Mul.
as_two_terms, as_coeff_add (page 116), as_coeff_mul (page 116)

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)
(continues on next page)

120 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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

non-commutative 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)
>>> ((x-n1)*(x-y)).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

5.1. SymPy Core 121

SymPy Documentation, Release 1.3

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

as_leading_term(*symbols)
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 non-zero 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()
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_factors(order=None)
Return list of ordered factors (if Mul) else [self].

122 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

as_ordered_terms(order=None, data=False)
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()
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.
as_real_imag(deep=True, **hints)
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))

as_terms()
Transform an expression to a list of terms.
cancel(*gens, **args)
See the cancel function in sympy.polys
coeff(x, n=1, right=False)
Returns the coefficient from the term(s) containing x**n. If n is zero then all terms
independent of x will be returned.
When x is noncommutative, the coefficient to the left (default) or right of x can be
returned. The keyword ‘right’ is ignored when x is commutative.
See also:

as_coefficient (page 117) separate the expression into a coefficient and factor
as_coeff_Add (page 116) separate the additive constant from an expression

5.1. SymPy Core 123

SymPy Documentation, Release 1.3

as_coeff_Mul (page 116) separate the multiplicative constant from an expression

as_independent (page 120) separate x-dependent 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

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
(continues on next page)

124 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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

collect(syms, func=None, evaluate=True, exact=False, dis-

tribute_order_term=True)
See the collect function in sympy.simplify
combsimp()
See the combsimp function in sympy.simplify
compute_leading_term(x, logx=None)
as_leading_term is only allowed for results of .series() This is a wrapper to compute
a series first.
could_extract_minus_sign()
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.

5.1. SymPy Core 125

SymPy Documentation, Release 1.3

Examples

>>> from sympy.abc import x, y

>>> e = x - y
>>> {i.could_extract_minus_sign() for i in (e, -e)}
{False, True}

count_ops(visual=None)
wrapper for count_ops that returns the operation count.
equals(other, failing_expression=False)
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)
Expand an expression using hints.
See the docstring of the expand() function in sympy.core.function for more informa-
tion.
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 non-expression object, don’t return the free sym-
bols. Compare:

>>> from sympy import Tuple

>>> t = Tuple(x + y)
>>> t.expr_free_symbols
set()
>>> t.free_symbols
{x, y}

extract_additively(c)
Return self - c if it’s possible to subtract c from self and make all matching coeffi-
cients move towards zero, else return None.
See also:
extract_multiplicatively (page 127), coeff (page 123), as_coefficient
(page 117)

126 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

extract_branch_factor(allow_half=False)
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)
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.

>>> from sympy import symbols, Rational

5.1. SymPy Core 127

SymPy Documentation, Release 1.3

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

factor(*gens, **args)
See the factor() function in sympy.polys.polytools
fourier_series(limits=None)
Compute fourier sine/cosine series of self.
See the docstring of the fourier_series() (page 128) in sympy.series.fourier for
more information.
fps(x=None, x0=0, dir=1, hyper=True, order=4, rational=True, full=False)
Compute formal power power series of self.
See the docstring of the fps() (page 128) function in sympy.series.formal for more
information.
gammasimp()
See the gammasimp function in sympy.simplify
getO()
Returns the additive O(..) symbol if there is one, else None.
getn()
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()

integrate(*args, **kwargs)
See the integrate function in sympy.integrals
invert(g, *gens, **args)
Return the multiplicative inverse of self mod g where self (and g) may be symbolic
expressions).

128 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
sympy.core.numbers.mod_inverse, sympy.polys.polytools.invert (page 832)
is_algebraic_expr(*syms)
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.
See also:
is_rational_function (page 132)

References

• http://en.wikipedia.org/wiki/Algebraic_expression

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

is_constant(*wrt, **flags)
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 dif-
ferent 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.

5.1. SymPy Core 129

SymPy Documentation, Release 1.3

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 fail-
ing_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 than if not self.free_symbols, however, since
is_number will fail as soon as it hits a free symbol or undefined function.
See also:
sympy.core.basic.is_comparable

130 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

is_polynomial(*syms)
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’, polyno-
mial=True).

Examples

>>> from sympy import Symbol

>>> x = Symbol('x')
>>> ((x**2 + 1)**4).is_polynomial(x)
(continues on next page)

5.1. SymPy Core 131

SymPy Documentation, Release 1.3

(continued from previous page)

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)
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 sym-
bolic 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’, ratio-
nal_function=True).

Examples

>>> from sympy import Symbol, sin

>>> from sympy.abc import x, y

>>> (x/y).is_rational_function()
True

132 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

limit(x, xlim, dir=’+’)

Compute limit x->xlim.
lseries(x=None, x0=0, dir=’+’, logx=None)
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)
Wrapper to _eval_nseries if assumptions allow, else to series.

5.1. SymPy Core 133

SymPy Documentation, Release 1.3

If x is given, x0 is 0, dir=’+’, and self has x, then _eval_nseries is called. This calcu-
lates “n” terms in the innermost expressions and then builds up the final series just
by “cross-multiplying” 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 since
sin 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)

See the nsimplify function in sympy.simplify
powsimp(*args, **kwargs)
See the powsimp function in sympy.simplify

134 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

primitive()
Return the positive Rational that can be extracted non-recursively 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

radsimp(**kwargs)
See the radsimp function in sympy.simplify
ratsimp()
See the ratsimp function in sympy.simplify
refine(assumption=True)
See the refine function in sympy.assumptions
removeO()
Removes the additive O(..) symbol if there is one
round(p=0)
Return x rounded to the given decimal place.
If a complex number would results, apply round to the real and imaginary compo-
nents of the number.

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

Examples

5.1. SymPy Core 135

SymPy Documentation, Release 1.3

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

separate(deep=False, force=False)
See the separate function in sympy.simplify
series(x=None, x0=0, n=6, dir=’+’, logx=None)
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 to x up
to O((x - x0)**n, x, x0) (default n is 6).
If x=None and self 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 for dir=- the series
from the left. For smooth functions this flag will not alter the results.

>>> abs(x).series(dir=”+”)
x
(continues on next page)

136 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> abs(x).series(dir=”-”)
-x

simplify(ratio=1.7, measure=None, rational=False, inverse=False)

See the simplify function in sympy.simplify
taylor_term(n, x, *previous_terms)
General method for the taylor term.
This method is slow, because it differentiates n-times. Subclasses can redefine it to
make it faster by using the “previous_terms”.
together(*args, **kwargs)
See the together function in sympy.polys
trigsimp(**args)
See the trigsimp function in sympy.simplify

5.1.9 UnevaluatedExpr

class sympy.core.expr.UnevaluatedExpr
Expression that is not evaluated unless released.

Examples

>>> from sympy import UnevaluatedExpr

>>> from sympy.abc import a, b, x, y
>>> x*(1/x)
1
>>> x*UnevaluatedExpr(1/x)
x*1/x

5.1.10 AtomicExpr

class sympy.core.expr.AtomicExpr
A parent class for object which are both atoms and Exprs.
For example: Symbol, Number, Rational, Integer, … But not: Add, Mul, Pow, …

5.1.11 symbol

Symbol

class sympy.core.symbol.Symbol
Assumptions: commutative = True
You can override the default assumptions in the constructor:

5.1. SymPy Core 137

SymPy Documentation, Release 1.3

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

as_dummy()
Return a Dummy having the same name and same assumptions as self.

Wild

class sympy.core.symbol.Wild
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 in properties need to return True 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:

138 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> 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
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)
Transform strings into instances of Symbol (page 137) class.

5.1. SymPy Core 139

SymPy Documentation, Release 1.3

symbols() (page 139) function returns a sequence of symbols with names taken from
names 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 to True 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
(continues on next page)

140 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

()
>>> 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() (page 139) can create symbol-like objects like instances of
Function or Wild classes. To achieve this, set cls 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)
Create symbols and inject them into the global namespace.

5.1. SymPy Core 141

SymPy Documentation, Release 1.3

This calls symbols() (page 139) with the same arguments and puts the results into the
global namespace. It’s recommended not to use var() (page 141) in library code, where
symbols() (page 139) 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
to var() (page 141).

5.1.12 numbers

Number

class sympy.core.numbers.Number
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 repre-
sented by the Integer class. Float and Rational are subclasses of Number; Integer is a
subclass of Rational.
For example, 2/3 is represented as Rational(2, 3) which is a different object from
the floating point number obtained with Python division 2/3. Even for numbers that
are exactly represented in binary, there is a difference between how two forms, such as
Rational(1, 2) and Float(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 numbers 3 +
4*I, are not instances of Number class as they are not atomic.
See also:
Float (page 143), Integer (page 147), Rational (page 145)
as_coeff_Add(rational=False)
Efficiently extract the coefficient of a summation.
as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a product.

142 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

cofactors(other)
Compute GCD and cofactors of self and other.
gcd(other)
Compute GCD of self and other.
lcm(other)
Compute LCM of self and other.

Float

class sympy.core.numbers.Float
Represent a floating-point number of arbitrary precision.

Notes

Floats are inexact by their nature unless their value is a binary-exact 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 5-digit
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 high-precision 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 20-digit 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 in-
crease the accuracy – the underlying value is not changed:

5.1. SymPy Core 143

SymPy Documentation, Release 1.3

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

Examples

>>> from sympy import Float

>>> Float(3.5)
3.50000000000000
>>> Float(3)
3.00000000000000

Creating Floats from strings (and Python int and long types) will give a minimum pre-
cision of 15 digits, but the precision will automatically increase to capture all digits
entered.

>>> Float(1)
1.00000000000000
>>> Float(10**20)
100000000000000000000.
(continues on next page)

144 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> Float('1e20')
100000000000000000000.

However, floating-point 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 high-precision decimal numbers as strings:

Float(‘1.23456789123456789’) 1.23456789123456789
The desired number of digits can also be specified:

>>> Float('1e-3', 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('12e-3', '')
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('600e-2', '') # 3 digits significant
6.00

Attributes

is_irrational
is_rational

Rational

class sympy.core.numbers.Rational
Represents rational numbers (p/q) of any size.

5.1. SymPy Core 145

SymPy Documentation, Release 1.3

See also:
sympify, sympy.simplify.simplify.nsimplify (page 1190)

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 denomina-
tor 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('1e-2')
1/100
>>> Rational(”.1”)
1/10
>>> Rational('1e-2/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

146 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Low-level

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

as_coeff_Add(rational=False)
Efficiently extract the coefficient of a summation.
as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a product.
as_content_primitive(radical=False, clear=True)
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.

factors(limit=None, use_trial=True, use_rho=False, use_pm1=False, ver-
bose=False, visual=False)
A wrapper to factorint which return factors of self that are smaller than limit (or
cheap to compute). Special methods of factoring are disabled by default so that
only trial division is used.
limit_denominator(max_denominator=1000000)
Closest Rational to self with denominator at most max_denominator.

>>> from sympy import Rational

>>> Rational('3.141592653589793').limit_denominator(10)
22/7
>>> Rational('3.141592653589793').limit_denominator(100)
311/99

Integer

class sympy.core.numbers.Integer
Represents integer numbers of any size.

5.1. SymPy Core 147

SymPy Documentation, Release 1.3

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 au-
tomatically converted to Integer when they are used in SymPy expressions.

NumberSymbol

class sympy.core.numbers.NumberSymbol

approximation(number_cls)
Return an interval with number_cls endpoints that contains the value of Number-
Symbol. If not implemented, then return None.

RealNumber

sympy.core.numbers.RealNumber
alias of sympy.core.numbers.Float (page 143)

igcd

sympy.core.numbers.igcd(*args)
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

148 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ilcm

sympy.core.numbers.ilcm(*args)
Computes integer least common multiple.

Examples

>>> from sympy.core.numbers import ilcm

>>> ilcm(5, 10)
10
>>> ilcm(7, 3)
21
>>> ilcm(5, 10, 15)
30

seterr

sympy.core.numbers.seterr(divide=False)
Should sympy raise an exception on 0/0 or return a nan?
divide == True …. raise an exception divide == False … return nan

Zero

class sympy.core.numbers.Zero
The number zero.
Zero is a singleton, and can be accessed by S.Zero

References

[R58]

Examples

>>> from sympy import S, Integer, zoo

>>> Integer(0) is S.Zero
True
>>> 1/S.Zero
zoo

as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a summation.

5.1. SymPy Core 149

SymPy Documentation, Release 1.3

One

class sympy.core.numbers.One
The number one.
One is a singleton, and can be accessed by S.One.

References

[R59]

Examples

>>> from sympy import S, Integer

>>> Integer(1) is S.One
True

NegativeOne

class sympy.core.numbers.NegativeOne
The number negative one.
NegativeOne is a singleton, and can be accessed by S.NegativeOne.
See also:
One (page 150)

References

[R60]

Examples

>>> from sympy import S, Integer

>>> Integer(-1) is S.NegativeOne
True

Half

class sympy.core.numbers.Half
The rational number 1/2.
Half is a singleton, and can be accessed by S.Half.

References

[R61]

150 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import S, Rational

>>> Rational(1, 2) is S.Half
True

NaN

class sympy.core.numbers.NaN
Not a Number.
This serves as a place holder for numeric values that are indeterminate. Most opera-
tions on NaN, produce another NaN. Most indeterminate forms, such as 0/0 or oo -
oo` produce NaN. Two exceptions are ``0**0 and oo**0, which all produce 1 (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 counter-intuitive 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 as nan.

References

[R62]

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

5.1. SymPy Core 151

SymPy Documentation, Release 1.3

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
Positive infinite quantity.
In real analysis the symbol ∞ denotes an unbounded limit: x → ∞ 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 +∞ and −∞ can be added to the topological space of
the real numbers, producing the two-point 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 as oo.
See also:
NegativeInfinity (page 152), NaN (page 151)

References

[R63]

Examples

>>> from sympy import oo, exp, limit, Symbol

>>> 1 + oo
oo
>>> 42/oo
0
>>> x = Symbol('x')
>>> limit(exp(x), x, oo)
oo

NegativeInfinity

class sympy.core.numbers.NegativeInfinity
Negative infinite quantity.

152 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

NegativeInfinity is a singleton, and can be accessed by S.NegativeInfinity.

See also:
Infinity (page 152)

ComplexInfinity

class sympy.core.numbers.ComplexInfinity
Complex infinity.
In complex analysis the symbol ∞,
˜ 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 as zoo.
See also:
Infinity (page 152)

Examples

>>> from sympy import zoo, oo

>>> zoo + 42
zoo
>>> 42/zoo
0
>>> zoo + zoo
nan
>>> zoo*zoo
zoo

Exp1

class sympy.core.numbers.Exp1
The e constant.
The transcendental number e = 2.718281828 . . . 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 as E.

References

[R64]

Examples

5.1. SymPy Core 153

SymPy Documentation, Release 1.3

>>> from sympy import exp, log, E

>>> E is exp(1)
True
>>> log(E)
1

ImaginaryUnit

class sympy.core.numbers.ImaginaryUnit
√
The imaginary unit, i = −1.
I is a singleton, and can be accessed by S.I, or can be imported as I.

References

[R65]

Examples

>>> from sympy import I, sqrt

>>> sqrt(-1)
I
>>> I*I
-1
>>> 1/I
-I

Pi

class sympy.core.numbers.Pi
The π constant.
The transcendental number π = 3.141592654 . . . represents the ratio of a circle’s circumfer-
ence to its diameter, the area of the unit circle, the half-period of trigonometric functions,
and many other things in mathematics.
Pi is a singleton, and can be accessed by S.Pi, or can be imported as pi.

References

[R66]

Examples

154 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

EulerGamma

class sympy.core.numbers.EulerGamma
The Euler-Mascheroni constant.
γ = 0.5772157 . . . (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:
( n )
∑1
γ = lim − ln n
n→∞ k
k=1

EulerGamma is a singleton, and can be accessed by S.EulerGamma.

References

[R67]

Examples

>>> from sympy import S

>>> S.EulerGamma.is_irrational
>>> S.EulerGamma > 0
True
>>> S.EulerGamma > 1
False

Attributes

is_irrational

Catalan

class sympy.core.numbers.Catalan
Catalan’s constant.

5.1. SymPy Core 155

SymPy Documentation, Release 1.3

K = 0.91596559 . . . is given by the infinite series

∞
∑ (−1)k
K=
(2k + 1)2
k=0

Catalan is a singleton, and can be accessed by S.Catalan.

References

[R68]

Examples

>>> from sympy import S

>>> S.Catalan.is_irrational
>>> S.Catalan > 0
True
>>> S.Catalan > 1
False

Attributes

is_irrational

GoldenRatio

class sympy.core.numbers.GoldenRatio
The golden ratio, ϕ.
√
ϕ = 1+2 5 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.

References

[R69]

Examples

>>> from sympy import S

>>> S.GoldenRatio > 1
True
>>> S.GoldenRatio.expand(func=True)
1/2 + sqrt(5)/2
>>> S.GoldenRatio.is_irrational
True

156 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

TribonacciConstant

class sympy.core.numbers.TribonacciConstant
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 x3 − x2 − x − 1 = 0, and also satisfies the equation x + x−3 = 2.
TribonacciConstant is a singleton, and can be accessed by S.TribonacciConstant.

References

[R70]

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

5.1.13 power

Pow

class sympy.core.power.Pow
Defines the expression x**y as “x raised to a power y”
Singleton definitions involving (0, 1, -1, oo, -oo, I, -I):

5.1. SymPy Core 157

SymPy Documentation, Release 1.3

expr value reason

z**0 1 Although arguments over 0**0 exist, see [2].
z**1 z
(-oo)**(- 0
1)
(-1)**-1 -1
S.Zero**- zoo This is not strictly true, as 0**-1 may be undefined, but is convenient
1 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 conve-
nient, however, when the base is positive.
1**oo nan Because there are various cases where lim(x(t),t)=1, lim(y(t),t)=oo
1**-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 nan Because of oscillations in the limit.
(-1)**(-
oo)
oo**oo oo
oo**-oo 0
(- nan
oo)**oo
(-oo)**-
oo
oo**I (- nan oo**e could probably be best thought of as the limit of x**e for real
oo)**I 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) 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**(- 0 If the real part of e is negative, then the limit is 0.
1+I)
-oo**(-
1+I)

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 test-case code in the calculation of limits.
See also:
sympy.core.numbers.Infinity (page 152), sympy.core.numbers.NegativeInfinity
(page 152), sympy.core.numbers.NaN (page 151)

References

[R71], [R72], [R73]

as_base_exp()
Return base and exp of self.

158 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

5.1. SymPy Core 159

SymPy Documentation, Release 1.3

integer_nthroot

sympy.core.power.integer_nthroot(y, n)
Return a tuple containing x = floor(y**(1/n)) and a boolean indicating whether the result
is exact (that is, whether x**n == y).
See also:
sympy.ntheory.primetest.is_square, integer_log

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

5.1.14 mul

Mul

class sympy.core.mul.Mul

as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a product.
as_coefficients_dict()
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)
Return the tuple (R, self/R) where R is the positive Rational extracted from self.

160 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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)
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()
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)
Return commutative, noncommutative and order arguments by combining related
terms.

Notes

• In an expression like a*b*c, python process this through sympy as Mul(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 2-arg Mul behavior
2*x + 2
>>> y*(x + 1)*2
(continues on next page)

5.1. SymPy Core 161

SymPy Documentation, Release 1.3

(continued from previous page)

2*y*(x + 1)
>>> 2*(x + 1)*y # 2-arg 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. Post-processing may be nec-
essary 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 re-processed for each new argument. So if each of a, b and c were Mul
(page 160) expression, then a*b*c (or building up the product with *=) will
process all the arguments of a and b twice: once when a*b is computed and
again when c 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 argu-
ments 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 by d[i]
and multiply by n[i] and you suspect there are many repeats in n. It would be
better to compute M*n[i]/d[i] rather than M/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 the d[i] first (and those are more unique
than the n[i]) then that will create a new Mul, M/d[i] the args of which will be
traversed again when it is multiplied by n[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__.

162 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

prod

sympy.core.mul.prod(a, start=1)
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

5.1.15 add

Add

class sympy.core.add.Add

as_coeff_Add(rational=False)
Efficiently extract the coefficient of a summation.
as_coeff_add(*deps)
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()
Return a dictionary mapping terms to their Rational coefficient. Since the dictio-
nary 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.

5.1. SymPy Core 163

SymPy Documentation, Release 1.3

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

164 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import x, y

>>> (3*x - 2*y + 5).as_two_terms()
(5, 3*x - 2*y)

classmethod class_key()
Nice order of classes
extract_leading_order(symbols, point=None)
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)
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:
sympy.core.mul.Mul.flatten (page 161)
primitive()
Return (R, self/R) where R` is the Rational GCD of self`.
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)

5.1. SymPy Core 165

SymPy Documentation, Release 1.3

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

5.1.16 mod

Mod

class sympy.core.mod.Mod
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

5.1.17 relational

Rel

sympy.core.relational.Rel
alias of sympy.core.relational.Relational

Eq

sympy.core.relational.Eq
alias of sympy.core.relational.Equality (page 167)

Ne

sympy.core.relational.Ne
alias of sympy.core.relational.Unequality (page 174)

Lt

sympy.core.relational.Lt
alias of sympy.core.relational.StrictLessThan (page 178)

166 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Le

sympy.core.relational.Le
alias of sympy.core.relational.LessThan (page 171)

Gt

sympy.core.relational.Gt
alias of sympy.core.relational.StrictGreaterThan (page 175)

Ge

sympy.core.relational.Ge
alias of sympy.core.relational.GreaterThan (page 168)

Equality

class sympy.core.relational.Equality
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.
See also:

sympy.logic.boolalg.Equivalent (page 749) for representing equality between two

boolean expressions

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 e valE q method, it can be used in place of the default algorithm.
If lhs.e valE q(rhs) or rhs.e valE q(lhs) returns anything other than None, that return value
will be substituted for the Equality. If None is returned by e valE q, an Equality object will
be created as usual.

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
(continues on next page)

5.1. SymPy Core 167

SymPy Documentation, Release 1.3

(continued from previous page)

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

GreaterThan

class sympy.core.relational.GreaterThan
Class representations of inequalities.
The *Than classes represent inequal relationships, where the left-hand side is generally
bigger or smaller than the right-hand side. For example, the GreaterThan class repre-
sents an inequal relationship where the left-hand 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
(continues on next page)

168 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> '%s >= %s is the same as %s <= %s' % (e.gts, e.lts, e.lts, e.gts)
'x >= 1 is the same as 1 <= x'

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, per-
haps), one can work around this annoyance in a couple ways:
(1) “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)
(continues on next page)

5.1. SymPy Core 169

SymPy Documentation, Release 1.3

(continued from previous page)

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 [R74], 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

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

170 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

LessThan

class sympy.core.relational.LessThan
Class representations of inequalities.
The *Than classes represent inequal relationships, where the left-hand side is generally
bigger or smaller than the right-hand side. For example, the GreaterThan class repre-
sents an inequal relationship where the left-hand 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
(continues on next page)

5.1. SymPy Core 171

SymPy Documentation, Release 1.3

(continued from previous page)

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

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, per-
haps), one can work around this annoyance in a couple ways:
(1) “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):
(continues on next page)

172 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

...
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 [R75], 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

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

5.1. SymPy Core 173

SymPy Documentation, Release 1.3

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

Unequality

class sympy.core.relational.Unequality
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.
See also:
Equality (page 167)

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 e valE q methods.

Examples

>>> from sympy import Ne

>>> from sympy.abc import x, y
>>> Ne(y, x+x**2)
Ne(y, x**2 + x)

174 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

StrictGreaterThan

class sympy.core.relational.StrictGreaterThan
Class representations of inequalities.
The *Than classes represent inequal relationships, where the left-hand side is generally
bigger or smaller than the right-hand side. For example, the GreaterThan class repre-
sents an inequal relationship where the left-hand 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'

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

5.1. SymPy Core 175

SymPy Documentation, Release 1.3

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, per-
haps), one can work around this annoyance in a couple ways:
(1) “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 [R76], there is no way for

SymPy to create a chained inequality with that syntax so one must use And:

176 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

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

5.1. SymPy Core 177

SymPy Documentation, Release 1.3

StrictLessThan

class sympy.core.relational.StrictLessThan
Class representations of inequalities.
The *Than classes represent inequal relationships, where the left-hand side is generally
bigger or smaller than the right-hand side. For example, the GreaterThan class repre-
sents an inequal relationship where the left-hand 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'

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

178 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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, per-
haps), one can work around this annoyance in a couple ways:
(1) “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 [R77], there is no way for

SymPy to create a chained inequality with that syntax so one must use And:

5.1. SymPy Core 179

SymPy Documentation, Release 1.3

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

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

180 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.1.18 multidimensional

vectorize

class sympy.core.multidimensional.vectorize(*mdargs)
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)]]

5.1.19 function

Lambda

class sympy.core.function.Lambda
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

5.1. SymPy Core 181

SymPy Documentation, Release 1.3

A handy shortcut for lots of arguments:

>>> p = x, y, z
>>> f = Lambda(p, x + y*z)
>>> f(*p)
x + y*z

expr
The return value of the function
is_identity
Return True if this Lambda is an identity function.
variables
The variables used in the internal representation of the function

WildFunction

class sympy.core.function.WildFunction(name, **assumptions)

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. if nargs = (1, 2) then functions with 1 or 2 arguments will
be matched.

182 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> 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
Carries out differentiation of the given expression with respect to symbols.
expr must define ._eval_derivative(symbol) method that returns the differentiation result.
This function only needs to consider the non-trivial 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.
Simplification of high-order derivatives:
Because there can be a significant amount of simplification that can be done when mul-
tiple differentiations are performed, results will be automatically simplified in a fairly
conservative fashion unless the keyword simplify is set to False.

>>> from sympy import sqrt, diff

>>> from sympy.abc import x
>>> 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 can not be evaluated, the list of differen-
tiation symbols will be sorted, that is, the expression is assumed to have continuous
derivatives up to the order asked. This sorting assumes that derivatives wrt Symbols
commute, derivatives wrt non-Symbols commute, but Symbol and non-Symbol deriva-
tives don’t commute with each other.
Derivative wrt non-Symbols:
This class also allows derivatives wrt non-Symbols that have _diff_wrt set to True, such
as Function and Derivative. When a derivative wrt a non- Symbol is attempted, the non-
Symbol is temporarily converted to a Symbol while the differentiation is performed.
Note that this may seem strange, that Derivative allows things like f(g(x)).diff(g(x)), or
even f(cos(x)).diff(cos(x)). The motivation for allowing this syntax is to make it easier
to work with variational calculus (i.e., the Euler-Lagrange method). The best way to
understand this is that the action of derivative with respect to a non-Symbol is defined
by the above description: the object is substituted for a Symbol and the derivative is
taken with respect to that. This action is only allowed for objects for which this can be
done unambiguously, for example Function and Derivative objects. Note that this leads
to what may appear to be mathematically inconsistent results. For example:

5.1. SymPy Core 183

SymPy Documentation, Release 1.3

>>> from sympy import cos, sin, sqrt

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

This appears wrong because in fact 2*cos(x) and 2*sqrt(1 - sin(x)**2) are identically
equal. However this is the wrong way to think of this. Think of it instead as if we have
something like this:

>>> from sympy.abc import c, s, u, x

>>> def F(u):
... return 2*u
...
>>> def G(u):
... return 2*sqrt(1 - u**2)
...
>>> F(cos(x))
2*cos(x)
>>> G(sin(x))
2*sqrt(-sin(x)**2 + 1)
>>> F(c).diff(c)
2
>>> F(cos(x)).diff(cos(x))
2
>>> G(s).diff(c)
0
>>> G(sin(x)).diff(cos(x))
0

Here, the Symbols c and s act just like the functions cos(x) and sin(x), respectively.
Think of 2*cos(x) as f(c).subs(c, cos(x)) (or f(c) at c = cos(x)) and 2*sqrt(1 - sin(x)**2)
as g(s).subs(s, sin(x)) (or g(s) at s = sin(x)), where f(u) == 2*u and g(u) == 2*sqrt(1
- u**2). Here, we define the function first and evaluate it at the function, but we can
actually unambiguously do this in reverse in SymPy, because expr.subs(Function, Sym-
bol) is well-defined: just structurally replace the function everywhere it appears in the
expression.
This is the same notational convenience used in the Euler-Lagrange method when one
says F(t, f(t), f’(t)).diff(f(t)). What is actually meant is that the expression in question is
represented by some F(t, u, v) at u = f(t) and v = f’(t), and F(t, f(t), f’(t)).diff(f(t)) simply
means F(t, u, v).diff(u) at u = f(t).
We do not allow derivatives to be taken with respect to expressions where this is not
so well defined. For example, we do not allow expr.diff(x*y) because there are multiple
ways of structurally defining where x*y appears in an expression, some of which may
surprise the reader (for example, a very strict definition would have that (x*y*z).diff(x*y)
== 0).

>>> from sympy.abc import x, y, z

>>> (x*y*z).diff(x*y)
Traceback (most recent call last):
...
ValueError: Can't differentiate wrt the variable: x*y, 1

Note that this definition also fits in nicely with the definition of the chain rule. Note how

184 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

the chain rule in SymPy is defined using unevaluated Subs objects:

>>> from sympy import symbols, Function

>>> f, g = symbols('f g', cls=Function)
>>> f(2*g(x)).diff(x)
2*Derivative(g(x), x)*Subs(Derivative(f(_xi_1), _xi_1),
(_xi_1,), (2*g(x),))
>>> f(g(x)).diff(x)
Derivative(g(x), x)*Subs(Derivative(f(_xi_1), _xi_1),
(_xi_1,), (g(x),))

Finally, note that, to be consistent with variational calculus, and to ensure that the defini-
tion of substituting a Function for a Symbol in an expression is well-defined, derivatives
of functions are assumed to not be related to the function. In other words, we have:

>>> from sympy import diff

>>> diff(f(x), x).diff(f(x))
0

The same is true for derivatives of different orders:

>>> diff(f(x), x, 2).diff(diff(f(x), x, 1))

0
>>> diff(f(x), x, 1).diff(diff(f(x), x, 2))
0

Note, any class can allow derivatives to be taken with respect to itself. See the docstring
of Expr._diff_wrt.

Examples

Some basic examples:

>>> from sympy import Derivative, Symbol, Function

>>> f = Function('f')
>>> g = Function('g')
>>> x = Symbol('x')
>>> y = Symbol('y')

>>> Derivative(x**2, x, evaluate=True)

2*x
>>> Derivative(Derivative(f(x,y), x), y)
Derivative(f(x, y), x, y)
>>> Derivative(f(x), x, 3)
Derivative(f(x), (x, 3))
>>> Derivative(f(x, y), y, x, evaluate=True)
Derivative(f(x, y), x, y)

Now some derivatives wrt functions:

>>> Derivative(f(x)**2, f(x), evaluate=True)

2*f(x)
>>> Derivative(f(g(x)), x, evaluate=True)
Derivative(g(x), x)*Subs(Derivative(f(_xi_1), _xi_1),
(_xi_1,), (g(x),))

5.1. SymPy Core 185

SymPy Documentation, Release 1.3

as_finite_difference(points=1, x0=None, wrt=None)

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 co-
efficient, it will be used as the step-size for generating an equidistant
sequence of length order+1 centered around x0. Default: 1 (step-size
1)
x0 : number or Symbol, optional
the value of the independent variable (wrt) at which the derivative is
to be approximated. Default: same as wrt.
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.
See also:
sympy.calculus.finite_diff.apply_finite_diff (page 1505), sympy.
calculus.finite_diff.differentiate_finite (page 1507), sympy.calculus.
finite_diff.finite_diff_weights (page 1508)

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 = [x-h, 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:

186 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> 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 to Derivative instances in compound expres-

sions using replace:

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

doit_numerically(z0)
Evaluate the derivative at z numerically.
When we can represent derivatives at a point, this should be folded into the normal
evalf. For now, we need a special method.

diff

sympy.core.function.diff(f, *symbols, **kwargs)

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.
See also:
Derivative (page 183)
sympy.geometry.util.idiff computes the derivative implicitly

References

http://reference.wolfram.com/legacy/v5_2/Built-inFunctions/AlgebraicComputation/
Calculus/D.html

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)
(continues on next page)

5.1. SymPy Core 187

SymPy Documentation, Release 1.3

(continued from previous page)

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.

FunctionClass

class sympy.core.function.FunctionClass(*args, **kwargs)

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 re-
turned:

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

188 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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
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):
...
(continues on next page)

5.1. SymPy Core 189

SymPy Documentation, Release 1.3

(continued from previous page)

... @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 im-
plemented. 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.
if my_func can take one or two arguments then,

>>> class my_func(Function):

... nargs = (1, 2)
...
>>>

as_base_exp()
Returns the method as the 2-tuple (base, exponent).
fdiff(argindex=1)
Returns the first derivative of the function.
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 sym-
bols:

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

190 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> 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
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()).
A simple example:

>>> from sympy import Subs, Function, sin

>>> from sympy.abc import x, y, z
>>> f = Function('f')
>>> e = Subs(f(x).diff(x), x, y)
>>> e.subs(y, 0)
Subs(Derivative(f(x), x), (x,), (0,))
>>> e.subs(f, sin).doit()
cos(y)

An example with several 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)

expr
The expression on which the substitution operates
point
The values for which the variables are to be substituted

5.1. SymPy Core 191

SymPy Documentation, Release 1.3

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, multino-
mial=True, basic=True, **hints)
Expand an expression using methods given as hints.
Hints evaluated unless explicitly set to False are: basic, log, multinomial, mul,
power_base, and power_exp The following hints are supported but not applied unless
set to True: complex, func, and trig. In addition, the following meta-hints are sup-
ported by some or all of the other hints: frac, numer, denom, modulus, and force. deep
is supported by all hints. Additionally, subclasses of Expr may define their own hints or
meta-hints.
The basic hint is used for any special rewriting of an object that should be done automat-
ically (along with the other hints like mul) when expand is called. This is a catch-all 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 to True (the default), things like arguments of functions are recursively
expanded. Use deep=False to only expand on the top level.
If the force hint is used, assumptions about variables will be ignored in making the
expansion.
See also:
expand_log (page 199), expand_mul (page 198), expand_multinomial (page 200), ex-
pand_complex (page 200), expand_trig (page 199), expand_power_base (page 201), ex-
pand_power_exp (page 200), expand_func (page 199), hyperexpand

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 implemen-
tation, they are applied in alphabetical order, except multinomial comes before

192 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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 multiplica-
tions and prevent log and power_base from expanding them. Also, if mul is applied
before multinomial`, the expression might not be fully distributed. The
solution is to use the various ``expand_hint helper functions or to use
hint=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 before mul. 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 meta-hint can be used to reduce the coefficients of an expression post-
expansion:

>>> 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 equiv-
alent:

5.1. SymPy Core 193

SymPy Documentation, Release 1.3

>>> expand((x + 1)**2)

x**2 + 2*x + 1
>>> ((x + 1)**2).expand()
x**2 + 2*x + 1

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)

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

194 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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 meta-hint 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 automat-
ically:

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

5.1. SymPy Core 195

SymPy Documentation, Release 1.3

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 redefining as_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) and cos(n*x) in terms of sin(x) and cos(x) are not
2 2
unique, due to the identity sin (x) + cos (x) = 1. The current implementation uses the
form obtained from Chebyshev polynomials, but this may change. See this MathWorld
article for more information.

Api

Objects can define their own expand hints by defining _eval_expand_hint(). The func-
tion should take the form:

def _eval_expand_hint(self, **hints):

# Only apply the method to the top-level expression
...

196 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also the example below. Objects should define _eval_expand_hint() methods only
if hint applies to that specific object. The generic _eval_expand_hint() method defined
in Expr will handle the no-op case.
Each hint should be responsible for expanding that hint only. Furthermore, the expansion
should be applied to the top-level expression only. expand() takes care of the recursion
that happens when deep=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 unexpected At-
tributeError``s. Note, again, that you do not need to recursively apply
the hint to args of your object: this is handled automatically by ``ex-
pand(). _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 public expand() function, method, or expand_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, the force=True
hint described above that causes expand(log=True) to ignore assumptions is such a
metahint. The deep meta-hint is handled exclusively by expand() and is not passed to
_eval_expand_hint() methods.
Note that expansion hints should generally be methods that perform some kind of ‘ex-
pansion’. For hints that simply rewrite an expression, use the .rewrite() API.

PoleError

class sympy.core.function.PoleError

count_ops

sympy.core.function.count_ops(expr, visual=False)
Return a representation (integer or expression) of the operations in expr.
If visual is False (default) then the sum of the coefficients of the visual expression will
be returned.
If visual is True 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:

5.1. SymPy Core 197

SymPy Documentation, Release 1.3

>>> (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)
Wrapper around expand that only uses the mul hint. See the expand docstring for more
information.

Examples

198 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

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

sympy.core.function.expand_func(expr, deep=True)
Wrapper around expand that only uses the func hint. See the expand docstring for more
information.

Examples

>>> from sympy import expand_func, gamma

>>> from sympy.abc import x
>>> expand_func(gamma(x + 2))
x*(x + 1)*gamma(x)

expand_trig

sympy.core.function.expand_trig(expr, deep=True)
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))

5.1. SymPy Core 199

SymPy Documentation, Release 1.3

expand_complex

sympy.core.function.expand_complex(expr, deep=True)
Wrapper around expand that only uses the complex hint. See the expand docstring for
more information.
See also:
Expr.as_real_imag

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

expand_multinomial

sympy.core.function.expand_multinomial(expr, deep=True)
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

sympy.core.function.expand_power_exp(expr, deep=True)
Wrapper around expand that only uses the power_exp hint.
See the expand docstring for more information.

Examples

>>> from sympy import expand_power_exp

>>> from sympy.abc import x, y
>>> expand_power_exp(x**(y + 2))
x**2*x**y

200 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

expand_power_base

sympy.core.function.expand_power_base(expr, deep=True, force=False)

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 top-level 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 non-
negative 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 ex-
pand() 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)
(continues on next page)

5.1. SymPy Core 201

SymPy Documentation, Release 1.3

(continued from previous page)

>>> ((2*y)**(1+z)).expand()
2*2**z*y*y**z

nfloat

sympy.core.function.nfloat(expr, n=15, exponent=False)

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

5.1.20 evalf

PrecisionExhausted

class sympy.core.evalf.PrecisionExhausted

sympy.core.evalf.N(x, n=15, **options)

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

202 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.1.21 containers

Tuple

class sympy.core.containers.Tuple
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 on args. 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)

index(value[, start[, stop ]]) → integer – return first index of value.

Raises ValueError if the value is not present.
tuple_count(value)
T.count(value) -> integer – return number of occurrences of value

Dict

class sympy.core.containers.Dict
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:

5.1. SymPy Core 203

SymPy Documentation, Release 1.3

>>> 1 in D
True
>>> D.has('one') # searches keys and values
True
>>> 'one' in D # not in the keys
False
>>> D[1]
one

get(k[, d ]) → D[k] if k in D, else d. d defaults to None.

items() → list of D’s (key, value) pairs, as 2-tuples
keys() → list of D’s keys
values() → list of D’s values

5.1.22 compatibility

iterable

sympy.core.compatibility.iterable(i, exclude=((<class ’str’>,

), <class ’dict’>, <class
’sympy.core.compatibility.NotIterable’>))
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'>
(continues on next page)

204 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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)
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)
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 non-integral value.

5.1. SymPy Core 205

SymPy Documentation, Release 1.3

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

5.1.23 exprtools

gcd_terms

sympy.core.exprtools.gcd_terms(terms, isprimitive=False, clear=True, frac-

tion=True)
Compute the GCD of terms and put them together.
terms can be an expression or a non-Basic 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.
See also:
factor_terms (page 207), sympy.polys.polytools.terms_gcd (page 836)

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)
(continues on next page)

206 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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

factor_terms

sympy.core.exprtools.factor_terms(expr, radical=False, clear=False, frac-

tion=False, sign=True)
Remove common factors from terms in all arguments without changing the underly-
ing structure of the expr. No expansion or simplification (and no processing of non-
commutatives) is performed.
If radical=True then a radical common to all terms will be factored out of any Add sub-
expressions 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.
See also:
gcd_terms (page 206), sympy.polys.polytools.terms_gcd (page 836)

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

5.1. SymPy Core 207

SymPy Documentation, Release 1.3

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)

5.2 Combinatorics Module

5.2.1 Contents

Partitions

class sympy.combinatorics.partitions.Partition
This class represents an abstract partition.
A partition is a set of disjoint sets whose union equals a given set.
See also:
sympy.utilities.iterables.partitions (page 1470), sympy.utilities.iterables.
multiset_partitions (page 1466)

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

RGS
Returns the “restricted growth string” of the partition.
The RGS is returned as a list of indices, L, where L[i] indicates the block in which
element i appears. For example, in a partition of 3 elements (a, b, c) into 2 blocks
([c], [a, b]) the RGS is [1, 1, 0]: “a” is in block 1, “b” is in block 1 and “c” is in block
0.

Examples

>>> from sympy.combinatorics.partitions import Partition

>>> a = Partition([1, 2], [3], [4, 5])
>>> a.members
(1, 2, 3, 4, 5)
>>> a.RGS
(0, 0, 1, 2, 2)
>>> a + 1
{{3}, {4}, {5}, {1, 2}}
(continues on next page)

208 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> _.RGS
(0, 0, 1, 2, 3)

classmethod from_rgs(rgs, elements)

Creates a set partition from a restricted growth string.
The indices given in rgs are assumed to be the index of the element as given in
elements as provided (the elements are not sorted by this routine). Block numbering
starts from 0. If any block was not referenced in rgs an error will be raised.

Examples

>>> from sympy.combinatorics.partitions import Partition

>>> Partition.from_rgs([0, 1, 2, 0, 1], list('abcde'))
{{c}, {a, d}, {b, e}}
>>> Partition.from_rgs([0, 1, 2, 0, 1], list('cbead'))
{{e}, {a, c}, {b, d}}
>>> a = Partition([1, 4], [2], [3, 5])
>>> Partition.from_rgs(a.RGS, a.members)
{{2}, {1, 4}, {3, 5}}

partition
Return partition as a sorted list of lists.

Examples

>>> from sympy.combinatorics.partitions import Partition

>>> Partition([1], [2, 3]).partition
[[1], [2, 3]]

rank
Gets the rank of a partition.

Examples

>>> from sympy.combinatorics.partitions import Partition

>>> a = Partition([1, 2], [3], [4, 5])
>>> a.rank
13

sort_key(order=None)
Return a canonical key that can be used for sorting.
Ordering is based on the size and sorted elements of the partition and ties are broken
with the rank.

Examples

5.2. Combinatorics Module 209

SymPy Documentation, Release 1.3

>>> from sympy.utilities.iterables import default_sort_key

>>> from sympy.combinatorics.partitions import Partition
>>> from sympy.abc import x
>>> a = Partition([1, 2])
>>> b = Partition([3, 4])
>>> c = Partition([1, x])
>>> d = Partition(list(range(4)))
>>> l = [d, b, a + 1, a, c]
>>> l.sort(key=default_sort_key); l
[{{1, 2}}, {{1}, {2}}, {{1, x}}, {{3, 4}}, {{0, 1, 2, 3}}]

class sympy.combinatorics.partitions.IntegerPartition
This class represents an integer partition.
In number theory and combinatorics, a partition of a positive integer, n, also called an
integer partition, is a way of writing n as a list of positive integers that sum to n. Two
partitions that differ only in the order of summands are considered to be the same par-
tition; if order matters then the partitions are referred to as compositions. For example,
4 has five partitions: [4], [3, 1], [2, 2], [2, 1, 1], and [1, 1, 1, 1]; the compositions [1, 2,
1] and [1, 1, 2] are the same as partition [2, 1, 1].
See also:
sympy.utilities.iterables.partitions (page 1470), sympy.utilities.iterables.
multiset_partitions (page 1466)
Reference http://en.wikipedia.org/wiki/Partition_%28number_theory%29
as_dict()
Return the partition as a dictionary whose keys are the partition integers and the
values are the multiplicity of that integer.

Examples

>>> from sympy.combinatorics.partitions import IntegerPartition

>>> IntegerPartition([1]*3 + [2] + [3]*4).as_dict()
{1: 3, 2: 1, 3: 4}

as_ferrers(char=’#’)
Prints the ferrer diagram of a partition.

Examples

>>> from sympy.combinatorics.partitions import IntegerPartition

>>> print(IntegerPartition([1, 1, 5]).as_ferrers())
#####
#
#

conjugate
Computes the conjugate partition of itself.

210 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.partitions import IntegerPartition

>>> a = IntegerPartition([6, 3, 3, 2, 1])
>>> a.conjugate
[5, 4, 3, 1, 1, 1]

next_lex()
Return the next partition of the integer, n, in lexical order, wrapping around to [n]
if the partition is [1, …, 1].

Examples

>>> from sympy.combinatorics.partitions import IntegerPartition

>>> p = IntegerPartition([3, 1])
>>> print(p.next_lex())
[4]
>>> p.partition < p.next_lex().partition
True

prev_lex()
Return the previous partition of the integer, n, in lexical order, wrapping around to
[1, …, 1] if the partition is [n].

Examples

>>> from sympy.combinatorics.partitions import IntegerPartition

>>> p = IntegerPartition([4])
>>> print(p.prev_lex())
[3, 1]
>>> p.partition > p.prev_lex().partition
True

sympy.combinatorics.partitions.random_integer_partition(n, seed=None)
Generates a random integer partition summing to n as a list of reverse-sorted integers.

Examples

>>> from sympy.combinatorics.partitions import random_integer_partition

For the following, a seed is given so a known value can be shown; in practice, the seed
would not be given.

>>> random_integer_partition(100, seed=[1, 1, 12, 1, 2, 1, 85, 1])

[85, 12, 2, 1]
>>> random_integer_partition(10, seed=[1, 2, 3, 1, 5, 1])
[5, 3, 1, 1]
>>> random_integer_partition(1)
[1]

5.2. Combinatorics Module 211

SymPy Documentation, Release 1.3

sympy.combinatorics.partitions.RGS_generalized(m)
Computes the m + 1 generalized unrestricted growth strings and returns them as rows
in matrix.

Examples

>>> from sympy.combinatorics.partitions import RGS_generalized

>>> RGS_generalized(6)
Matrix([
[ 1, 1, 1, 1, 1, 1, 1],
[ 1, 2, 3, 4, 5, 6, 0],
[ 2, 5, 10, 17, 26, 0, 0],
[ 5, 15, 37, 77, 0, 0, 0],
[ 15, 52, 151, 0, 0, 0, 0],
[ 52, 203, 0, 0, 0, 0, 0],
[203, 0, 0, 0, 0, 0, 0]])

sympy.combinatorics.partitions.RGS_enum(m)
RGS_enum computes the total number of restricted growth strings possible for a super-
set of size m.

Examples

>>> from sympy.combinatorics.partitions import RGS_enum

>>> from sympy.combinatorics.partitions import Partition
>>> RGS_enum(4)
15
>>> RGS_enum(5)
52
>>> RGS_enum(6)
203

We can check that the enumeration is correct by actually generating the partitions. Here,
the 15 partitions of 4 items are generated:

>>> a = Partition(list(range(4)))
>>> s = set()
>>> for i in range(20):
... s.add(a)
... a += 1
...
>>> assert len(s) == 15

sympy.combinatorics.partitions.RGS_unrank(rank, m)
Gives the unranked restricted growth string for a given superset size.

Examples

>>> from sympy.combinatorics.partitions import RGS_unrank

>>> RGS_unrank(14, 4)
[0, 1, 2, 3]
(continues on next page)

212 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> RGS_unrank(0, 4)
[0, 0, 0, 0]

sympy.combinatorics.partitions.RGS_rank(rgs)
Computes the rank of a restricted growth string.

Examples

>>> from sympy.combinatorics.partitions import RGS_rank, RGS_unrank

>>> RGS_rank([0, 1, 2, 1, 3])
42
>>> RGS_rank(RGS_unrank(4, 7))
4

Permutations

class sympy.combinatorics.permutations.Permutation
A permutation, alternatively known as an ‘arrangement number’ or ‘ordering’ is an ar-
rangement of the elements of an ordered list into a one-to-one mapping with itself. The
permutation of a given arrangement is given by indicating the positions of the elements
after re-arrangement [R30]. For example, if one started with elements [x, y, a, b] (in that
order) and they were reordered as [x, y, b, a] then the permutation would be [0, 1, 3, 2].
Notice that (in SymPy) the first element is always referred to as 0 and the permutation
uses the indices of the elements in the original ordering, not the elements (a, b, etc…)
themselves.

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = False

See also:
Cycle (page 236)

References

[R29], [R30], [R31], [R32], [R33], [R34], [R35]

Permutations Notation

Permutations are commonly represented in disjoint cycle or array forms.

Array Notation And 2-line Form

In the 2-line form, the elements and their final positions are shown as a matrix with 2
rows:
[0 1 2 … n-1] [p(0) p(1) p(2) … p(n-1)]

5.2. Combinatorics Module 213

SymPy Documentation, Release 1.3

Since the first line is always range(n), where n is the size of p, it is sufficient to represent
the permutation by the second line, referred to as the “array form” of the permutation.
This is entered in brackets as the argument to the Permutation class:

>>> p = Permutation([0, 2, 1]); p

Permutation([0, 2, 1])

Given i in range(p.size), the permutation maps i to i^p

>>> [i^p for i in range(p.size)]

[0, 2, 1]

The composite of two permutations p*q means first apply p, then q, so i^(p*q) = (i^p)^q
which is i^p^q according to Python precedence rules:

>>> q = Permutation([2, 1, 0])

>>> [i^p^q for i in range(3)]
[2, 0, 1]
>>> [i^(p*q) for i in range(3)]
[2, 0, 1]

One can use also the notation p(i) = i^p, but then the composition rule is (p*q)(i) =
q(p(i)), not p(q(i)):

>>> [(p*q)(i) for i in range(p.size)]

[2, 0, 1]
>>> [q(p(i)) for i in range(p.size)]
[2, 0, 1]
>>> [p(q(i)) for i in range(p.size)]
[1, 2, 0]

Disjoint Cycle Notation

In disjoint cycle notation, only the elements that have shifted are indicated. In the above
case, the 2 and 1 switched places. This can be entered in two ways:

>>> Permutation(1, 2) == Permutation([[1, 2]]) == p

True

Only the relative ordering of elements in a cycle matter:

>>> Permutation(1,2,3) == Permutation(2,3,1) == Permutation(3,1,2)

True

The disjoint cycle notation is convenient when representing permutations that have sev-
eral cycles in them:

>>> Permutation(1, 2)(3, 5) == Permutation([[1, 2], [3, 5]])

True

It also provides some economy in entry when computing products of permutations that
are written in disjoint cycle notation:

>>> Permutation(1, 2)(1, 3)(2, 3)

Permutation([0, 3, 2, 1])
(continues on next page)

214 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> _ == Permutation([[1, 2]])*Permutation([[1, 3]])*Permutation([[2, 3]])
True

Caution: when the cycles have common elements between them then the order
in which the permutations are applied matters. The convention is that the per-
mutations are applied from right to left. In the following, the transposition of
elements 2 and 3 is followed by the transposition of elements 1 and 2:

>>> Permutation(1, 2)(2, 3) == Permutation([(1, 2), (2, 3)])

True
>>> Permutation(1, 2)(2, 3).list()
[0, 3, 1, 2]

If the first and second elements had been swapped first, followed by the swap-
ping of the second and third, the result would have been [0, 2, 3, 1]. If, for
some reason, you want to apply the cycles in the order they are entered, you
can simply reverse the order of cycles:

>>> Permutation([(1, 2), (2, 3)][::-1]).list()

[0, 2, 3, 1]

Entering a singleton in a permutation is a way to indicate the size of the permutation.

The size keyword can also be used.
Array-form entry:

>>> Permutation([[1, 2], [9]])

Permutation([0, 2, 1], size=10)
>>> Permutation([[1, 2]], size=10)
Permutation([0, 2, 1], size=10)

Cyclic-form entry:

>>> Permutation(1, 2, size=10)

Permutation([0, 2, 1], size=10)
>>> Permutation(9)(1, 2)
Permutation([0, 2, 1], size=10)

Caution: no singleton containing an element larger than the largest in any previous cycle
can be entered. This is an important difference in how Permutation and Cycle handle the
__call__ syntax. A singleton argument at the start of a Permutation performs instantiation
of the Permutation and is permitted:

>>> Permutation(5)
Permutation([], size=6)

A singleton entered after instantiation is a call to the permutation – a function call – and
if the argument is out of range it will trigger an error. For this reason, it is better to start
the cycle with the singleton:
The following fails because there is is no element 3:

>>> Permutation(1, 2)(3)

Traceback (most recent call last):
(continues on next page)

5.2. Combinatorics Module 215

SymPy Documentation, Release 1.3

(continued from previous page)

...
IndexError: list index out of range

This is ok: only the call to an out of range singleton is prohibited; otherwise the permu-
tation autosizes:

>>> Permutation(3)(1, 2)
Permutation([0, 2, 1, 3])
>>> Permutation(1, 2)(3, 4) == Permutation(3, 4)(1, 2)
True

Equality Testing

The array forms must be the same in order for permutations to be equal:

>>> Permutation([1, 0, 2, 3]) == Permutation([1, 0])

False

Identity Permutation

The identity permutation is a permutation in which no element is out of place. It can be

entered in a variety of ways. All the following create an identity permutation of size 4:

>>> I = Permutation([0, 1, 2, 3])

>>> all(p == I for p in [
... Permutation(3),
... Permutation(range(4)),
... Permutation([], size=4),
... Permutation(size=4)])
True

Watch out for entering the range inside a set of brackets (which is cycle notation):

>>> I == Permutation([range(4)])
False

Permutation Printing

There are a few things to note about how Permutations are printed.
1) If you prefer one form (array or cycle) over another, you can set that with the
print_cyclic flag.

>>> Permutation(1, 2)(4, 5)(3, 4)

Permutation([0, 2, 1, 4, 5, 3])
>>> p = _

>>> Permutation.print_cyclic = True

>>> p
(1 2)(3 4 5)
>>> Permutation.print_cyclic = False

216 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

2) Regardless of the setting, a list of elements in the array for cyclic form can be obtained
and either of those can be copied and supplied as the argument to Permutation:

>>> p.array_form
[0, 2, 1, 4, 5, 3]
>>> p.cyclic_form
[[1, 2], [3, 4, 5]]
>>> Permutation(_) == p
True

3) Printing is economical in that as little as possible is printed while retaining all infor-
mation about the size of the permutation:

>>> Permutation([1, 0, 2, 3])

Permutation([1, 0, 2, 3])
>>> Permutation([1, 0, 2, 3], size=20)
Permutation([1, 0], size=20)
>>> Permutation([1, 0, 2, 4, 3, 5, 6], size=20)
Permutation([1, 0, 2, 4, 3], size=20)

>>> p = Permutation([1, 0, 2, 3])

>>> Permutation.print_cyclic = True
>>> p
(3)(0 1)
>>> Permutation.print_cyclic = False

The 2 was not printed but it is still there as can be seen with the array_form and size
methods:

>>> p.array_form
[1, 0, 2, 3]
>>> p.size
4

Short Introduction To Other Methods

The permutation can act as a bijective function, telling what element is located at a given
position

>>> q = Permutation([5, 2, 3, 4, 1, 0])

>>> q.array_form[1] # the hard way
2
>>> q(1) # the easy way
2
>>> {i: q(i) for i in range(q.size)} # showing the bijection
{0: 5, 1: 2, 2: 3, 3: 4, 4: 1, 5: 0}

The full cyclic form (including singletons) can be obtained:

>>> p.full_cyclic_form
[[0, 1], [2], [3]]

Any permutation can be factored into transpositions of pairs of elements:

5.2. Combinatorics Module 217

SymPy Documentation, Release 1.3

>>> Permutation([[1, 2], [3, 4, 5]]).transpositions()

[(1, 2), (3, 5), (3, 4)]
>>> Permutation.rmul(*[Permutation([ti], size=6) for ti in _]).cyclic_form
[[1, 2], [3, 4, 5]]

The number of permutations on a set of n elements is given by n! and is called the

cardinality.

>>> p.size
4
>>> p.cardinality
24

A given permutation has a rank among all the possible permutations of the same ele-
ments, but what that rank is depends on how the permutations are enumerated. (There
are a number of different methods of doing so.) The lexicographic rank is given by the
rank method and this rank is used to increment a permutation with addition/subtraction:

>>> p.rank()
6
>>> p + 1
Permutation([1, 0, 3, 2])
>>> p.next_lex()
Permutation([1, 0, 3, 2])
>>> _.rank()
7
>>> p.unrank_lex(p.size, rank=7)
Permutation([1, 0, 3, 2])

The product of two permutations p and q is defined as their composition as functions,

(p*q)(i) = q(p(i)) [R34].

>>> p = Permutation([1, 0, 2, 3])

>>> q = Permutation([2, 3, 1, 0])
>>> list(q*p)
[2, 3, 0, 1]
>>> list(p*q)
[3, 2, 1, 0]
>>> [q(p(i)) for i in range(p.size)]
[3, 2, 1, 0]

The permutation can be ‘applied’ to any list-like object, not only Permutations:

>>> p(['zero', 'one', 'four', 'two'])

['one', 'zero', 'four', 'two']
>>> p('zo42')
['o', 'z', '4', '2']

If you have a list of arbitrary elements, the corresponding permutation can be found with
the from_sequence method:

>>> Permutation.from_sequence('SymPy')
Permutation([1, 3, 2, 0, 4])

array_form
Return a copy of the attribute _array_form Examples ========

218 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([[2, 0], [3, 1]])
>>> p.array_form
[2, 3, 0, 1]
>>> Permutation([[2, 0, 3, 1]]).array_form
[3, 2, 0, 1]
>>> Permutation([2, 0, 3, 1]).array_form
[2, 0, 3, 1]
>>> Permutation([[1, 2], [4, 5]]).array_form
[0, 2, 1, 3, 5, 4]

ascents()
Returns the positions of ascents in a permutation, ie, the location where p[i] < p[i+1]
See also:
descents (page 221), inversions (page 225), min (page 229), max (page 229)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([4, 0, 1, 3, 2])
>>> p.ascents()
[1, 2]

atoms()
Returns all the elements of a permutation

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([0, 1, 2, 3, 4, 5]).atoms()
{0, 1, 2, 3, 4, 5}
>>> Permutation([[0, 1], [2, 3], [4, 5]]).atoms()
{0, 1, 2, 3, 4, 5}

cardinality
Returns the number of all possible permutations.
See also:
length (page 228), order (page 230), rank (page 231), size (page 234)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.cardinality
24

commutator(x)
Return the commutator of self and x: ~x*~self*x*self

5.2. Combinatorics Module 219

SymPy Documentation, Release 1.3

If f and g are part of a group, G, then the commutator of f and g is the group identity
iff f and g commute, i.e. fg == gf.

References

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

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([0, 2, 3, 1])
>>> x = Permutation([2, 0, 3, 1])
>>> c = p.commutator(x); c
Permutation([2, 1, 3, 0])
>>> c == ~x*~p*x*p
True

>>> I = Permutation(3)
>>> p = [I + i for i in range(6)]
>>> for i in range(len(p)):
... for j in range(len(p)):
... c = p[i].commutator(p[j])
... if p[i]*p[j] == p[j]*p[i]:
... assert c == I
... else:
... assert c != I
...

commutes_with(other)
Checks if the elements are commuting.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> a = Permutation([1, 4, 3, 0, 2, 5])
>>> b = Permutation([0, 1, 2, 3, 4, 5])
>>> a.commutes_with(b)
True
>>> b = Permutation([2, 3, 5, 4, 1, 0])
>>> a.commutes_with(b)
False

cycle_structure
Return the cycle structure of the permutation as a dictionary indicating the multi-
plicity of each cycle length.

Examples

220 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> Permutation(3).cycle_structure
{1: 4}
>>> Permutation(0, 4, 3)(1, 2)(5, 6).cycle_structure
{2: 2, 3: 1}

cycles
Returns the number of cycles contained in the permutation (including singletons).
See also:
sympy.functions.combinatorial.numbers.stirling (page 495)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([0, 1, 2]).cycles
3
>>> Permutation([0, 1, 2]).full_cyclic_form
[[0], [1], [2]]
>>> Permutation(0, 1)(2, 3).cycles
2

cyclic_form
This is used to convert to the cyclic notation from the canonical notation. Singletons
are omitted.
See also:
array_form (page 218), full_cyclic_form (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([0, 3, 1, 2])
>>> p.cyclic_form
[[1, 3, 2]]
>>> Permutation([1, 0, 2, 4, 3, 5]).cyclic_form
[[0, 1], [3, 4]]

descents()
Returns the positions of descents in a permutation, ie, the location where p[i] >
p[i+1]
See also:
ascents (page 219), inversions (page 225), min (page 229), max (page 229)

Examples

5.2. Combinatorics Module 221

SymPy Documentation, Release 1.3

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([4, 0, 1, 3, 2])
>>> p.descents()
[0, 3]

classmethod from_inversion_vector(inversion)
Calculates the permutation from the inversion vector.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> Permutation.from_inversion_vector([3, 2, 1, 0, 0])
Permutation([3, 2, 1, 0, 4, 5])

classmethod from_sequence(i, key=None)

Return the permutation needed to obtain i from the sorted elements of i. If custom
sorting is desired, a key can be given.

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True

>>> Permutation.from_sequence('SymPy')
(4)(0 1 3)
>>> _(sorted(”SymPy”))
['S', 'y', 'm', 'P', 'y']
>>> Permutation.from_sequence('SymPy', key=lambda x: x.lower())
(4)(0 2)(1 3)

full_cyclic_form
Return permutation in cyclic form including singletons.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation([0, 2, 1]).full_cyclic_form
[[0], [1, 2]]

get_adjacency_distance(other)
Computes the adjacency distance between two permutations.
This metric counts the number of times a pair i,j of jobs is adjacent in both p and p’.
If n_adj is this quantity then the adjacency distance is n - n_adj - 1 [1]
[1] Reeves, Colin R. Landscapes, Operators and Heuristic search, Annals of Opera-
tional Research, 86, pp 473-490. (1999)
See also:
get_precedence_matrix (page 224), get_precedence_distance (page 224),
get_adjacency_matrix (page 223)

222 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 3, 1, 2, 4])
>>> q = Permutation.josephus(4, 5, 2)
>>> p.get_adjacency_distance(q)
3
>>> r = Permutation([0, 2, 1, 4, 3])
>>> p.get_adjacency_distance(r)
4

get_adjacency_matrix()
Computes the adjacency matrix of a permutation.
If job i is adjacent to job j in a permutation p then we set m[i, j] = 1 where m is the
adjacency matrix of p.
See also:
get_precedence_matrix (page 224), get_precedence_distance (page 224),
get_adjacency_distance (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation.josephus(3, 6, 1)
>>> p.get_adjacency_matrix()
Matrix([
[0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 1, 0],
[0, 0, 0, 0, 0, 1],
[0, 1, 0, 0, 0, 0],
[1, 0, 0, 0, 0, 0],
[0, 0, 0, 1, 0, 0]])
>>> q = Permutation([0, 1, 2, 3])
>>> q.get_adjacency_matrix()
Matrix([
[0, 1, 0, 0],
[0, 0, 1, 0],
[0, 0, 0, 1],
[0, 0, 0, 0]])

get_positional_distance(other)
Computes the positional distance between two permutations.
See also:
get_precedence_distance (page 224), get_adjacency_distance (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 3, 1, 2, 4])
>>> q = Permutation.josephus(4, 5, 2)
>>> r = Permutation([3, 1, 4, 0, 2])
(continues on next page)

5.2. Combinatorics Module 223

SymPy Documentation, Release 1.3

(continued from previous page)

>>> p.get_positional_distance(q)
12
>>> p.get_positional_distance(r)
12

get_precedence_distance(other)
Computes the precedence distance between two permutations.
Suppose p and p’ represent n jobs. The precedence metric counts the number of
times a job j is preceded by job i in both p and p’. This metric is commutative.
See also:
get_precedence_matrix (page 224), get_adjacency_matrix (page 223),
get_adjacency_distance (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([2, 0, 4, 3, 1])
>>> q = Permutation([3, 1, 2, 4, 0])
>>> p.get_precedence_distance(q)
7
>>> q.get_precedence_distance(p)
7

get_precedence_matrix()
Gets the precedence matrix. This is used for computing the distance between two
permutations.
See also:
get_precedence_distance (page 224), get_adjacency_matrix (page 223),
get_adjacency_distance (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation.josephus(3, 6, 1)
>>> p
Permutation([2, 5, 3, 1, 4, 0])
>>> p.get_precedence_matrix()
Matrix([
[0, 0, 0, 0, 0, 0],
[1, 0, 0, 0, 1, 0],
[1, 1, 0, 1, 1, 1],
[1, 1, 0, 0, 1, 0],
[1, 0, 0, 0, 0, 0],
[1, 1, 0, 1, 1, 0]])

index()
Returns the index of a permutation.
The index of a permutation is the sum of all subscripts j such that p[j] is greater than
p[j+1].

224 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([3, 0, 2, 1, 4])
>>> p.index()
2

inversion_vector()
Return the inversion vector of the permutation.
The inversion vector consists of elements whose value indicates the number of ele-
ments in the permutation that are lesser than it and lie on its right hand side.
The inversion vector is the same as the Lehmer encoding of a permutation.
See also:
from_inversion_vector (page 222)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([4, 8, 0, 7, 1, 5, 3, 6, 2])
>>> p.inversion_vector()
[4, 7, 0, 5, 0, 2, 1, 1]
>>> p = Permutation([3, 2, 1, 0])
>>> p.inversion_vector()
[3, 2, 1]

The inversion vector increases lexicographically with the rank of the permutation,
the -ith element cycling through 0..i.

>>> p = Permutation(2)
>>> while p:
... print('%s %s %s' % (p, p.inversion_vector(), p.rank()))
... p = p.next_lex()
...
Permutation([0, 1, 2]) [0, 0] 0
Permutation([0, 2, 1]) [0, 1] 1
Permutation([1, 0, 2]) [1, 0] 2
Permutation([1, 2, 0]) [1, 1] 3
Permutation([2, 0, 1]) [2, 0] 4
Permutation([2, 1, 0]) [2, 1] 5

inversions()
Computes the number of inversions of a permutation.
An inversion is where i > j but p[i] < p[j].
For small length of p, it iterates over all i and j values and calculates the number of
inversions. For large length of p, it uses a variation of merge sort to calculate the
number of inversions.
See also:
descents (page 221), ascents (page 219), min (page 229), max (page 229)

5.2. Combinatorics Module 225

SymPy Documentation, Release 1.3

References

[1] http://www.cp.eng.chula.ac.th/~piak/teaching/algo/algo2008/count-inv.htm

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3, 4, 5])
>>> p.inversions()
0
>>> Permutation([3, 2, 1, 0]).inversions()
6

is_Empty
Checks to see if the permutation is a set with zero elements
See also:
is_Singleton (page 226)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([]).is_Empty
True
>>> Permutation([0]).is_Empty
False

is_Identity
Returns True if the Permutation is an identity permutation.
See also:
order (page 230)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([])
>>> p.is_Identity
True
>>> p = Permutation([[0], [1], [2]])
>>> p.is_Identity
True
>>> p = Permutation([0, 1, 2])
>>> p.is_Identity
True
>>> p = Permutation([0, 2, 1])
>>> p.is_Identity
False

is_Singleton
Checks to see if the permutation contains only one number and is thus the only
possible permutation of this set of numbers

226 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
is_Empty (page 226)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([0]).is_Singleton
True
>>> Permutation([0, 1]).is_Singleton
False

is_even
Checks if a permutation is even.
See also:
is_odd (page 227)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.is_even
True
>>> p = Permutation([3, 2, 1, 0])
>>> p.is_even
True

is_odd
Checks if a permutation is odd.
See also:
is_even (page 227)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.is_odd
False
>>> p = Permutation([3, 2, 0, 1])
>>> p.is_odd
True

classmethod josephus(m, n, s=1)

Return as a permutation the shuffling of range(n) using the Josephus scheme in
which every m-th item is selected until all have been chosen. The returned permu-
tation has elements listed by the order in which they were selected.
The parameter s stops the selection process when there are s items remaining and
these are selected by continuing the selection, counting by 1 rather than by m.
Consider selecting every 3rd item from 6 until only 2 remain:

5.2. Combinatorics Module 227

SymPy Documentation, Release 1.3

choices chosen
======== ======
012345
01 345 2
01 34 25
01 4 253
0 4 2531
0 25314
253140

References

1. http://en.wikipedia.org/wiki/Flavius_Josephus
2. http://en.wikipedia.org/wiki/Josephus_problem
3. http://www.wou.edu/~burtonl/josephus.html

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.josephus(3, 6, 2).array_form
[2, 5, 3, 1, 4, 0]

length()
Returns the number of integers moved by a permutation.
See also:
min (page 229), max (page 229), support (page 234), cardinality (page 219), order
(page 230), rank (page 231), size (page 234)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([0, 3, 2, 1]).length()
2
>>> Permutation([[0, 1], [2, 3]]).length()
4

list(size=None)
Return the permutation as an explicit list, possibly trimming unmoved elements if
size is less than the maximum element in the permutation; if this is desired, setting
size=-1 will guarantee such trimming.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation(2, 3)(4, 5)
>>> p.list()
(continues on next page)

228 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[0, 1, 3, 2, 5, 4]
>>> p.list(10)
[0, 1, 3, 2, 5, 4, 6, 7, 8, 9]

Passing a length too small will trim trailing, unchanged elements in the permutation:

>>> Permutation(2, 4)(1, 2, 4).list(-1)

[0, 2, 1]
>>> Permutation(3).list(-1)
[]

max()
The maximum element moved by the permutation.
See also:
min (page 229), descents (page 221), ascents (page 219), inversions (page 225)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([1, 0, 2, 3, 4])
>>> p.max()
1

min()
The minimum element moved by the permutation.
See also:
max (page 229), descents (page 221), ascents (page 219), inversions (page 225)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 4, 3, 2])
>>> p.min()
2

mul_inv(other)
other*~self, self and other have _array_form
next_lex()
Returns the next permutation in lexicographical order. If self is the last permutation
in lexicographical order it returns None. See [4] section 2.4.
See also:
rank (page 231), unrank_lex (page 235)

Examples

5.2. Combinatorics Module 229

SymPy Documentation, Release 1.3

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([2, 3, 1, 0])
>>> p = Permutation([2, 3, 1, 0]); p.rank()
17
>>> p = p.next_lex(); p.rank()
18

next_nonlex()
Returns the next permutation in nonlex order [3]. If self is the last permutation in
this order it returns None.
See also:
rank_nonlex (page 232), unrank_nonlex (page 235)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([2, 0, 3, 1]); p.rank_nonlex()
5
>>> p = p.next_nonlex(); p
Permutation([3, 0, 1, 2])
>>> p.rank_nonlex()
6

next_trotterjohnson()
Returns the next permutation in Trotter-Johnson order. If self is the last permutation
it returns None. See [4] section 2.4. If it is desired to generate all such permutations,
they can be generated in order more quickly with the generate_bell function.
See also:
rank_trotterjohnson (page 232), unrank_trotterjohnson (page 235), sympy.
utilities.iterables.generate_bell (page 1460)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([3, 0, 2, 1])
>>> p.rank_trotterjohnson()
4
>>> p = p.next_trotterjohnson(); p
Permutation([0, 3, 2, 1])
>>> p.rank_trotterjohnson()
5

order()
Computes the order of a permutation.
When the permutation is raised to the power of its order it equals the identity per-
mutation.
See also:

230 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

identity, cardinality (page 219), length (page 228), rank (page 231), size
(page 234)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> p = Permutation([3, 1, 5, 2, 4, 0])
>>> p.order()
4
>>> (p**(p.order()))
Permutation([], size=6)

parity()
Computes the parity of a permutation.
The parity of a permutation reflects the parity of the number of inversions in the
permutation, i.e., the number of pairs of x and y such that x > y but p[x] < p[y].
See also:
_af_parity

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.parity()
0
>>> p = Permutation([3, 2, 0, 1])
>>> p.parity()
1

classmethod random(n)
Generates a random permutation of length n.
Uses the underlying Python pseudo-random number generator.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.random(2) in (Permutation([1, 0]), Permutation([0, 1]))
True

rank()
Returns the lexicographic rank of the permutation.
See also:
next_lex (page 229), unrank_lex (page 235), cardinality (page 219), length
(page 228), order (page 230), size (page 234)

5.2. Combinatorics Module 231

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.rank()
0
>>> p = Permutation([3, 2, 1, 0])
>>> p.rank()
23

rank_nonlex(inv_perm=None)
This is a linear time ranking algorithm that does not enforce lexicographic order [3].
See also:
next_nonlex (page 230), unrank_nonlex (page 235)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.rank_nonlex()
23

rank_trotterjohnson()
Returns the Trotter Johnson rank, which we get from the minimal change algorithm.
See [4] section 2.4.
See also:
unrank_trotterjohnson (page 235), next_trotterjohnson (page 230)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2, 3])
>>> p.rank_trotterjohnson()
0
>>> p = Permutation([0, 2, 1, 3])
>>> p.rank_trotterjohnson()
7

static rmul(*args)
Return product of Permutations [a, b, c, …] as the Permutation whose ith value is
a(b(c(i))).
a, b, c, … can be Permutation objects or tuples.

Notes

All items in the sequence will be parsed by Permutation as necessary as long as the
first item is a Permutation:

232 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Permutation.rmul(a, [0, 2, 1]) == Permutation.rmul(a, b)

True

The reverse order of arguments will raise a TypeError.

Examples

>>> from sympy.combinatorics.permutations import _af_rmul, Permutation

>>> Permutation.print_cyclic = False

>>> a, b = [1, 0, 2], [0, 2, 1]

>>> a = Permutation(a); b = Permutation(b)
>>> list(Permutation.rmul(a, b))
[1, 2, 0]
>>> [a(b(i)) for i in range(3)]
[1, 2, 0]

This handles the operands in reverse order compared to the * operator:

>>> a = Permutation(a); b = Permutation(b)

>>> list(a*b)
[2, 0, 1]
>>> [b(a(i)) for i in range(3)]
[2, 0, 1]

classmethod rmul_with_af(*args)
same as rmul, but the elements of args are Permutation objects which have _ar-
ray_form
runs()
Returns the runs of a permutation.
An ascending sequence in a permutation is called a run [5].

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([2, 5, 7, 3, 6, 0, 1, 4, 8])
>>> p.runs()
[[2, 5, 7], [3, 6], [0, 1, 4, 8]]
>>> q = Permutation([1,3,2,0])
>>> q.runs()
[[1, 3], [2], [0]]

signature()
Gives the signature of the permutation needed to place the elements of the permu-
tation in canonical order.
The signature is calculated as (-1)^<number of inversions>
See also:
inversions (page 225)

5.2. Combinatorics Module 233

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([0, 1, 2])
>>> p.inversions()
0
>>> p.signature()
1
>>> q = Permutation([0,2,1])
>>> q.inversions()
1
>>> q.signature()
-1

size
Returns the number of elements in the permutation.
See also:
cardinality (page 219), length (page 228), order (page 230), rank (page 231)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation([[3, 2], [0, 1]]).size
4

support()
Return the elements in permutation, P, for which P[i] != i.

Examples

>>> from sympy.combinatorics import Permutation

>>> p = Permutation([[3, 2], [0, 1], [4]])
>>> p.array_form
[1, 0, 3, 2, 4]
>>> p.support()
[0, 1, 2, 3]

transpositions()
Return the permutation decomposed into a list of transpositions.
It is always possible to express a permutation as the product of transpositions, see
[1]

References

1. http://en.wikipedia.org/wiki/Transposition_%28mathematics%29#Properties

234 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> p = Permutation([[1, 2, 3], [0, 4, 5, 6, 7]])
>>> t = p.transpositions()
>>> t
[(0, 7), (0, 6), (0, 5), (0, 4), (1, 3), (1, 2)]
>>> print(''.join(str(c) for c in t))
(0, 7)(0, 6)(0, 5)(0, 4)(1, 3)(1, 2)
>>> Permutation.rmul(*[Permutation([ti], size=p.size) for ti in t]) == p
True

classmethod unrank_lex(size, rank)

Lexicographic permutation unranking.
See also:
rank (page 231), next_lex (page 229)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> a = Permutation.unrank_lex(5, 10)
>>> a.rank()
10
>>> a
Permutation([0, 2, 4, 1, 3])

classmethod unrank_nonlex(n, r)
This is a linear time unranking algorithm that does not respect lexicographic order
[3].
See also:
next_nonlex (page 230), rank_nonlex (page 232)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = False
>>> Permutation.unrank_nonlex(4, 5)
Permutation([2, 0, 3, 1])
>>> Permutation.unrank_nonlex(4, -1)
Permutation([0, 1, 2, 3])

classmethod unrank_trotterjohnson(size, rank)

Trotter Johnson permutation unranking. See [4] section 2.4.
See also:
rank_trotterjohnson (page 232), next_trotterjohnson (page 230)

5.2. Combinatorics Module 235

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.unrank_trotterjohnson(5, 10)
Permutation([0, 3, 1, 2, 4])

class sympy.combinatorics.permutations.Cycle(*args)
Wrapper around dict which provides the functionality of a disjoint cycle.
A cycle shows the rule to use to move subsets of elements to obtain a permutation. The
Cycle class is more flexible than Permutation in that 1) all elements need not be present in
order to investigate how multiple cycles act in sequence and 2) it can contain singletons:

>>> from sympy.combinatorics.permutations import Perm, Cycle

A Cycle will automatically parse a cycle given as a tuple on the rhs:

>>> Cycle(1, 2)(2, 3)

(1 3 2)

The identity cycle, Cycle(), can be used to start a product:

>>> Cycle()(1, 2)(2, 3)

(1 3 2)

The array form of a Cycle can be obtained by calling the list method (or passing it to the
list function) and all elements from 0 will be shown:

>>> a = Cycle(1, 2)
>>> a.list()
[0, 2, 1]
>>> list(a)
[0, 2, 1]

If a larger (or smaller) range is desired use the list method and provide the desired size
– but the Cycle cannot be truncated to a size smaller than the largest element that is out
of place:

>>> b = Cycle(2, 4)(1, 2)(3, 1, 4)(1, 3)

>>> b.list()
[0, 2, 1, 3, 4]
>>> b.list(b.size + 1)
[0, 2, 1, 3, 4, 5]
>>> b.list(-1)
[0, 2, 1]

Singletons are not shown when printing with one exception: the largest element is al-
ways shown – as a singleton if necessary:

>>> Cycle(1, 4, 10)(4, 5)

(1 5 4 10)
>>> Cycle(1, 2)(4)(5)(10)
(1 2)(10)

The array form can be used to instantiate a Permutation so other properties of the per-
mutation can be investigated:

236 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Perm(Cycle(1, 2)(3, 4).list()).transpositions()

[(1, 2), (3, 4)]

See also:
Permutation (page 213)

Notes

The underlying structure of the Cycle is a dictionary and although the __iter__ method
has been redefined to give the array form of the cycle, the underlying dictionary items
are still available with the such methods as items():
>>> list(Cycle(1, 2).items())
[(1, 2), (2, 1)]

list(size=None)
Return the cycles as an explicit list starting from 0 up to the greater of the largest
value in the cycles and size.
Truncation of trailing unmoved items will occur when size is less than the maximum
element in the cycle; if this is desired, setting size=-1 will guarantee such trimming.

Examples

>>> from sympy.combinatorics.permutations import Cycle

>>> from sympy.combinatorics.permutations import Permutation
>>> Permutation.print_cyclic = False
>>> p = Cycle(2, 3)(4, 5)
>>> p.list()
[0, 1, 3, 2, 5, 4]
>>> p.list(10)
[0, 1, 3, 2, 5, 4, 6, 7, 8, 9]

Passing a length too small will trim trailing, unchanged elements in the permutation:
>>> Cycle(2, 4)(1, 2, 4).list(-1)
[0, 2, 1]

Generators

generators.symmetric()
Generates the symmetric group of order n, Sn.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.generators import symmetric
>>> list(symmetric(3))
[(2), (1 2), (2)(0 1), (0 1 2), (0 2 1), (0 2)]

5.2. Combinatorics Module 237

SymPy Documentation, Release 1.3

generators.cyclic()
Generates the cyclic group of order n, Cn.
See also:
dihedral (page 238)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.generators import cyclic
>>> list(cyclic(5))
[(4), (0 1 2 3 4), (0 2 4 1 3),
(0 3 1 4 2), (0 4 3 2 1)]

generators.alternating()
Generates the alternating group of order n, An.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.generators import alternating
>>> list(alternating(3))
[(2), (0 1 2), (0 2 1)]

generators.dihedral()
Generates the dihedral group of order 2n, Dn.
The result is given as a subgroup of Sn, except for the special cases n=1 (the group S2)
and n=2 (the Klein 4-group) where that’s not possible and embeddings in S2 and S4
respectively are given.
See also:
cyclic (page 237)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.generators import dihedral
>>> list(dihedral(3))
[(2), (0 2), (0 1 2), (1 2), (0 2 1), (2)(0 1)]

Permutation Groups

class sympy.combinatorics.perm_groups.PermutationGroup
The class defining a Permutation group.

238 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

PermutationGroup([p1, p2, …, pn]) returns the permutation group generated by the list
of permutations. This group can be supplied to Polyhedron if one desires to decorate the
elements to which the indices of the permutation refer.
See also:
sympy.combinatorics.polyhedron.Polyhedron (page 267), sympy.combinatorics.
permutations.Permutation (page 213)

References

[1] Holt, D., Eick, B., O’Brien, E. “Handbook of Computational Group Theory”
[2] Seress, A. “Permutation Group Algorithms”
[3] http://en.wikipedia.org/wiki/Schreier_vector
[4] http://en.wikipedia.org/wiki/Nielsen_transformation #Prod-
uct_replacement_algorithm
[5] Frank Celler, Charles R.Leedham-Green, Scott H.Murray, Alice C.Niemeyer, and
E.A.O’Brien. “Generating Random Elements of a Finite Group”
[6] http://en.wikipedia.org/wiki/Block_%28permutation_group_theory%29
[7] http://www.algorithmist.com/index.php/Union_Find
[8] http://en.wikipedia.org/wiki/Multiply_transitive_group#Multiply_transitive_groups
[9] http://en.wikipedia.org/wiki/Center_%28group_theory%29
[10] http://en.wikipedia.org/wiki/Centralizer_and_normalizer
[11] http://groupprops.subwiki.org/wiki/Derived_subgroup
[12] http://en.wikipedia.org/wiki/Nilpotent_group
[13] http://www.math.colostate.edu/~hulpke/CGT/cgtnotes.pdf

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.permutations import Cycle
>>> from sympy.combinatorics.polyhedron import Polyhedron
>>> from sympy.combinatorics.perm_groups import PermutationGroup

The permutations corresponding to motion of the front, right and bottom face of a 2x2
Rubik’s cube are defined:

>>> F = Permutation(2, 19, 21, 8)(3, 17, 20, 10)(4, 6, 7, 5)

>>> R = Permutation(1, 5, 21, 14)(3, 7, 23, 12)(8, 10, 11, 9)
>>> D = Permutation(6, 18, 14, 10)(7, 19, 15, 11)(20, 22, 23, 21)

These are passed as permutations to PermutationGroup:

>>> G = PermutationGroup(F, R, D)
>>> G.order()
3674160

5.2. Combinatorics Module 239

SymPy Documentation, Release 1.3

The group can be supplied to a Polyhedron in order to track the objects being moved.
An example involving the 2x2 Rubik’s cube is given there, but here is a simple demon-
stration:

>>> a = Permutation(2, 1)
>>> b = Permutation(1, 0)
>>> G = PermutationGroup(a, b)
>>> P = Polyhedron(list('ABC'), pgroup=G)
>>> P.corners
(A, B, C)
>>> P.rotate(0) # apply permutation 0
>>> P.corners
(A, C, B)
>>> P.reset()
>>> P.corners
(A, B, C)

Or one can make a permutation as a product of selected permutations and apply them
to an iterable directly:

>>> P10 = G.make_perm([0, 1])

>>> P10('ABC')
['C', 'A', 'B']

base
Return a base from the Schreier-Sims algorithm.
For a permutation group G, a base is a sequence of points B = (b1 , b2 , ..., bk ) such that
no element of G apart from the identity fixes all the points in B. The concepts of a
base and strong generating set and their applications are discussed in depth in [1],
pp. 87-89 and [2], pp. 55-57.
An alternative way to think of B is that it gives the indices of the stabilizer cosets
that contain more than the identity permutation.
See also:
strong_gens (page 264), basic_transversals (page 242), basic_orbits
(page 241), basic_stabilizers (page 242)

Examples

>>> from sympy.combinatorics import Permutation, PermutationGroup

>>> G = PermutationGroup([Permutation(0, 1, 3)(2, 4)])
>>> G.base
[0, 2]

baseswap(base, strong_gens, pos, randomized=False, transversals=None, ba-

sic_orbits=None, strong_gens_distr=None)
Swap two consecutive base points in base and strong generating set.
If a base for a group G is given by (b1 , b2 , ..., bk ), this function returns a base
(b1 , b2 , ..., bi+1 , bi , ..., bk ), where i is given by pos, and a strong generating set relative
to that base. The original base and strong generating set are not modified.
The randomized version (default) is of Las Vegas type.
Parameters base, strong_gens

240 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The base and strong generating set.

pos
The position at which swapping is performed.
randomized
A switch between randomized and deterministic version.
transversals
The transversals for the basic orbits, if known.
basic_orbits
The basic orbits, if known.
strong_gens_distr
The strong generators distributed by basic stabilizers, if known.
Returns (base, strong_gens)
base is the new base, and strong_gens is a generating set relative to
it.
See also:
schreier_sims (page 261)

Notes

The deterministic version of the algorithm is discussed in [1], pp. 102-103; the
randomized version is discussed in [1], p.103, and [2], p.98. It is of Las Vegas type.
Notice that [1] contains a mistake in the pseudocode and discussion of BASESWAP:
⟨T ⟩ ⟨T ⟩
on line 3 of the pseudocode, |βi+1 | should be replaced by |βi |, and the same for the
discussion of the algorithm.

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> S = SymmetricGroup(4)
>>> S.schreier_sims()
>>> S.base
[0, 1, 2]
>>> base, gens = S.baseswap(S.base, S.strong_gens, 1, randomized=False)
>>> base, gens
([0, 2, 1],
[(0 1 2 3), (3)(0 1), (1 3 2),
(2 3), (1 3)])

check that base, gens is a BSGS

>>> S1 = PermutationGroup(gens)
>>> _verify_bsgs(S1, base, gens)
True

5.2. Combinatorics Module 241

SymPy Documentation, Release 1.3

basic_orbits
Return the basic orbits relative to a base and strong generating set.
If (b1 , b2 , ..., bk ) is a base for a group G, and G(i) = Gb1 ,b2 ,...,bi−1 is the i-th basic stabilizer
(so that G(1) = G), the i-th basic orbit relative to this base is the orbit of bi under G(i) .
See [1], pp. 87-89 for more information.
See also:
base (page 240), strong_gens (page 264), basic_transversals (page 242), ba-
sic_stabilizers (page 242)

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> S = SymmetricGroup(4)
>>> S.basic_orbits
[[0, 1, 2, 3], [1, 2, 3], [2, 3]]

basic_stabilizers
Return a chain of stabilizers relative to a base and strong generating set.
The i-th basic stabilizer G(i) relative to a base (b1 , b2 , ..., bk ) is Gb1 ,b2 ,...,bi−1 . For more
information, see [1], pp. 87-89.
See also:
base (page 240), strong_gens (page 264), basic_orbits (page 241), ba-
sic_transversals (page 242)

Examples

>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> A = AlternatingGroup(4)
>>> A.schreier_sims()
>>> A.base
[0, 1]
>>> for g in A.basic_stabilizers:
... print(g)
...
PermutationGroup([
(3)(0 1 2),
(1 2 3)])
PermutationGroup([
(1 2 3)])

basic_transversals
Return basic transversals relative to a base and strong generating set.
The basic transversals are transversals of the basic orbits. They are provided as a
list of dictionaries, each dictionary having keys - the elements of one of the basic
orbits, and values - the corresponding transversal elements. See [1], pp. 87-89 for
more information.
See also:

242 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

strong_gens (page 264), base (page 240), basic_orbits (page 241), ba-
sic_stabilizers (page 242)

Examples

>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> A = AlternatingGroup(4)
>>> A.basic_transversals
[{0: (3), 1: (3)(0 1 2), 2: (3)(0 2 1), 3: (0 3 1)}, {1: (3), 2: (1 2 3), 3:␣
,→(1 3 2)}]

center()
Return the center of a permutation group.
The center for a group G is defined as Z(G) = {z ∈ G|∀g ∈ G, zg = gz}, the set of
elements of G that commute with all elements of G. It is equal to the centralizer of
G inside G, and is naturally a subgroup of G ([9]).
See also:
centralizer (page 243)

Notes

This is a naive implementation that is a straightforward application of .

centralizer()

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> D = DihedralGroup(4)
>>> G = D.center()
>>> G.order()
2

centralizer(other)
Return the centralizer of a group/set/element.
The centralizer of a set of permutations S inside a group G is the set of elements of
G that commute with all elements of S:

`C_G(S) = \{ g \in G | gs = sg \forall s \in S\}` ([10])

Usually, S is a subset of G, but if G is a proper subgroup of the full symmetric group,

we allow for S to have elements outside G.
It is naturally a subgroup of G; the centralizer of a permutation group is equal to the
centralizer of any set of generators for that group, since any element commuting
with the generators commutes with any product of the generators.
Parameters other
a permutation group/list of permutations/single permutation

5.2. Combinatorics Module 243

SymPy Documentation, Release 1.3

See also:
subgroup_search (page 265)

Notes

The implementation is an application of .subgroup_search() with tests using a spe-

cific base for the group G.

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... CyclicGroup)
>>> S = SymmetricGroup(6)
>>> C = CyclicGroup(6)
>>> H = S.centralizer(C)
>>> H.is_subgroup(C)
True

commutator(G, H)
Return the commutator of two subgroups.
For a permutation group K and subgroups G, H, the commutator of G and H is defined
as the group generated by all the commutators [g, h] = hgh−1 g −1 for g in G and h in H.
It is naturally a subgroup of K ([1], p.27).
See also:
derived_subgroup (page 248)

Notes

The commutator of two subgroups H, G is equal to the normal closure of the com-
mutators of all the generators, i.e. hgh−1 g −1 for h a generator of H and g a generator
of G ([1], p.28)

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... AlternatingGroup)
>>> S = SymmetricGroup(5)
>>> A = AlternatingGroup(5)
>>> G = S.commutator(S, A)
>>> G.is_subgroup(A)
True

contains(g, strict=True)
Test if permutation g belong to self, G.
If g is an element of G it can be written as a product of factors drawn from the cosets
of G’s stabilizers. To see if g is one of the actual generators defining the group use
G.has(g).

244 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If strict is not True, g will be resized, if necessary, to match the size of permutations
in self.
See also:
coset_factor (page 245), has, in

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> a = Permutation(1, 2)
>>> b = Permutation(2, 3, 1)
>>> G = PermutationGroup(a, b, degree=5)
>>> G.contains(G[0]) # trivial check
True
>>> elem = Permutation([[2, 3]], size=5)
>>> G.contains(elem)
True
>>> G.contains(Permutation(4)(0, 1, 2, 3))
False

If strict is False, a permutation will be resized, if necessary:

>>> H = PermutationGroup(Permutation(5))
>>> H.contains(Permutation(3))
False
>>> H.contains(Permutation(3), strict=False)
True

To test if a given permutation is present in the group:

>>> elem in G.generators

False
>>> G.has(elem)
False

coset_factor(g, factor_index=False)
Return G’s (self’s) coset factorization of g
If g is an element of G then it can be written as the product of permutations drawn
from the Schreier-Sims coset decomposition,
The permutations returned in f are those for which the product gives g: g = f[n]*.
..f[1]*f[0] where n = len(B) and B = G.base. f[i] is one of the permutations in
self._basic_orbits[i].
If factor_index==True, returns a tuple [b[0],..,b[n]], where b[i] belongs to
self._basic_orbits[i]

Examples

5.2. Combinatorics Module 245

SymPy Documentation, Release 1.3

>>> from sympy.combinatorics import Permutation, PermutationGroup

>>> Permutation.print_cyclic = True
>>> a = Permutation(0, 1, 3, 7, 6, 4)(2, 5)
>>> b = Permutation(0, 1, 3, 2)(4, 5, 7, 6)
>>> G = PermutationGroup([a, b])

Define g:
>>> g = Permutation(7)(1, 2, 4)(3, 6, 5)

Confirm that it is an element of G:

>>> G.contains(g)
True

Thus, it can be written as a product of factors (up to 3) drawn from u. See below
that a factor from u1 and u2 and the Identity permutation have been used:
>>> f = G.coset_factor(g)
>>> f[2]*f[1]*f[0] == g
True
>>> f1 = G.coset_factor(g, True); f1
[0, 4, 4]
>>> tr = G.basic_transversals
>>> f[0] == tr[0][f1[0]]
True

If g is not an element of G then [] is returned:

>>> c = Permutation(5, 6, 7)
>>> G.coset_factor(c)
[]

see util._strip
coset_rank(g)
rank using Schreier-Sims representation
The coset rank of g is the ordering number in which it appears in the lexicographic
listing according to the coset decomposition
The ordering is the same as in G.generate(method=’coset’). If g does not belong to
the group it returns None.
See also:
coset_factor (page 245)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation(0, 1, 3, 7, 6, 4)(2, 5)
>>> b = Permutation(0, 1, 3, 2)(4, 5, 7, 6)
>>> G = PermutationGroup([a, b])
>>> c = Permutation(7)(2, 4)(3, 5)
(continues on next page)

246 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> G.coset_rank(c)
16
>>> G.coset_unrank(16)
(7)(2 4)(3 5)

coset_table(H)
Return the standardised (right) coset table of self in H as a list of lists.
coset_transversal(H)
Return a transversal of the right cosets of self by its subgroup H using the second
method described in [1], Subsection 4.6.7
coset_unrank(rank, af=False)
unrank using Schreier-Sims representation
coset_unrank is the inverse operation of coset_rank if 0 <= rank < order; otherwise
it returns None.
degree
Returns the size of the permutations in the group.
The number of permutations comprising the group is given by len(group); the num-
ber of permutations that can be generated by the group is given by group.order().
See also:
order (page 259)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([1, 0, 2])
>>> G = PermutationGroup([a])
>>> G.degree
3
>>> len(G)
1
>>> G.order()
2
>>> list(G.generate())
[(2), (2)(0 1)]

derived_series()
Return the derived series for the group.
The derived series for a group G is defined as G = G0 > G1 > G2 > . . . where Gi =
[Gi−1 , Gi−1 ], i.e. Gi is the derived subgroup of Gi−1 , for i ∈ N. When we have Gk = Gk−1
for some k ∈ N, the series terminates.
Returns A list of permutation groups containing the members of the derived
series in the order G = G0 , G1 , G2 , . . ..
See also:
derived_subgroup (page 248)

5.2. Combinatorics Module 247

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... AlternatingGroup, DihedralGroup)
>>> A = AlternatingGroup(5)
>>> len(A.derived_series())
1
>>> S = SymmetricGroup(4)
>>> len(S.derived_series())
4
>>> S.derived_series()[1].is_subgroup(AlternatingGroup(4))
True
>>> S.derived_series()[2].is_subgroup(DihedralGroup(2))
True

derived_subgroup()
Compute the derived subgroup.
The derived subgroup, or commutator subgroup is the subgroup generated by all
commutators [g, h] = hgh−1 g −1 for g, h ∈ G ; it is equal to the normal closure of the set
of commutators of the generators ([1], p.28, [11]).
See also:
derived_series (page 247)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([1, 0, 2, 4, 3])
>>> b = Permutation([0, 1, 3, 2, 4])
>>> G = PermutationGroup([a, b])
>>> C = G.derived_subgroup()
>>> list(C.generate(af=True))
[[0, 1, 2, 3, 4], [0, 1, 3, 4, 2], [0, 1, 4, 2, 3]]

elements
Returns all the elements of the permutation group as a set

Examples

>>> from sympy.combinatorics import Permutation, PermutationGroup

>>> p = PermutationGroup(Permutation(1, 3), Permutation(1, 2))
>>> p.elements
{(3), (2 3), (3)(1 2), (1 2 3), (1 3 2), (1 3)}

generate(method=’coset’, af=False)
Return iterator to generate the elements of the group
Iteration is done with one of these methods:

method='coset' using the Schreier-Sims coset representation

method='dimino' using the Dimino method

248 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If af = True it yields the array form of the permutations

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics import PermutationGroup
>>> from sympy.combinatorics.polyhedron import tetrahedron

The permutation group given in the tetrahedron object is also true groups:
>>> G = tetrahedron.pgroup
>>> G.is_group
True

Also the group generated by the permutations in the tetrahedron pgroup – even the
first two – is a proper group:
>>> H = PermutationGroup(G[0], G[1])
>>> J = PermutationGroup(list(H.generate())); J
PermutationGroup([
(0 1)(2 3),
(1 2 3),
(1 3 2),
(0 3 1),
(0 2 3),
(0 3)(1 2),
(0 1 3),
(3)(0 2 1),
(0 3 2),
(3)(0 1 2),
(0 2)(1 3)])
>>> _.is_group
True

generate_dimino(af=False)
Yield group elements using Dimino’s algorithm
If af == True it yields the array form of the permutations

References

[1] The Implementation of Various Algorithms for Permutation Groups in the Com-
puter Algebra System: AXIOM, N.J. Doye, M.Sc. Thesis

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1, 3])
>>> b = Permutation([0, 2, 3, 1])
>>> g = PermutationGroup([a, b])
(continues on next page)

5.2. Combinatorics Module 249

SymPy Documentation, Release 1.3

(continued from previous page)

>>> list(g.generate_dimino(af=True))
[[0, 1, 2, 3], [0, 2, 1, 3], [0, 2, 3, 1],
[0, 1, 3, 2], [0, 3, 2, 1], [0, 3, 1, 2]]

generate_schreier_sims(af=False)
Yield group elements using the Schreier-Sims representation in coset_rank order
If af = True it yields the array form of the permutations

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1, 3])
>>> b = Permutation([0, 2, 3, 1])
>>> g = PermutationGroup([a, b])
>>> list(g.generate_schreier_sims(af=True))
[[0, 1, 2, 3], [0, 2, 1, 3], [0, 3, 2, 1],
[0, 1, 3, 2], [0, 2, 3, 1], [0, 3, 1, 2]]

generator_product(g, original=False)
Return a list of strong generators [s1, ..., sn] s.t g = sn ∗ ... ∗ s1. If original = T rue, make
the list contain only the original group generators
generators
Returns the generators of the group.

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1])
>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G.generators
[(1 2), (2)(0 1)]

identity
Return the identity element of the permutation group.
is_abelian
Test if the group is Abelian.

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1])
(continues on next page)

250 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G.is_abelian
False
>>> a = Permutation([0, 2, 1])
>>> G = PermutationGroup([a])
>>> G.is_abelian
True

is_alt_sym(eps=0.05, _random_prec=None)
Monte Carlo test for the symmetric/alternating group for degrees >= 8.
More specifically, it is one-sided Monte Carlo with the answer True (i.e., G is sym-
metric/alternating) guaranteed to be correct, and the answer False being incorrect
with probability eps.
For degree < 8, the order of the group is checked so the test is deterministic.
See also:
_check_cycles_alt_sym

Notes

The algorithm itself uses some nontrivial results from group theory and number
theory: 1) If a transitive group G of degree n contains an element with a cycle of
length n/2 < p < n-2 for p a prime, G is the symmetric or alternating group ([1],
pp. 81-82) 2) The proportion of elements in the symmetric/alternating group having
the property described in 1) is approximately log(2)/ log(n) ([1], p.82; [2], pp. 226-
227). The helper function _check_cycles_alt_sym is used to go over the cycles in
a permutation and look for ones satisfying 1).

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> D = DihedralGroup(10)
>>> D.is_alt_sym()
False

is_nilpotent
Test if the group is nilpotent.
A group G is nilpotent if it has a central series of finite length. Alternatively, G is
nilpotent if its lower central series terminates with the trivial group. Every nilpotent
group is also solvable ([1], p.29, [12]).
See also:
lower_central_series (page 254), is_solvable (page 253)

5.2. Combinatorics Module 251

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... CyclicGroup)
>>> C = CyclicGroup(6)
>>> C.is_nilpotent
True
>>> S = SymmetricGroup(5)
>>> S.is_nilpotent
False

is_normal(gr, strict=True)
Test if G=self is a normal subgroup of gr.
G is normal in gr if for each g2 in G, g1 in gr, g = g1*g2*g1**-1 belongs to G It is
sufficient to check this for each g1 in gr.generators and g2 in G.generators.

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([1, 2, 0])
>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G1 = PermutationGroup([a, Permutation([2, 0, 1])])
>>> G1.is_normal(G)
True

is_primitive(randomized=True)
Test if a group is primitive.
A permutation group G acting on a set S is called primitive if S contains no nontrivial
block under the action of G (a block is nontrivial if its cardinality is more than 1).
See also:
minimal_block (page 256), random_stab (page 261)

Notes

The algorithm is described in [1], p.83, and uses the function minimal_block to
search for blocks of the form {0, k} for k ranging over representatives for the or-
bits of G0 , the stabilizer of 0. This algorithm has complexity O(n2 ) where n is the
degree of the group, and will perform badly if G0 is small.
There are two implementations offered: one finds G0 deterministically using the
function stabilizer, and the other (default) produces random elements of G0 using
random_stab, hoping that they generate a subgroup of G0 with not too many more
orbits than G0 (this is suggested in [1], p.83). Behavior is changed by the randomized
flag.

252 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> D = DihedralGroup(10)
>>> D.is_primitive()
False

is_solvable
Test if the group is solvable.
G is solvable if its derived series terminates with the trivial group ([1], p.29).
See also:
is_nilpotent (page 251), derived_series (page 247)

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> S = SymmetricGroup(3)
>>> S.is_solvable
True

is_subgroup(G, strict=True)
Return True if all elements of self belong to G.
If strict is False then if self’s degree is smaller than G’s, the elements will be
resized to have the same degree.

Examples

>>> from sympy.combinatorics import Permutation, PermutationGroup

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,
... CyclicGroup)

Testing is strict by default: the degree of each group must be the same:

>>> p = Permutation(0, 1, 2, 3, 4, 5)
>>> G1 = PermutationGroup([Permutation(0, 1, 2), Permutation(0, 1)])
>>> G2 = PermutationGroup([Permutation(0, 2), Permutation(0, 1, 2)])
>>> G3 = PermutationGroup([p, p**2])
>>> assert G1.order() == G2.order() == G3.order() == 6
>>> G1.is_subgroup(G2)
True
>>> G1.is_subgroup(G3)
False
>>> G3.is_subgroup(PermutationGroup(G3[1]))
False
>>> G3.is_subgroup(PermutationGroup(G3[0]))
True

To ignore the size, set strict to False:

5.2. Combinatorics Module 253

SymPy Documentation, Release 1.3

>>> S3 = SymmetricGroup(3)
>>> S5 = SymmetricGroup(5)
>>> S3.is_subgroup(S5, strict=False)
True
>>> C7 = CyclicGroup(7)
>>> G = S5*C7
>>> S5.is_subgroup(G, False)
True
>>> C7.is_subgroup(G, 0)
False

is_transitive(strict=True)
Test if the group is transitive.
A group is transitive if it has a single orbit.
If strict is False the group is transitive if it has a single orbit of length different
from 1.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1, 3])
>>> b = Permutation([2, 0, 1, 3])
>>> G1 = PermutationGroup([a, b])
>>> G1.is_transitive()
False
>>> G1.is_transitive(strict=False)
True
>>> c = Permutation([2, 3, 0, 1])
>>> G2 = PermutationGroup([a, c])
>>> G2.is_transitive()
True
>>> d = Permutation([1, 0, 2, 3])
>>> e = Permutation([0, 1, 3, 2])
>>> G3 = PermutationGroup([d, e])
>>> G3.is_transitive() or G3.is_transitive(strict=False)
False

is_trivial
Test if the group is the trivial group.
This is true if the group contains only the identity permutation.

Examples

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> G = PermutationGroup([Permutation([0, 1, 2])])
>>> G.is_trivial
True

lower_central_series()
Return the lower central series for the group.

254 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The lower central series for a group G is the series G = G0 > G1 > G2 > . . . where
Gk = [G, Gk−1 ], i.e. every term after the first is equal to the commutator of G and the
previous term in G1 ([1], p.29).
Returns A list of permutation groups in the order G = G0 , G1 , G2 , . . .
See also:
commutator (page 244), derived_series (page 247)

Examples

>>> from sympy.combinatorics.named_groups import (AlternatingGroup,

... DihedralGroup)
>>> A = AlternatingGroup(4)
>>> len(A.lower_central_series())
2
>>> A.lower_central_series()[1].is_subgroup(DihedralGroup(2))
True

make_perm(n, seed=None)
Multiply n randomly selected permutations from pgroup together, starting with the
identity permutation. If n is a list of integers, those integers will be used to select
the permutations and they will be applied in L to R order: make_perm((A, B, C)) will
give CBA(I) where I is the identity permutation.
seed is used to set the seed for the random selection of permutations from pgroup. If
this is a list of integers, the corresponding permutations from pgroup will be selected
in the order give. This is mainly used for testing purposes.
See also:
random (page 260)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a, b = [Permutation([1, 0, 3, 2]), Permutation([1, 3, 0, 2])]
>>> G = PermutationGroup([a, b])
>>> G.make_perm(1, [0])
(0 1)(2 3)
>>> G.make_perm(3, [0, 1, 0])
(0 2 3 1)
>>> G.make_perm([0, 1, 0])
(0 2 3 1)

max_div
Maximum proper divisor of the degree of a permutation group.
See also:
minimal_block (page 256), _union_find_merge

5.2. Combinatorics Module 255

SymPy Documentation, Release 1.3

Notes

Obviously, this is the degree divided by its minimal proper divisor (larger than 1, if
one exists). As it is guaranteed to be prime, the sieve from sympy.ntheory is used.
This function is also used as an optimization tool for the functions minimal_block
and _union_find_merge.

Examples

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> G = PermutationGroup([Permutation([0, 2, 1, 3])])
>>> G.max_div
2

minimal_block(points)
For a transitive group, finds the block system generated by points.
If a group G acts on a set S, a nonempty subset B of S is called a block under the
action of G if for all g in G we have gB = B (g fixes B) or gB and B have no common
points (g moves B entirely). ([1], p.23; [6]).
The distinct translates gB of a block B for g in G partition the set S and this set of
translates is known as a block system. Moreover, we obviously have that all blocks
in the partition have the same size, hence the block size divides |S| ([1], p.23). A G-
congruence is an equivalence relation ~ on the set S such that a ~ b implies g(a) ~
g(b) for all g in G. For a transitive group, the equivalence classes of a G-congruence
and the blocks of a block system are the same thing ([1], p.23).
The algorithm below checks the group for transitivity, and then finds the G-
congruence generated by the pairs (p_0, p_1), (p_0, p_2), ..., (p_0,p_{k-
1}) which is the same as finding the maximal block system (i.e., the one with mini-
mum block size) such that p_0, ..., p_{k-1} are in the same block ([1], p.83).
It is an implementation of Atkinson’s algorithm, as suggested in [1], and manipulates
an equivalence relation on the set S using a union-find data structure. The running
time is just above O(|points||S|). ([1], pp. 83-87; [7]).
See also:
_union_find_rep, _union_find_merge, is_transitive (page 254), is_primitive
(page 252)

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> D = DihedralGroup(10)
>>> D.minimal_block([0, 5])
[0, 1, 2, 3, 4, 0, 1, 2, 3, 4]
>>> D.minimal_block([0, 1])
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

256 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

minimal_blocks(randomized=True)
For a transitive group, return the list of all minimal block systems. If a group is
intransitive, return F alse.
See also:
minimal_block (page 256), is_transitive (page 254), is_primitive (page 252)

Examples

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> DihedralGroup(6).minimal_blocks()
[[0, 1, 0, 1, 0, 1], [0, 1, 2, 0, 1, 2]]
>>> G = PermutationGroup(Permutation(1,2,5))
>>> G.minimal_blocks()
False

normal_closure(other, k=10)
Return the normal closure of a subgroup/set of permutations.
If S is a subset of a group G, the normal closure of A in G is defined as the intersection
of all normal subgroups of G that contain A ([1], p.14). Alternatively, it is the group
generated by the conjugates x^{-1}yx for x a generator of G and y a generator
of the subgroup \left\langle S\right\rangle generated by S (for some chosen
generating set for \left\langle S\right\rangle) ([1], p.73).
Parameters other
a subgroup/list of permutations/single permutation
k
an implementation-specific parameter that determines the number of
conjugates that are adjoined to other at once
See also:
commutator (page 244), derived_subgroup (page 248), random_pr (page 260)

Notes

The algorithm is described in [1], pp. 73-74; it makes use of the generation of ran-
dom elements for permutation groups by the product replacement algorithm.

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... CyclicGroup, AlternatingGroup)
>>> S = SymmetricGroup(5)
>>> C = CyclicGroup(5)
>>> G = S.normal_closure(C)
>>> G.order()
60
(continues on next page)

5.2. Combinatorics Module 257

SymPy Documentation, Release 1.3

(continued from previous page)

>>> G.is_subgroup(AlternatingGroup(5))
True

orbit(alpha, action=’tuples’)
Compute the orbit of alpha {g(α)|g ∈ G} as a set.
The time complexity of the algorithm used here is O(|Orb| ∗ r) where |Orb| is the size
of the orbit and r is the number of generators of the group. For a more detailed
analysis, see [1], p.78, [2], pp. 19-21. Here alpha can be a single point, or a list of
points.
If alpha is a single point, the ordinary orbit is computed. if alpha is a list of points,
there are three available options:
‘union’ - computes the union of the orbits of the points in the list ‘tuples’ - computes
the orbit of the list interpreted as an ordered tuple under the group action ( i.e.,
g((1,2,3)) = (g(1), g(2), g(3)) ) ‘sets’ - computes the orbit of the list interpreted as a
sets
See also:
orbit_transversal (page 258)

Examples

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([1, 2, 0, 4, 5, 6, 3])
>>> G = PermutationGroup([a])
>>> G.orbit(0)
{0, 1, 2}
>>> G.orbit([0, 4], 'union')
{0, 1, 2, 3, 4, 5, 6}

orbit_rep(alpha, beta, schreier_vector=None)

Return a group element which sends alpha to beta.
If beta is not in the orbit of alpha, the function returns False. This implementation
makes use of the schreier vector. For a proof of correctness, see [1], p.80
See also:
schreier_vector (page 263)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.named_groups import AlternatingGroup
>>> G = AlternatingGroup(5)
>>> G.orbit_rep(0, 4)
(0 4 1 2 3)

258 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

orbit_transversal(alpha, pairs=False)
Computes a transversal for the orbit of alpha as a set.
For a permutation group G, a transversal for the orbit Orb = {g(α)|g ∈ G} is a set
{gβ |gβ (α) = β} for β ∈ Orb. Note that there may be more than one possible transversal.
If pairs is set to True, it returns the list of pairs (β, gβ ). For a proof of correctness,
see [1], p.79
See also:
orbit (page 258)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> G = DihedralGroup(6)
>>> G.orbit_transversal(0)
[(5), (0 1 2 3 4 5), (0 5)(1 4)(2 3), (0 2 4)(1 3 5), (5)(0 4)(1 3), (0 3)(1␣
,→4)(2 5)]

orbits(rep=False)
Return the orbits of self, ordered according to lowest element in each orbit.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation(1, 5)(2, 3)(4, 0, 6)
>>> b = Permutation(1, 5)(3, 4)(2, 6, 0)
>>> G = PermutationGroup([a, b])
>>> G.orbits()
[{0, 2, 3, 4, 6}, {1, 5}]

order()
Return the order of the group: the number of permutations that can be generated
from elements of the group.
The number of permutations comprising the group is given by len(group); the
length of each permutation in the group is given by group.size.
See also:
degree (page 247)

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup

5.2. Combinatorics Module 259

SymPy Documentation, Release 1.3

>>> a = Permutation([1, 0, 2])

>>> G = PermutationGroup([a])
>>> G.degree
3
>>> len(G)
1
>>> G.order()
2
>>> list(G.generate())
[(2), (2)(0 1)]

>>> a = Permutation([0, 2, 1])

>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G.order()
6

pointwise_stabilizer(points, incremental=True)
Return the pointwise stabilizer for a set of points.
For a permutation group G and a set of points {p1 , p2 , . . . , pk }, the pointwise stabilizer
of p1 , p2 , . . . , pk is defined as Gp1 ,...,pk = {g ∈ G|g(pi ) = pi ∀i ∈ {1, 2, . . . , k}} ([1],p20). It is
a subgroup of G.
See also:
stabilizer (page 263), schreier_sims_incremental (page 261)

Notes

When incremental == True, rather than the obvious implementation using succes-
sive calls to .stabilizer(), this uses the incremental Schreier-Sims algorithm to
obtain a base with starting segment - the given points.

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> S = SymmetricGroup(7)
>>> Stab = S.pointwise_stabilizer([2, 3, 5])
>>> Stab.is_subgroup(S.stabilizer(2).stabilizer(3).stabilizer(5))
True

presentation(eliminate_gens=True)
Return an F pGroup presentation of the group.
The algorithm is described in [1], Chapter 6.1.
random(af=False)
Return a random group element
random_pr(gen_count=11, iterations=50, _random_prec=None)
Return a random group element using product replacement.
For the details of the product replacement algorithm, see _random_pr_init In ran-
dom_pr the actual ‘product replacement’ is performed. Notice that if the attribute
_random_gens is empty, it needs to be initialized by _random_pr_init.

260 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
_random_pr_init
random_stab(alpha, schreier_vector=None, _random_prec=None)
Random element from the stabilizer of alpha.
The schreier vector for alpha is an optional argument used for speeding up repeated
calls. The algorithm is described in [1], p.81
See also:
random_pr (page 260), orbit_rep (page 258)
schreier_sims()
Schreier-Sims algorithm.
It computes the generators of the chain of stabilizers G > Gb1 > .. > Gb1,..,br > 1 in
which Gb1 ,..,bi stabilizes b1 , .., bi , and the corresponding s cosets. An element of the
group can be written as the product h1 ∗ .. ∗ hs .
We use the incremental Schreier-Sims algorithm.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> a = Permutation([0, 2, 1])
>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G.schreier_sims()
>>> G.basic_transversals
[{0: (2)(0 1), 1: (2), 2: (1 2)},
{0: (2), 2: (0 2)}]

schreier_sims_incremental(base=None, gens=None, slp_dict=False)

Extend a sequence of points and generating set to a base and strong generating set.
Parameters base
The sequence of points to be extended to a base. Optional parameter
with default value [].
gens
The generating set to be extended to a strong generating set relative
to the base obtained. Optional parameter with default value self.
generators.
slp_dict
If T rue, return a dictionary g : gens for each strong generator g where
gens is a list of strong generators coming before g in strongg ens, such
that the product of the elements of gens is equal to g.
Returns (base, strong_gens)
base is the base obtained, and strong_gens is the strong generat-
ing set relative to it. The original parameters base, gens remain un-
changed.

5.2. Combinatorics Module 261

SymPy Documentation, Release 1.3

See also:
schreier_sims (page 261), schreier_sims_random (page 262)

Notes

This version of the Schreier-Sims algorithm runs in polynomial time. There are cer-
tain assumptions in the implementation - if the trivial group is provided, base and
gens are returned immediately, as any sequence of points is a base for the trivial
group. If the identity is present in the generators gens, it is removed as it is a re-
dundant generator. The implementation is described in [1], pp. 90-93.

Examples

>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> A = AlternatingGroup(7)
>>> base = [2, 3]
>>> seq = [2, 3]
>>> base, strong_gens = A.schreier_sims_incremental(base=seq)
>>> _verify_bsgs(A, base, strong_gens)
True
>>> base[:2]
[2, 3]

schreier_sims_random(base=None, gens=None, consec_succ=10, _ran-

dom_prec=None)
Randomized Schreier-Sims algorithm.
The randomized Schreier-Sims algorithm takes the sequence base and the generat-
ing set gens, and extends base to a base, and gens to a strong generating set rel-
ative to that base with probability of a wrong answer at most 2−consec_succ , provided
the random generators are sufficiently random.
Parameters base
The sequence to be extended to a base.
gens
The generating set to be extended to a strong generating set.
consec_succ
The parameter defining the probability of a wrong answer.
_random_prec
An internal parameter used for testing purposes.
Returns (base, strong_gens)
base is the base and strong_gens is the strong generating set relative
to it.
See also:
schreier_sims (page 261)

262 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notes

The algorithm is described in detail in [1], pp. 97-98. It extends the orbits orbs and
the permutation groups stabs to basic orbits and basic stabilizers for the base and
strong generating set produced in the end. The idea of the extension process is to
“sift” random group elements through the stabilizer chain and amend the stabiliz-
ers/orbits along the way when a sift is not successful. The helper function _strip
is used to attempt to decompose a random group element according to the current
state of the stabilizer chain and report whether the element was fully decomposed
(successful sift) or not (unsuccessful sift). In the latter case, the level at which the
sift failed is reported and used to amend stabs, base, gens and orbs accordingly.
The halting condition is for consec_succ consecutive successful sifts to pass. This
makes sure that the current base and gens form a BSGS with probability at least
1 − 1/consec_succ.

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> S = SymmetricGroup(5)
>>> base, strong_gens = S.schreier_sims_random(consec_succ=5)
>>> _verify_bsgs(S, base, strong_gens) #doctest: +SKIP
True

schreier_vector(alpha)
Computes the schreier vector for alpha.
The Schreier vector efficiently stores information about the orbit of alpha. It can
later be used to quickly obtain elements of the group that send alpha to a particular
element in the orbit. Notice that the Schreier vector depends on the order in which
the group generators are listed. For a definition, see [3]. Since list indices start from
zero, we adopt the convention to use “None” instead of 0 to signify that an element
doesn’t belong to the orbit. For the algorithm and its correctness, see [2], pp.78-80.
See also:
orbit (page 258)

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.permutations import Permutation
>>> a = Permutation([2, 4, 6, 3, 1, 5, 0])
>>> b = Permutation([0, 1, 3, 5, 4, 6, 2])
>>> G = PermutationGroup([a, b])
>>> G.schreier_vector(0)
[-1, None, 0, 1, None, 1, 0]

stabilizer(alpha)
Return the stabilizer subgroup of alpha.
The stabilizer of α is the group Gα = {g ∈ G|g(α) = α}. For a proof of correctness, see
[1], p.79.

5.2. Combinatorics Module 263

SymPy Documentation, Release 1.3

See also:
orbit (page 258)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> G = DihedralGroup(6)
>>> G.stabilizer(5)
PermutationGroup([
(5)(0 4)(1 3)])

strong_gens
Return a strong generating set from the Schreier-Sims algorithm.
A generating set S = {g1 , g2 , ..., gt } for a permutation group G is a strong generating
set relative to the sequence of points (referred to as a “base”) (b1 , b2 , ..., bk ) if, for
1 ≤ i ≤ k we have that the intersection of the pointwise stabilizer G(i+1) := Gb1 ,b2 ,...,bi
with S generates the pointwise stabilizer G(i+1) . The concepts of a base and strong
generating set and their applications are discussed in depth in [1], pp. 87-89 and
[2], pp. 55-57.
See also:
base (page 240), basic_transversals (page 242), basic_orbits (page 241), ba-
sic_stabilizers (page 242)

Examples

>>> from sympy.combinatorics.named_groups import DihedralGroup

>>> D = DihedralGroup(4)
>>> D.strong_gens
[(0 1 2 3), (0 3)(1 2), (1 3)]
>>> D.base
[0, 1]

strong_presentation()
Return a strong finite presentation of G. The generators of the returned group are
in the same order as the strong generators of G.
The algorithm is based on Sims’ Verify algorithm described in [1], Chapter 6.
See also:
presentation (page 260), _verify

Example

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> P = DihedralGroup(4)
(continues on next page)

264 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> G = P.strong_presentation()
>>> P.order() == G.order()
True

subgroup(gens)
Return the subgroup generated by gens which is a list of elements of the group
subgroup_search(prop, base=None, strong_gens=None, tests=None,
init_subgroup=None)
Find the subgroup of all elements satisfying the property prop.
This is done by a depth-first search with respect to base images that uses several
tests to prune the search tree.
Parameters prop
The property to be used. Has to be callable on group elements and
always return True or False. It is assumed that all group elements
satisfying prop indeed form a subgroup.
base
A base for the supergroup.
strong_gens
A strong generating set for the supergroup.
tests
A list of callables of length equal to the length of base. These are
used to rule out group elements by partial base images, so that
tests[l](g) returns False if the element g is known not to satisfy
prop base on where g sends the first l + 1 base points.
init_subgroup
if a subgroup of the sought group is known in advance, it can be
passed to the function as this parameter.
Returns res
The subgroup of all elements satisfying prop. The generating set for
this group is guaranteed to be a strong generating set relative to the
base base.

Notes

This function is extremely lengthy and complicated and will require some careful
attention. The implementation is described in [1], pp. 114-117, and the comments
for the code here follow the lines of the pseudocode in the book for clarity.
The complexity is exponential in general, since the search process by itself visits
all members of the supergroup. However, there are a lot of tests which are used to
prune the search tree, and users can define their own tests via the tests parameter,
so in practice, and for some computations, it’s not terrible.
A crucial part in the procedure is the frequent base change performed (this is line
11 in the pseudocode) in order to obtain a new basic stabilizer. The book mentiones
that this can be done by using .baseswap(...), however the current implementation

5.2. Combinatorics Module 265

SymPy Documentation, Release 1.3

uses a more straightforward way to find the next basic stabilizer - calling the function
.stabilizer(...) on the previous basic stabilizer.

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... AlternatingGroup)
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> S = SymmetricGroup(7)
>>> prop_even = lambda x: x.is_even
>>> base, strong_gens = S.schreier_sims_incremental()
>>> G = S.subgroup_search(prop_even, base=base, strong_gens=strong_gens)
>>> G.is_subgroup(AlternatingGroup(7))
True
>>> _verify_bsgs(G, base, G.generators)
True

sylow_subgroup(p)
Return a p-Sylow subgroup of the group.
The algorithm is described in [1], Chapter 4, Section 7

Examples

>>> from sympy.combinatorics.named_groups import DihedralGroup

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> D = DihedralGroup(6)
>>> S = D.sylow_subgroup(2)
>>> S.order()
4
>>> G = SymmetricGroup(6)
>>> S = G.sylow_subgroup(5)
>>> S.order()
5

>>> G1 = AlternatingGroup(3)
>>> G2 = AlternatingGroup(5)
>>> G3 = AlternatingGroup(9)

>>> S1 = G1.sylow_subgroup(3)
>>> S2 = G2.sylow_subgroup(3)
>>> S3 = G3.sylow_subgroup(3)

>>> len1 = len(S1.lower_central_series())

>>> len2 = len(S2.lower_central_series())
>>> len3 = len(S3.lower_central_series())

>>> len1 == len2

True
(continues on next page)

266 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> len1 < len3
True

transitivity_degree
Compute the degree of transitivity of the group.
A permutation group G acting on Ω = {0, 1, ..., n − 1} is k-fold transitive, if, for any k
points (a1 , a2 , ..., ak ) ∈ Ω and any k points (b1 , b2 , ..., bk ) ∈ Ω there exists g ∈ G such that
g(a1 ) = b1 , g(a2 ) = b2 , ..., g(ak ) = bk The degree of transitivity of G is the maximum k
such that G is k-fold transitive. ([8])
See also:
is_transitive (page 254), orbit (page 258)

Examples

>>> from sympy.combinatorics.perm_groups import PermutationGroup

>>> from sympy.combinatorics.permutations import Permutation
>>> a = Permutation([1, 2, 0])
>>> b = Permutation([1, 0, 2])
>>> G = PermutationGroup([a, b])
>>> G.transitivity_degree
3

Polyhedron

class sympy.combinatorics.polyhedron.Polyhedron
Represents the polyhedral symmetry group (PSG).
The PSG is one of the symmetry groups of the Platonic solids. There are three polyhedral
groups: the tetrahedral group of order 12, the octahedral group of order 24, and the
icosahedral group of order 60.
All doctests have been given in the docstring of the constructor of the object.

References

http://mathworld.wolfram.com/PolyhedralGroup.html
array_form
Return the indices of the corners.
The indices are given relative to the original position of corners.
See also:
corners (page 268), cyclic_form (page 268)

Examples

5.2. Combinatorics Module 267

SymPy Documentation, Release 1.3

>>> from sympy.combinatorics import Permutation, Cycle

>>> from sympy.combinatorics.polyhedron import tetrahedron
>>> tetrahedron = tetrahedron.copy()
>>> tetrahedron.array_form
[0, 1, 2, 3]

>>> tetrahedron.rotate(0)
>>> tetrahedron.array_form
[0, 2, 3, 1]
>>> tetrahedron.pgroup[0].array_form
[0, 2, 3, 1]

corners
Get the corners of the Polyhedron.
The method vertices is an alias for corners.
See also:
array_form (page 267), cyclic_form (page 268)

Examples

>>> from sympy.combinatorics import Polyhedron

>>> from sympy.abc import a, b, c, d
>>> p = Polyhedron(list('abcd'))
>>> p.corners == p.vertices == (a, b, c, d)
True

cyclic_form
Return the indices of the corners in cyclic notation.
The indices are given relative to the original position of corners.
See also:
corners (page 268), array_form (page 267)
edges
Given the faces of the polyhedra we can get the edges.

Examples

>>> from sympy.combinatorics import Polyhedron

>>> from sympy.abc import a, b, c
>>> corners = (a, b, c)
>>> faces = [(0, 1, 2)]
>>> Polyhedron(corners, faces).edges
{(0, 1), (0, 2), (1, 2)}

faces
Get the faces of the Polyhedron.
pgroup
Get the permutations of the Polyhedron.

268 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

reset()
Return corners to their original positions.

Examples

>>> from sympy.combinatorics.polyhedron import tetrahedron as T

>>> T = T.copy()
>>> T.corners
(0, 1, 2, 3)
>>> T.rotate(0)
>>> T.corners
(0, 2, 3, 1)
>>> T.reset()
>>> T.corners
(0, 1, 2, 3)

rotate(perm)
Apply a permutation to the polyhedron in place. The permutation may be given as
a Permutation instance or an integer indicating which permutation from pgroup of
the Polyhedron should be applied.
This is an operation that is analogous to rotation about an axis by a fixed increment.

Notes

When a Permutation is applied, no check is done to see if that is a valid permuta-

tion for the Polyhedron. For example, a cube could be given a permutation which
effectively swaps only 2 vertices. A valid permutation (that rotates the object in a
physical way) will be obtained if one only uses permutations from the pgroup of the
Polyhedron. On the other hand, allowing arbitrary rotations (applications of permu-
tations) gives a way to follow named elements rather than indices since Polyhedron
allows vertices to be named while Permutation works only with indices.

Examples

>>> from sympy.combinatorics import Polyhedron, Permutation

>>> from sympy.combinatorics.polyhedron import cube
>>> cube = cube.copy()
>>> cube.corners
(0, 1, 2, 3, 4, 5, 6, 7)
>>> cube.rotate(0)
>>> cube.corners
(1, 2, 3, 0, 5, 6, 7, 4)

A non-physical “rotation” that is not prohibited by this method:

>>> cube.reset()
>>> cube.rotate(Permutation([[1, 2]], size=8))
>>> cube.corners
(0, 2, 1, 3, 4, 5, 6, 7)

Polyhedron can be used to follow elements of set that are identified by letters instead
of integers:

5.2. Combinatorics Module 269

SymPy Documentation, Release 1.3

>>> shadow = h5 = Polyhedron(list('abcde'))

>>> p = Permutation([3, 0, 1, 2, 4])
>>> h5.rotate(p)
>>> h5.corners
(d, a, b, c, e)
>>> _ == shadow.corners
True
>>> copy = h5.copy()
>>> h5.rotate(p)
>>> h5.corners == copy.corners
False

size
Get the number of corners of the Polyhedron.
vertices
Get the corners of the Polyhedron.
The method vertices is an alias for corners.
See also:
array_form (page 267), cyclic_form (page 268)

Examples

>>> from sympy.combinatorics import Polyhedron

>>> from sympy.abc import a, b, c, d
>>> p = Polyhedron(list('abcd'))
>>> p.corners == p.vertices == (a, b, c, d)
True

Prufer Sequences

class sympy.combinatorics.prufer.Prufer
The Prufer correspondence is an algorithm that describes the bijection between labeled
trees and the Prufer code. A Prufer code of a labeled tree is unique up to isomorphism
and has a length of n - 2.
Prufer sequences were first used by Heinz Prufer to give a proof of Cayley’s formula.

References

[R36]
static edges(*runs)
Return a list of edges and the number of nodes from the given runs that connect
nodes in an integer-labelled tree.
All node numbers will be shifted so that the minimum node is 0. It is not a problem
if edges are repeated in the runs; only unique edges are returned. There is no
assumption made about what the range of the node labels should be, but all nodes
from the smallest through the largest must be present.

270 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer.edges([1, 2, 3], [2, 4, 5]) # a T
([[0, 1], [1, 2], [1, 3], [3, 4]], 5)

Duplicate edges are removed:

>>> Prufer.edges([0, 1, 2, 3], [1, 4, 5], [1, 4, 6]) # a K
([[0, 1], [1, 2], [1, 4], [2, 3], [4, 5], [4, 6]], 7)

next(delta=1)
Generates the Prufer sequence that is delta beyond the current one.
See also:
prufer_rank (page 272), rank (page 272), prev (page 271), size (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> a = Prufer([[0, 1], [0, 2], [0, 3]])
>>> b = a.next(1) # == a.next()
>>> b.tree_repr
[[0, 2], [0, 1], [1, 3]]
>>> b.rank
1

nodes
Returns the number of nodes in the tree.

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).nodes
6
>>> Prufer([1, 0, 0]).nodes
5

prev(delta=1)
Generates the Prufer sequence that is -delta before the current one.
See also:
prufer_rank (page 272), rank (page 272), next (page 271), size (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> a = Prufer([[0, 1], [1, 2], [2, 3], [1, 4]])
>>> a.rank
36
>>> b = a.prev()
(continues on next page)

5.2. Combinatorics Module 271

SymPy Documentation, Release 1.3

(continued from previous page)

>>> b
Prufer([1, 2, 0])
>>> b.rank
35

prufer_rank()
Computes the rank of a Prufer sequence.
See also:
rank (page 272), next (page 271), prev (page 271), size (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> a = Prufer([[0, 1], [0, 2], [0, 3]])
>>> a.prufer_rank()
0

prufer_repr
Returns Prufer sequence for the Prufer object.
This sequence is found by removing the highest numbered vertex, recording the
node it was attached to, and continuing until only two vertices remain. The Prufer
sequence is the list of recorded nodes.
See also:
to_prufer (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).prufer_repr
[3, 3, 3, 4]
>>> Prufer([1, 0, 0]).prufer_repr
[1, 0, 0]

rank
Returns the rank of the Prufer sequence.
See also:
prufer_rank (page 272), next (page 271), prev (page 271), size (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> p = Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]])
>>> p.rank
778
>>> p.next(1).rank
779
(continues on next page)

272 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> p.prev().rank
777

size
Return the number of possible trees of this Prufer object.
See also:
prufer_rank (page 272), rank (page 272), next (page 271), prev (page 271)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer([0]*4).size == Prufer([6]*4).size == 1296
True

static to_prufer(tree, n)
Return the Prufer sequence for a tree given as a list of edges where n is the number
of nodes in the tree.
See also:

prufer_repr (page 272) returns Prufer sequence of a Prufer object.

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> a = Prufer([[0, 1], [0, 2], [0, 3]])
>>> a.prufer_repr
[0, 0]
>>> Prufer.to_prufer([[0, 1], [0, 2], [0, 3]], 4)
[0, 0]

static to_tree(prufer)
Return the tree (as a list of edges) of the given Prufer sequence.
See also:

tree_repr (page 274) returns tree representation of a Prufer object.

References

• https://hamberg.no/erlend/posts/2010-11-06-prufer-sequence-compact-tree-representation.
html

Examples

5.2. Combinatorics Module 273

SymPy Documentation, Release 1.3

>>> from sympy.combinatorics.prufer import Prufer

>>> a = Prufer([0, 2], 4)
>>> a.tree_repr
[[0, 1], [0, 2], [2, 3]]
>>> Prufer.to_tree([0, 2])
[[0, 1], [0, 2], [2, 3]]

tree_repr
Returns the tree representation of the Prufer object.
See also:
to_tree (page 273)

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).tree_repr
[[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]
>>> Prufer([1, 0, 0]).tree_repr
[[1, 2], [0, 1], [0, 3], [0, 4]]

classmethod unrank(rank, n)
Finds the unranked Prufer sequence.

Examples

>>> from sympy.combinatorics.prufer import Prufer

>>> Prufer.unrank(0, 4)
Prufer([0, 0])

Subsets

class sympy.combinatorics.subsets.Subset
Represents a basic subset object.
We generate subsets using essentially two techniques, binary enumeration and lexico-
graphic enumeration. The Subset class takes two arguments, the first one describes the
initial subset to consider and the second describes the superset.

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.next_binary().subset
['b']
>>> a.prev_binary().subset
['c']

274 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

classmethod bitlist_from_subset(subset, superset)

Gets the bitlist corresponding to a subset.
See also:
subset_from_bitlist (page 279)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> Subset.bitlist_from_subset(['c', 'd'], ['a', 'b', 'c', 'd'])
'0011'

cardinality
Returns the number of all possible subsets.
See also:
subset (page 279), superset (page 279), size (page 278), superset_size
(page 280)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.cardinality
16

iterate_binary(k)
This is a helper function. It iterates over the binary subsets by k steps. This variable
can be both positive or negative.
See also:
next_binary (page 276), prev_binary (page 277)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.iterate_binary(-2).subset
['d']
>>> a = Subset(['a', 'b', 'c'], ['a', 'b', 'c', 'd'])
>>> a.iterate_binary(2).subset
[]

iterate_graycode(k)
Helper function used for prev_gray and next_gray. It performs k step overs to get
the respective Gray codes.
See also:
next_gray (page 276), prev_gray (page 277)

5.2. Combinatorics Module 275

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([1, 2, 3], [1, 2, 3, 4])
>>> a.iterate_graycode(3).subset
[1, 4]
>>> a.iterate_graycode(-2).subset
[1, 2, 4]

next_binary()
Generates the next binary ordered subset.
See also:
prev_binary (page 277), iterate_binary (page 275)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.next_binary().subset
['b']
>>> a = Subset(['a', 'b', 'c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.next_binary().subset
[]

next_gray()
Generates the next Gray code ordered subset.
See also:
iterate_graycode (page 275), prev_gray (page 277)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([1, 2, 3], [1, 2, 3, 4])
>>> a.next_gray().subset
[1, 3]

next_lexicographic()
Generates the next lexicographically ordered subset.
See also:
prev_lexicographic (page 277)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.next_lexicographic().subset
['d']
(continues on next page)

276 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> a = Subset(['d'], ['a', 'b', 'c', 'd'])
>>> a.next_lexicographic().subset
[]

prev_binary()
Generates the previous binary ordered subset.
See also:
next_binary (page 276), iterate_binary (page 275)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([], ['a', 'b', 'c', 'd'])
>>> a.prev_binary().subset
['a', 'b', 'c', 'd']
>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.prev_binary().subset
['c']

prev_gray()
Generates the previous Gray code ordered subset.
See also:
iterate_graycode (page 275), next_gray (page 276)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([2, 3, 4], [1, 2, 3, 4, 5])
>>> a.prev_gray().subset
[2, 3, 4, 5]

prev_lexicographic()
Generates the previous lexicographically ordered subset.
See also:
next_lexicographic (page 276)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([], ['a', 'b', 'c', 'd'])
>>> a.prev_lexicographic().subset
['d']
>>> a = Subset(['c','d'], ['a', 'b', 'c', 'd'])
>>> a.prev_lexicographic().subset
['c']

5.2. Combinatorics Module 277

SymPy Documentation, Release 1.3

rank_binary
Computes the binary ordered rank.
See also:
iterate_binary (page 275), unrank_binary (page 280)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset([], ['a','b','c','d'])
>>> a.rank_binary
0
>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.rank_binary
3

rank_gray
Computes the Gray code ranking of the subset.
See also:
iterate_graycode (page 275), unrank_gray (page 280)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c','d'], ['a','b','c','d'])
>>> a.rank_gray
2
>>> a = Subset([2, 4, 5], [1, 2, 3, 4, 5, 6])
>>> a.rank_gray
27

rank_lexicographic
Computes the lexicographic ranking of the subset.

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.rank_lexicographic
14
>>> a = Subset([2, 4, 5], [1, 2, 3, 4, 5, 6])
>>> a.rank_lexicographic
43

size
Gets the size of the subset.
See also:
subset (page 279), superset (page 279), superset_size (page 280), cardinality
(page 275)

278 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.size
2

subset
Gets the subset represented by the current instance.
See also:
superset (page 279), size (page 278), superset_size (page 280), cardinality
(page 275)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.subset
['c', 'd']

classmethod subset_from_bitlist(super_set, bitlist)

Gets the subset defined by the bitlist.
See also:
bitlist_from_subset (page 274)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> Subset.subset_from_bitlist(['a', 'b', 'c', 'd'], '0011').subset
['c', 'd']

classmethod subset_indices(subset, superset)

Return indices of subset in superset in a list; the list is empty if all elements of subset
are not in superset.

Examples

>>> from sympy.combinatorics import Subset

>>> superset = [1, 3, 2, 5, 4]
>>> Subset.subset_indices([3, 2, 1], superset)
[1, 2, 0]
>>> Subset.subset_indices([1, 6], superset)
[]
>>> Subset.subset_indices([], superset)
[]

superset
Gets the superset of the subset.
See also:

5.2. Combinatorics Module 279

SymPy Documentation, Release 1.3

subset (page 279), size (page 278), superset_size (page 280), cardinality
(page 275)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.superset
['a', 'b', 'c', 'd']

superset_size
Returns the size of the superset.
See also:
subset (page 279), superset (page 279), size (page 278), cardinality (page 275)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
>>> a.superset_size
4

classmethod unrank_binary(rank, superset)

Gets the binary ordered subset of the specified rank.
See also:
iterate_binary (page 275), rank_binary (page 277)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> Subset.unrank_binary(4, ['a', 'b', 'c', 'd']).subset
['b']

classmethod unrank_gray(rank, superset)

Gets the Gray code ordered subset of the specified rank.
See also:
iterate_graycode (page 275), rank_gray (page 278)

Examples

>>> from sympy.combinatorics.subsets import Subset

>>> Subset.unrank_gray(4, ['a', 'b', 'c']).subset
['a', 'b']
>>> Subset.unrank_gray(0, ['a', 'b', 'c']).subset
[]

280 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

subsets.ksubsets(k)
Finds the subsets of size k in lexicographic order.
This uses the itertools generator.
See also:

class Subset

Examples

>>> from sympy.combinatorics.subsets import ksubsets

>>> list(ksubsets([1, 2, 3], 2))
[(1, 2), (1, 3), (2, 3)]
>>> list(ksubsets([1, 2, 3, 4, 5], 2))
[(1, 2), (1, 3), (1, 4), (1, 5), (2, 3), (2, 4), (2, 5), (3, 4), (3, 5), (4,␣
,→5)]

Gray Code

class sympy.combinatorics.graycode.GrayCode
A Gray code is essentially a Hamiltonian walk on a n-dimensional cube with edge length
of one. The vertices of the cube are represented by vectors whose values are binary.
The Hamilton walk visits each vertex exactly once. The Gray code for a 3d cube is
[‘000’,‘100’,‘110’,‘010’,‘011’,‘111’,‘101’, ‘001’].
A Gray code solves the problem of sequentially generating all possible subsets of n ob-
jects in such a way that each subset is obtained from the previous one by either deleting
or adding a single object. In the above example, 1 indicates that the object is present,
and 0 indicates that its absent.
Gray codes have applications in statistics as well when we want to compute various
statistics related to subsets in an efficient manner.
References: [1] Nijenhuis,A. and Wilf,H.S.(1978). Combinatorial Algorithms. Academic
Press. [2] Knuth, D. (2011). The Art of Computer Programming, Vol 4 Addison Wesley

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3)
>>> list(a.generate_gray())
['000', '001', '011', '010', '110', '111', '101', '100']
>>> a = GrayCode(4)
>>> list(a.generate_gray())
['0000', '0001', '0011', '0010', '0110', '0111', '0101', '0100', '1100', '1101
,→', '1111', '1110', '1010', '1011', '1001', '1000']

current
Returns the currently referenced Gray code as a bit string.

5.2. Combinatorics Module 281

SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> GrayCode(3, start='100').current
'100'

generate_gray(**hints)
Generates the sequence of bit vectors of a Gray Code.
[1] Knuth, D. (2011). The Art of Computer Programming, Vol 4, Addison Wesley
See also:
skip (page 283)

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3)
>>> list(a.generate_gray())
['000', '001', '011', '010', '110', '111', '101', '100']
>>> list(a.generate_gray(start='011'))
['011', '010', '110', '111', '101', '100']
>>> list(a.generate_gray(rank=4))
['110', '111', '101', '100']

n
Returns the dimension of the Gray code.

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(5)
>>> a.n
5

next(delta=1)
Returns the Gray code a distance delta (default = 1) from the current value in
canonical order.

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3, start='110')
>>> a.next().current
'111'
>>> a.next(-1).current
'010'

rank
Ranks the Gray code.

282 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

A ranking algorithm determines the position (or rank) of a combinatorial object

among all the objects w.r.t. a given order. For example, the 4 bit binary reflected
Gray code (BRGC) ‘0101’ has a rank of 6 as it appears in the 6th position in the
canonical ordering of the family of 4 bit Gray codes.
References: [1] http://statweb.stanford.edu/~susan/courses/s208/node12.html
See also:
unrank (page 284)

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3)
>>> list(a.generate_gray())
['000', '001', '011', '010', '110', '111', '101', '100']
>>> GrayCode(3, start='100').rank
7
>>> GrayCode(3, rank=7).current
'100'

selections
Returns the number of bit vectors in the Gray code.

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3)
>>> a.selections
8

skip()
Skips the bit generation.
See also:
generate_gray (page 282)

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> a = GrayCode(3)
>>> for i in a.generate_gray():
... if i == '010':
... a.skip()
... print(i)
...
000
001
011
010
111
(continues on next page)

5.2. Combinatorics Module 283

SymPy Documentation, Release 1.3

(continued from previous page)

101
100

classmethod unrank(n, rank)

Unranks an n-bit sized Gray code of rank k. This method exists so that a derivative
GrayCode class can define its own code of a given rank.
The string here is generated in reverse order to allow for tail-call optimization.
See also:
rank (page 282)

Examples

>>> from sympy.combinatorics.graycode import GrayCode

>>> GrayCode(5, rank=3).current
'00010'
>>> GrayCode.unrank(5, 3)
'00010'

graycode.random_bitstring()
Generates a random bitlist of length n.

Examples

>>> from sympy.combinatorics.graycode import random_bitstring

>>> random_bitstring(3) # doctest: +SKIP
100

graycode.gray_to_bin()
Convert from Gray coding to binary coding.
We assume big endian encoding.
See also:
bin_to_gray (page 284)

Examples

>>> from sympy.combinatorics.graycode import gray_to_bin

>>> gray_to_bin('100')
'111'

graycode.bin_to_gray()
Convert from binary coding to gray coding.
We assume big endian encoding.
See also:
gray_to_bin (page 284)

284 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.graycode import bin_to_gray

>>> bin_to_gray('111')
'100'

graycode.get_subset_from_bitstring(bitstring)
Gets the subset defined by the bitstring.
See also:
graycode_subsets (page 285)

Examples

>>> from sympy.combinatorics.graycode import get_subset_from_bitstring

>>> get_subset_from_bitstring(['a', 'b', 'c', 'd'], '0011')
['c', 'd']
>>> get_subset_from_bitstring(['c', 'a', 'c', 'c'], '1100')
['c', 'a']

graycode.graycode_subsets()
Generates the subsets as enumerated by a Gray code.
See also:
get_subset_from_bitstring (page 285)

Examples

>>> from sympy.combinatorics.graycode import graycode_subsets

>>> list(graycode_subsets(['a', 'b', 'c']))
[[], ['c'], ['b', 'c'], ['b'], ['a', 'b'], ['a', 'b', 'c'], ['a', 'c'], ['a']]
>>> list(graycode_subsets(['a', 'b', 'c', 'c']))
[[], ['c'], ['c', 'c'], ['c'], ['b', 'c'], ['b', 'c', 'c'], ['b', 'c'], ['b'],
,→ ['a', 'b'], ['a', 'b', 'c'], ['a', 'b', 'c', 'c'], ['a', 'b', 'c'], ['a',
,→'c'], ['a', 'c', 'c'], ['a', 'c'], ['a']]

Named Groups

sympy.combinatorics.named_groups.SymmetricGroup(n)
Generates the symmetric group on n elements as a permutation group.
The generators taken are the n-cycle (0 1 2 ... n-1) and the transposition (0 1) (in
cycle notation). (See [1]). After the group is generated, some of its basic properties are
set.
See also:
CyclicGroup (page 286), DihedralGroup (page 286), AlternatingGroup (page 287)

5.2. Combinatorics Module 285

SymPy Documentation, Release 1.3

References

[1] http://en.wikipedia.org/wiki/Symmetric_group#Generators_and_relations

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> G = SymmetricGroup(4)
>>> G.is_group
True
>>> G.order()
24
>>> list(G.generate_schreier_sims(af=True))
[[0, 1, 2, 3], [1, 2, 3, 0], [2, 3, 0, 1], [3, 1, 2, 0], [0, 2, 3, 1],
[1, 3, 0, 2], [2, 0, 1, 3], [3, 2, 0, 1], [0, 3, 1, 2], [1, 0, 2, 3],
[2, 1, 3, 0], [3, 0, 1, 2], [0, 1, 3, 2], [1, 2, 0, 3], [2, 3, 1, 0],
[3, 1, 0, 2], [0, 2, 1, 3], [1, 3, 2, 0], [2, 0, 3, 1], [3, 2, 1, 0],
[0, 3, 2, 1], [1, 0, 3, 2], [2, 1, 0, 3], [3, 0, 2, 1]]

sympy.combinatorics.named_groups.CyclicGroup(n)
Generates the cyclic group of order n as a permutation group.
The generator taken is the n-cycle (0 1 2 ... n-1) (in cycle notation). After the group
is generated, some of its basic properties are set.
See also:
SymmetricGroup (page 285), DihedralGroup (page 286), AlternatingGroup (page 287)

Examples

>>> from sympy.combinatorics.named_groups import CyclicGroup

>>> G = CyclicGroup(6)
>>> G.is_group
True
>>> G.order()
6
>>> list(G.generate_schreier_sims(af=True))
[[0, 1, 2, 3, 4, 5], [1, 2, 3, 4, 5, 0], [2, 3, 4, 5, 0, 1],
[3, 4, 5, 0, 1, 2], [4, 5, 0, 1, 2, 3], [5, 0, 1, 2, 3, 4]]

sympy.combinatorics.named_groups.DihedralGroup(n)
Generates the dihedral group Dn as a permutation group.
The dihedral group Dn is the group of symmetries of the regular n-gon. The generators
taken are the n-cycle a = (0 1 2 ... n-1) (a rotation of the n-gon) and b = (0 n-1)(1
n-2)... (a reflection of the n-gon) in cycle rotation. It is easy to see that these satisfy
a**n = b**2 = 1 and bab = ~a so they indeed generate Dn (See [1]). After the group
is generated, some of its basic properties are set.
See also:
SymmetricGroup (page 285), CyclicGroup (page 286), AlternatingGroup (page 287)

286 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[1] http://en.wikipedia.org/wiki/Dihedral_group

Examples

>>> from sympy.combinatorics.named_groups import DihedralGroup

>>> G = DihedralGroup(5)
>>> G.is_group
True
>>> a = list(G.generate_dimino())
>>> [perm.cyclic_form for perm in a]
[[], [[0, 1, 2, 3, 4]], [[0, 2, 4, 1, 3]],
[[0, 3, 1, 4, 2]], [[0, 4, 3, 2, 1]], [[0, 4], [1, 3]],
[[1, 4], [2, 3]], [[0, 1], [2, 4]], [[0, 2], [3, 4]],
[[0, 3], [1, 2]]]

sympy.combinatorics.named_groups.AlternatingGroup(n)
Generates the alternating group on n elements as a permutation group.
For n > 2, the generators taken are (0 1 2), (0 1 2 ... n-1) for n odd and (0 1 2),
(1 2 ... n-1) for n even (See [1], p.31, ex.6.9.). After the group is generated, some of
its basic properties are set. The cases n = 1, 2 are handled separately.
See also:
SymmetricGroup (page 285), CyclicGroup (page 286), DihedralGroup (page 286)

References

[1] Armstrong, M. “Groups and Symmetry”

Examples

>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> G = AlternatingGroup(4)
>>> G.is_group
True
>>> a = list(G.generate_dimino())
>>> len(a)
12
>>> all(perm.is_even for perm in a)
True

sympy.combinatorics.named_groups.AbelianGroup(*cyclic_orders)
Returns the direct product of cyclic groups with the given orders.
According to the structure theorem for finite abelian groups ([1]), every finite abelian
group can be written as the direct product of finitely many cyclic groups.
See also:
DirectProduct

5.2. Combinatorics Module 287

SymPy Documentation, Release 1.3

References

[1] http://groupprops.subwiki.org/wiki/Structure_theorem_for_finitely_generated_
abelian_groups

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import AbelianGroup
>>> AbelianGroup(3, 4)
PermutationGroup([
(6)(0 1 2),
(3 4 5 6)])
>>> _.is_group
True

Utilities

sympy.combinatorics.util._base_ordering(base, degree)
Order {0, 1, ..., n − 1} so that base points come first and in order.
Parameters ‘‘base‘‘ - the base
‘‘degree‘‘ - the degree of the associated permutation group
Returns A list base_ordering such that base_ordering[point] is the
number of point in the ordering.

Notes

This is used in backtrack searches, when we define a relation << on the underlying set
for a permutation group of degree n, {0, 1, ..., n − 1}, so that if (b1 , b2 , ..., bk ) is a base we
have bi << bj whenever i < j and bi << a for all i ∈ {1, 2, ..., k} and a is not in the base. The
idea is developed and applied to backtracking algorithms in [1], pp.108-132. The points
that are not in the base are taken in increasing order.

References

[1] Holt, D., Eick, B., O’Brien, E. “Handbook of computational group theory”

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> from sympy.combinatorics.util import _base_ordering
>>> S = SymmetricGroup(4)
>>> S.schreier_sims()
>>> _base_ordering(S.base, S.degree)
[0, 1, 2, 3]

288 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.combinatorics.util._check_cycles_alt_sym(perm)
Checks for cycles of prime length p with n/2 < p < n-2.
Here n is the degree of the permutation. This is a helper function for the function
is_alt_sym from sympy.combinatorics.perm_groups.
See also:
sympy.combinatorics.perm_groups.PermutationGroup.is_alt_sym (page 251)

Examples

>>> from sympy.combinatorics.util import _check_cycles_alt_sym

>>> from sympy.combinatorics.permutations import Permutation
>>> a = Permutation([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [11, 12]])
>>> _check_cycles_alt_sym(a)
False
>>> b = Permutation([[0, 1, 2, 3, 4, 5, 6], [7, 8, 9, 10]])
>>> _check_cycles_alt_sym(b)
True

sympy.combinatorics.util._distribute_gens_by_base(base, gens)
Distribute the group elements gens by membership in basic stabilizers.
Notice that for a base (b1 , b2 , ..., bk ), the basic stabilizers are defined as G(i) = Gb1 ,...,bi−1 for
i ∈ {1, 2, ..., k}.
Parameters ‘‘base‘‘ - a sequence of points in ‘{0, 1, …, n-1}‘
‘‘gens‘‘ - a list of elements of a permutation group of degree ‘n‘.
Returns List of length k, where k is
the length of base. The i-th entry contains those elements in
gens which fix the first i elements of base (so that the
0-th entry is equal to gens itself). If no element fixes the first
i elements of base, the i-th element is set to a list containing
the identity element.
See also:
_strong_gens_from_distr (page 293), _orbits_transversals_from_bsgs (page 290),
_handle_precomputed_bsgs (page 290)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> from sympy.combinatorics.util import _distribute_gens_by_base
>>> D = DihedralGroup(3)
>>> D.schreier_sims()
>>> D.strong_gens
[(0 1 2), (0 2), (1 2)]
>>> D.base
(continues on next page)

5.2. Combinatorics Module 289

SymPy Documentation, Release 1.3

(continued from previous page)

[0, 1]
>>> _distribute_gens_by_base(D.base, D.strong_gens)
[[(0 1 2), (0 2), (1 2)],
[(1 2)]]

sympy.combinatorics.util._handle_precomputed_bsgs(base, strong_gens,
transversals=None,
basic_orbits=None,
strong_gens_distr=None)
Calculate BSGS-related structures from those present.
The base and strong generating set must be provided; if any of the transversals, basic
orbits or distributed strong generators are not provided, they will be calculated from the
base and strong generating set.
Parameters ‘‘base‘‘ - the base
‘‘strong_gens‘‘ - the strong generators
‘‘transversals‘‘ - basic transversals
‘‘basic_orbits‘‘ - basic orbits
‘‘strong_gens_distr‘‘ - strong generators distributed by membership
in basic
stabilizers
Returns (transversals, basic_orbits, strong_gens_distr) where
transversals
are the basic transversals, basic_orbits are the basic orbits, and
strong_gens_distr are the strong generators distributed by membership
in basic stabilizers.
See also:
_orbits_transversals_from_bsgs (page 290), distribute_gens_by_base

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import DihedralGroup
>>> from sympy.combinatorics.util import _handle_precomputed_bsgs
>>> D = DihedralGroup(3)
>>> D.schreier_sims()
>>> _handle_precomputed_bsgs(D.base, D.strong_gens,
... basic_orbits=D.basic_orbits)
([{0: (2), 1: (0 1 2), 2: (0 2)}, {1: (2), 2: (1 2)}], [[0, 1, 2], [1, 2]], [[(0␣
,→1 2), (0 2), (1 2)], [(1 2)]])

sympy.combinatorics.util._orbits_transversals_from_bsgs(base,
strong_gens_distr,
transver-
sals_only=False,
slp=False)

290 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Compute basic orbits and transversals from a base and strong generating set.
The generators are provided as distributed across the basic stabilizers. If the optional
argument transversals_only is set to True, only the transversals are returned.
Parameters ‘‘base‘‘ - the base
‘‘strong_gens_distr‘‘ - strong generators distributed by membership
in basic
stabilizers
‘‘transversals_only‘‘ - a flag switching between returning only the
transversals/ both orbits and transversals
‘‘slp‘‘ - if ‘‘True‘‘, return a list of dictionaries containing the
generator presentations of the elements of the transversals, i.e. the
list of indices of generators from strongg ensd istr[i] such that their prod-
uct is the relevant transversal element
See also:
_distribute_gens_by_base (page 289), _handle_precomputed_bsgs (page 290)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.util import _orbits_transversals_from_bsgs
>>> from sympy.combinatorics.util import (_orbits_transversals_from_bsgs,
... _distribute_gens_by_base)
>>> S = SymmetricGroup(3)
>>> S.schreier_sims()
>>> strong_gens_distr = _distribute_gens_by_base(S.base, S.strong_gens)
>>> _orbits_transversals_from_bsgs(S.base, strong_gens_distr)
([[0, 1, 2], [1, 2]], [{0: (2), 1: (0 1 2), 2: (0 2 1)}, {1: (2), 2: (1 2)}])

sympy.combinatorics.util._remove_gens(base, strong_gens, basic_orbits=None,

strong_gens_distr=None)
Remove redundant generators from a strong generating set.
Parameters ‘‘base‘‘ - a base
‘‘strong_gens‘‘ - a strong generating set relative to ‘‘base‘‘
‘‘basic_orbits‘‘ - basic orbits
‘‘strong_gens_distr‘‘ - strong generators distributed by membership
in basic
stabilizers
Returns A strong generating set with respect to base which is a subset of
strong_gens.

5.2. Combinatorics Module 291

SymPy Documentation, Release 1.3

Notes

This procedure is outlined in [1],p.95.

References

[1] Holt, D., Eick, B., O’Brien, E. “Handbook of computational group theory”

Examples

>>> from sympy.combinatorics.named_groups import SymmetricGroup

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.util import _remove_gens
>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> S = SymmetricGroup(15)
>>> base, strong_gens = S.schreier_sims_incremental()
>>> new_gens = _remove_gens(base, strong_gens)
>>> len(new_gens)
14
>>> _verify_bsgs(S, base, new_gens)
True

sympy.combinatorics.util._strip(g, base, orbits, transversals)

Attempt to decompose a permutation using a (possibly partial) BSGS structure.
This is done by treating the sequence base as an actual base, and the orbits orbits and
transversals transversals as basic orbits and transversals relative to it.
This process is called “sifting”. A sift is unsuccessful when a certain orbit element is not
found or when after the sift the decomposition doesn’t end with the identity element.
The argument transversals is a list of dictionaries that provides transversal elements
for the orbits orbits.
Parameters ‘‘g‘‘ - permutation to be decomposed
‘‘base‘‘ - sequence of points
‘‘orbits‘‘ - a list in which the ‘‘i‘‘-th entry is an orbit of ‘‘base[i]‘‘
under some subgroup of the pointwise stabilizer of ‘
‘base[0], base[1], …, base[i - 1]‘‘. The groups themselves are implicit
in this function since the only information we need is encoded in the
orbits
and transversals
‘‘transversals‘‘ - a list of orbit transversals associated with the orbits
‘‘orbits‘‘.
See also:
sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims (page 261),
sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims_random
(page 262)

292 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notes

The algorithm is described in [1],pp.89-90. The reason for returning both the current
state of the element being decomposed and the level at which the sifting ends is that
they provide important information for the randomized version of the Schreier-Sims al-
gorithm.

References

[1] Holt, D., Eick, B., O’Brien, E. “Handbook of computational group theory”

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.permutations import Permutation
>>> from sympy.combinatorics.util import _strip
>>> S = SymmetricGroup(5)
>>> S.schreier_sims()
>>> g = Permutation([0, 2, 3, 1, 4])
>>> _strip(g, S.base, S.basic_orbits, S.basic_transversals)
((4), 5)

sympy.combinatorics.util._strong_gens_from_distr(strong_gens_distr)
Retrieve strong generating set from generators of basic stabilizers.
This is just the union of the generators of the first and second basic stabilizers.
Parameters ‘‘strong_gens_distr‘‘ - strong generators distributed by
membership in basic
stabilizers
See also:
_distribute_gens_by_base (page 289)

Examples

>>> from sympy.combinatorics import Permutation

>>> Permutation.print_cyclic = True
>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.util import (_strong_gens_from_distr,
... _distribute_gens_by_base)
>>> S = SymmetricGroup(3)
>>> S.schreier_sims()
>>> S.strong_gens
[(0 1 2), (2)(0 1), (1 2)]
>>> strong_gens_distr = _distribute_gens_by_base(S.base, S.strong_gens)
>>> _strong_gens_from_distr(strong_gens_distr)
[(0 1 2), (2)(0 1), (1 2)]

5.2. Combinatorics Module 293

SymPy Documentation, Release 1.3

Group constructors

sympy.combinatorics.group_constructs.DirectProduct(*groups)
Returns the direct product of several groups as a permutation group.
This is implemented much like the __mul__ procedure for taking the direct product of
two permutation groups, but the idea of shifting the generators is realized in the case
of an arbitrary number of groups. A call to DirectProduct(G1, G2, …, Gn) is generally
expected to be faster than a call to G1*G2*…*Gn (and thus the need for this algorithm).
See also:
__mul__

Examples

>>> from sympy.combinatorics.group_constructs import DirectProduct

>>> from sympy.combinatorics.named_groups import CyclicGroup
>>> C = CyclicGroup(4)
>>> G = DirectProduct(C, C, C)
>>> G.order()
64

Test Utilities

sympy.combinatorics.testutil._cmp_perm_lists(first, second)
Compare two lists of permutations as sets.
This is used for testing purposes. Since the array form of a permutation is currently a
list, Permutation is not hashable and cannot be put into a set.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.testutil import _cmp_perm_lists
>>> a = Permutation([0, 2, 3, 4, 1])
>>> b = Permutation([1, 2, 0, 4, 3])
>>> c = Permutation([3, 4, 0, 1, 2])
>>> ls1 = [a, b, c]
>>> ls2 = [b, c, a]
>>> _cmp_perm_lists(ls1, ls2)
True

sympy.combinatorics.testutil._naive_list_centralizer(self, other, af=False)

sympy.combinatorics.testutil._verify_bsgs(group, base, gens)
Verify the correctness of a base and strong generating set.
This is a naive implementation using the definition of a base and a strong generating set
relative to it. There are other procedures for verifying a base and strong generating set,
but this one will serve for more robust testing.
See also:
sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims (page 261)

294 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.combinatorics.named_groups import AlternatingGroup

>>> from sympy.combinatorics.testutil import _verify_bsgs
>>> A = AlternatingGroup(4)
>>> A.schreier_sims()
>>> _verify_bsgs(A, A.base, A.strong_gens)
True

sympy.combinatorics.testutil._verify_centralizer(group, arg, centr=None)

Verify the centralizer of a group/set/element inside another group.
This is used for testing .centralizer() from sympy.combinatorics.perm_groups
See also:
_naive_list_centralizer (page 294), sympy.combinatorics.perm_groups.
PermutationGroup.centralizer (page 243), _cmp_perm_lists (page 294)

Examples

>>> from sympy.combinatorics.named_groups import (SymmetricGroup,

... AlternatingGroup)
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.permutations import Permutation
>>> from sympy.combinatorics.testutil import _verify_centralizer
>>> S = SymmetricGroup(5)
>>> A = AlternatingGroup(5)
>>> centr = PermutationGroup([Permutation([0, 1, 2, 3, 4])])
>>> _verify_centralizer(S, A, centr)
True

sympy.combinatorics.testutil._verify_normal_closure(group, arg, clo-

sure=None)

Tensor Canonicalization

sympy.combinatorics.tensor_can.canonicalize(g, dummies, msym, *v)

canonicalize tensor formed by tensors
Parameters g : permutation representing the tensor
dummies : list representing the dummy indices
it can be a list of dummy indices of the same type or a list of lists of
dummy indices, one list for each type of index; the dummy indices
must come after the free indices, and put in order contravariant, co-
variant [d0, -d0, d1,-d1,…]
msym : symmetry of the metric(s)
it can be an integer or a list; in the first case it is the symmetry of the
dummy index metric; in the second case it is the list of the symmetries
of the index metric for each type
v : list, (base_i, gens_i, n_i, sym_i) for tensors of type i
base_i, gens_i : BSGS for tensors of this type.

5.2. Combinatorics Module 295

SymPy Documentation, Release 1.3

The BSGS should have minimal base under lexicographic ordering; if

not, an attempt is made do get the minimal BSGS; in case of failure,
canonicalize_naive is used, which is much slower.
n_i : number of tensors of type i.
sym_i : symmetry under exchange of component tensors of type i.
Both for msym and sym_i the cases are
• None no symmetry
• 0 commuting
• 1 anticommuting
Returns 0 if the tensor is zero, else return the array form of
the permutation representing the canonical form of the tensor.

Examples

one type of index with commuting metric;

Aab and Bab antisymmetric and commuting
T = Ad0d1 ∗ B d0 d2 ∗ B d2d1
ord = [d0, −d0, d1, −d1, d2, −d2] order of the indices
g = [1, 3, 0, 5, 4, 2, 6, 7]
Tc = 0

>>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs,␣

,→canonicalize, bsgs_direct_product

>>> from sympy.combinatorics import Permutation

>>> base2a, gens2a = get_symmetric_group_sgs(2, 1)
>>> t0 = (base2a, gens2a, 1, 0)
>>> t1 = (base2a, gens2a, 2, 0)
>>> g = Permutation([1, 3, 0, 5, 4, 2, 6, 7])
>>> canonicalize(g, range(6), 0, t0, t1)
0

same as above, but with Bab anticommuting

Tc = −Ad0d1 ∗ Bd0 d2 ∗ Bd1d2
can = [0,2,1,4,3,5,7,6]

>>> t1 = (base2a, gens2a, 2, 1)

>>> canonicalize(g, range(6), 0, t0, t1)
[0, 2, 1, 4, 3, 5, 7, 6]

two types of indices [a, b, c, d, e, f ] and [m, n], in this order, both with commuting metric
f abc antisymmetric, commuting
Ama no symmetry, commuting
T = f c da ∗ f f eb ∗ Am d ∗ Amb ∗ An a ∗ Ane
ord = [c,f,a,-a,b,-b,d,-d,e,-e,m,-m,n,-n]

296 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

g = [0,7,3, 1,9,5, 11,6, 10,4, 13,2, 12,8, 14,15]

The canonical tensor is Tc = −f cab ∗ f f de ∗ Am a ∗ Amd ∗ An b ∗ Ane
can = [0,2,4, 1,6,8, 10,3, 11,7, 12,5, 13,9, 15,14]

>>> base_f, gens_f = get_symmetric_group_sgs(3, 1)

>>> base1, gens1 = get_symmetric_group_sgs(1)
>>> base_A, gens_A = bsgs_direct_product(base1, gens1, base1, gens1)
>>> t0 = (base_f, gens_f, 2, 0)
>>> t1 = (base_A, gens_A, 4, 0)
>>> dummies = [range(2, 10), range(10, 14)]
>>> g = Permutation([0, 7, 3, 1, 9, 5, 11, 6, 10, 4, 13, 2, 12, 8, 14, 15])
>>> canonicalize(g, dummies, [0, 0], t0, t1)
[0, 2, 4, 1, 6, 8, 10, 3, 11, 7, 12, 5, 13, 9, 15, 14]

Algorithm

First one uses canonical_free to get the minimum tensor under lexicographic order, us-
ing only the slot symmetries. If the component tensors have not minimal BSGS, it is
attempted to find it; if the attempt fails canonicalize_naive is used instead.
Compute the residual slot symmetry keeping fixed the free indices using ten-
sor_gens(base, gens, list_free_indices, sym).
Reduce the problem eliminating the free indices.
Then use double_coset_can_rep and lift back the result reintroducing the free indices.
sympy.combinatorics.tensor_can.double_coset_can_rep(dummies, sym, b_S,
sgens, S_transversals, g)
Butler-Portugal algorithm for tensor canonicalization with dummy indices
dummies list of lists of dummy indices, one list for each type of index; the
dummy indices are put in order contravariant, covariant [d0, -d0, d1, -d1,
…].
sym list of the symmetries of the index metric for each type.
possible symmetries of the metrics
• 0 symmetric
• 1 antisymmetric
• None no symmetry
b_S base of a minimal slot symmetry BSGS.
sgens generators of the slot symmetry BSGS.
S_transversals transversals for the slot BSGS.
g permutation representing the tensor.
Return 0 if the tensor is zero, else return the array form of the permutation representing
the canonical form of the tensor.
A tensor with dummy indices can be represented in a number of equivalent ways which
typically grows exponentially with the number of indices. To be able to establish if two
tensors with many indices are equal becomes computationally very slow in absence of
an efficient algorithm.

5.2. Combinatorics Module 297

SymPy Documentation, Release 1.3

The Butler-Portugal algorithm [3] is an efficient algorithm to put tensors in canonical

form, solving the above problem.
Portugal observed that a tensor can be represented by a permutation, and that the class
of tensors equivalent to it under slot and dummy symmetries is equivalent to the double
coset D ∗ g ∗ S (Note: in this documentation we use the conventions for multiplication
of permutations p, q with (p*q)(i) = p[q[i]] which is opposite to the one used in the
Permutation class)
Using the algorithm by Butler to find a representative of the double coset one can find a
canonical form for the tensor.
To see this correspondence, let g be a permutation in array form; a tensor with indices
ind (the indices including both the contravariant and the covariant ones) can be written
as
t = T (ind[g[0], ..., ind[g[n − 1]]),
where n = len(ind); g has size n + 2, the last two indices for the sign of the tensor (trick
introduced in [4]).
A slot symmetry transformation s is a permutation acting on the slots t− > T (ind[(g ∗
s)[0]], ..., ind[(g ∗ s)[n − 1]])
A dummy symmetry transformation acts on ind t− > T (ind[(d ∗ g)[0]], ..., ind[(d ∗ g)[n − 1]])
Being interested only in the transformations of the tensor under these symmetries, one
can represent the tensor by g, which transforms as
g− > d ∗ g ∗ s, so it belongs to the coset D ∗ g ∗ S.
Let us explain the conventions by an example.
Given a tensor T d3d2d1 d1d2d3 with the slot symmetries T a0a1a2a3a4a5 = −T a2a1a0a3a4a5
T a0a1a2a3a4a5 = −T a4a1a2a3a0a5
and symmetric metric, find the tensor equivalent to it which is the lowest under the
ordering of indices: lexicographic ordering d1, d2, d3 then and contravariant index before
covariant index; that is the canonical form of the tensor.
The canonical form is −T d1d2d3 d1d2d3 obtained using T a0a1a2a3a4a5 = −T a2a1a0a3a4a5 .
To convert this problem in the input for this function, use the following labelling of the
index names (- for covariant for short) d1, −d1, d2, −d2, d3, −d3
T d3d2d1 d1d2d3 corresponds to g = [4, 2, 0, 1, 3, 5, 6, 7] where the last two indices are for the sign
sgens = [P ermutation(0, 2)(6, 7), P ermutation(0, 4)(6, 7)]
sgens[0] is the slot symmetry −(0, 2) T a0a1a2a3a4a5 = −T a2a1a0a3a4a5
sgens[1] is the slot symmetry −(0, 4) T a0a1a2a3a4a5 = −T a4a1a2a3a0a5
The dummy symmetry group D is generated by the strong base generators
[(0, 1), (2, 3), (4, 5), (0, 1)(2, 3), (2, 3)(4, 5)]
The dummy symmetry acts from the left d = [1, 0, 2, 3, 4, 5, 6, 7] exchange d1− > −d1
T d3d2d1 d1d2d3 == T d3d2 d1 d1 d2d3
g = [4, 2, 0, 1, 3, 5, 6, 7]− > [4, 2, 1, 0, 3, 5, 6, 7] =a fr mul(d, g) which differs from a fr mul(g, d).
The slot symmetry acts from the right s = [2, 1, 0, 3, 4, 5, 7, 6] exchanges slots 0 and 2 and
changes sign T d3d2d1 d1d2d3 == −T d1d2d3 d1d2d3
g = [4, 2, 0, 1, 3, 5, 6, 7]− > [0, 2, 4, 1, 3, 5, 7, 6] =a fr mul(g, s)

298 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Example in which the tensor is zero, same slot symmetries as above: T d3 d1,d2 d1 d3 d2
= −T d3 d1,d3 d1 d2 d2 under slot symmetry −(2, 4);
= Td3d1 d3d1 d2 d2 under slot symmetry −(0, 2);
= T d3 d1d3 d1 d2 d2 symmetric metric;
= 0 since two of these lines have tensors differ only for the sign.
The double coset D*g*S consists of permutations h = d ∗ g ∗ s corresponding to equivalent
tensors; if there are two h which are the same apart from the sign, return zero; otherwise
choose as representative the tensor with indices ordered lexicographically according to
[d1, −d1, d2, −d2, d3, −d3] that is rep = min(D ∗ g ∗ S) = min([d ∗ g ∗ sf ordinDf orsinS])
The indices are fixed one by one; first choose the lowest index for slot 0, then the lowest
remaining index for slot 1, etc. Doing this one obtains a chain of stabilizers
S− > Sb0 − > Sb0,b1 − > ... and D− > Dp0 − > Dp0,p1 − > ...
where [b0, b1, ...] = range(b) is a base of the symmetric group; the strong base bS of S is an
ordered sublist of it; therefore it is sufficient to compute once the strong base generators
of S using the Schreier-Sims algorithm; the stabilizers of the strong base generators are
the strong base generators of the stabilizer subgroup.
dbase = [p0, p1, ...] is not in general in lexicographic order, so that one must recompute
the strong base generators each time; however this is trivial, there is no need to use the
Schreier-Sims algorithm for D.
The algorithm keeps a TAB of elements (si , di , hi ) where hi = di ∗ g ∗ si satisfying hi [j] = pj
for 0 <= j < i starting from s0 = id, d0 = id, h0 = g.
The equations h0 [0] = p0 , h1 [1] = p1 , ... are solved in this order, choosing each time the
lowest possible value of p_i
For j < i di ∗ g ∗ si ∗ Sb0 ,...,bi−1 ∗ bj = Dp0 ,...,pi−1 ∗ pj so that for dx in Dp0 ,...,pi−1 and sx in
Sbase[0],...,base[i−1] one has dx ∗ di ∗ g ∗ si ∗ sx ∗ bj = pj
Search for dx, sx such that this equation holds for j = i; it can be written as si ∗ sx ∗ bj =
J, dx ∗ di ∗ g ∗ J = pj sx ∗ bj = si ∗ ∗ − 1 ∗ J; sx = trace(si ∗ ∗ − 1, Sb0 ,...,bi−1 ) dx ∗ ∗ − 1 ∗ pj = di ∗ g ∗ J; dx =
trace(di ∗ g ∗ J, Dp0 ,...,pi−1 )
si+1 = si ∗ trace(si ∗ ∗ − 1 ∗ J, Sb0 ,...,bi−1 ) di+1 = trace(di ∗ g ∗ J, Dp0 ,...,pi−1 ) ∗ ∗ − 1 ∗ di hi+1 ∗ bi =
di+1 ∗ g ∗ si+1 ∗ bi = pi
hn ∗ bj = pj for all j, so that hn is the solution.
Add the found (s, d, h) to TAB1.
At the end of the iteration sort TAB1 with respect to the h; if there are two consecutive
h in TAB1 which differ only for the sign, the tensor is zero, so return 0; if there are two
consecutive h which are equal, keep only one.
Then stabilize the slot generators under i and the dummy generators under pi .
Assign T AB = T AB1 at the end of the iteration step.
At the end T AB contains a unique (s, d, h), since all the slots of the tensor h have been
fixed to have the minimum value according to the symmetries. The algorithm returns h.
It is important that the slot BSGS has lexicographic minimal base, otherwise there is an
i which does not belong to the slot base for which pi is fixed by the dummy symmetry
only, while i is not invariant from the slot stabilizer, so pi is not in general the minimal
value.

5.2. Combinatorics Module 299

SymPy Documentation, Release 1.3

This algorithm differs slightly from the original algorithm [3]: the canonical
form is minimal lexicographically, and the BSGS has minimal base under lexico-
graphic order. Equal tensors h are eliminated from TAB.

Examples

>>> from sympy.combinatorics.permutations import Permutation

>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.tensor_can import double_coset_can_rep, get_
,→transversals

>>> gens = [Permutation(x) for x in [[2, 1, 0, 3, 4, 5, 7, 6], [4, 1, 2, 3, 0, 5,␣

,→7, 6]]]

>>> base = [0, 2]

>>> g = Permutation([4, 2, 0, 1, 3, 5, 6, 7])
>>> transversals = get_transversals(base, gens)
>>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g)
[0, 1, 2, 3, 4, 5, 7, 6]

>>> g = Permutation([4, 1, 3, 0, 5, 2, 6, 7])

>>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g)
0

sympy.combinatorics.tensor_can.get_symmetric_group_sgs(n, antisym=False)
Return base, gens of the minimal BSGS for (anti)symmetric tensor
n rank of the tensor
antisym = False symmetric tensor antisym = True antisymmetric tensor

Examples

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs
>>> Permutation.print_cyclic = True
>>> get_symmetric_group_sgs(3)
([0, 1], [(4)(0 1), (4)(1 2)])

sympy.combinatorics.tensor_can.bsgs_direct_product(base1, gens1, base2,

gens2, signed=True)
direct product of two BSGS
base1 base of the first BSGS.
gens1 strong generating sequence of the first BSGS.
base2, gens2 similarly for the second BSGS.
signed flag for signed permutations.

Examples

300 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.combinatorics import Permutation

>>> from sympy.combinatorics.tensor_can import (get_symmetric_group_sgs, bsgs_
,→direct_product)

>>> Permutation.print_cyclic = True

>>> base1, gens1 = get_symmetric_group_sgs(1)
>>> base2, gens2 = get_symmetric_group_sgs(2)
>>> bsgs_direct_product(base1, gens1, base2, gens2)
([1], [(4)(1 2)])

Finitely Presented Groups

Introduction

This module presents the functionality designed for computing with finitely- presented groups
(fp-groups for short). The name of the corresponding SymPy object is FpGroup. The functions
or classes described here are studied under computational group theory. All code exam-
ples assume:

>>> from sympy.combinatorics.free_groups import free_group, vfree_group, xfree_group

>>> from sympy.combinatorics.fp_groups import FpGroup, CosetTable, coset_enumeration_r

Overview of Facilities

The facilities provided for fp-groups fall into a number of natural groupings
• The construction of fp-groups using a free group and a list of words in generators of that
free group.
• Index determination using the famous Todd-Coxeter procedure.
• The construction of all subgroups having index less than some (small) specified positive
integer, using the Low-Index Subgroups algorithm.
• Algorithms for computing presentations of a subgroup of finite index in a group defined
by finite presentation.
For a description of fundamental algorithms of finitely presented groups we often make use
of Handbook of Computational Group Theory.

The Construction of Finitely Presented Groups

Finitely presented groups are constructed by factoring a free group by a set of relators. The
set of relators is taken in as a list of words in generators of free group in SymPy, using a list
provides ordering to the relators. If the list of relators is empty, the associated free group is
returned.
Example of construction of a finitely-presented group. The symmetric group of degree 4
may be represented as a two generator group with presentation ⟨a, b | a2 , b3 , (ab)4 ⟩. Giving the
relations as a list of relators, group in SymPy would be specified as:

5.2. Combinatorics Module 301

SymPy Documentation, Release 1.3

>>> F, a, b = free_group(”a, b”)

>>> G = FpGroup(F, [a**2, b**3, (a*b)**4])
>>> G
<fp group on the generators (a, b)>

Currently groups with relators having presentation like ⟨r, s, t | r2 , s2 , t2 , rst = str = trs⟩ will
have to be specified as:

>>> F, r, s, t = free_group(”r, s, t”)

>>> G = FpGroup(F, [r**2, s**2, t**2, r*s*t*r**-1*t**-1*s**-1, s*t*r*s**-1*r**-1*t**-
,→1])

Obviously this is not a unique way to make that particular group, but the point is that in case
of equality with non-identity the user has to manually do that.

Free Groups and Words

Construction of a Free Group

free_group(”gen0, gen1, ..., gen_(n-1)”) constructs a free group F on n generators,

where n is a positive integer. The i-th generator of F may be obtained using the method
.generators[i], i = 0, . . . n − 1.

>>> F, x, y = free_group(”x, y”)

creates a free group F of rank 2 and assigns the variables x and y to the two generators.

>>> F = vfree_group(”x, y”)

>>> F
<free group on the generators (x, y)>

creates a free group F of rank 2, with tuple of generators F.generators, and inserts x and y
as generators into the global namespace.

>>> F = xfree_group(”x, y”)

>>> F
(<free group on the generators (x, y)>, (x, y))
>>> x**2
x**2

creates a free groups F[0] of rank 2, with tuple of generators F[1].

Construction of words

This section is applicable to words of FreeGroup as well as FpGroup. When we say word in
SymPy, it actually means a reduced word , since the words are automatically reduced. Given
a group G defined on n generators x1 , x2 , x3 , . . . , xn , a word is constructed as sr11 sr22 · · · srkk where
si ∈ {x1 , x2 , . . . , xn } , ri ∈ Z for all k.
Each word can be constructed in a variety of ways, since after reduction they may be equiv-
alent.

302 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Coset Enumeration: The Todd-Coxeter Algorithm

This section describes the use of coset enumeration techniques in SymPy. The algorithm
used for coset enumeration procedure is Todd-Coxeter algorithm and is developed in Sympy
using [Ho05] and [CDHW73]. The reader should consult [CDHW73] and [Hav91] for a general
description of the algorithm.
We have two strategies of coset enumeration relator-based and coset-table based and the two
have been implemented as coset_enumeration_r, coset_enumeration_c respectively. The
two strategies differ in the way they make new definitions for the cosets.
Though from the user point of view it is suggested to rather use the .coset_enumeration
method of FpGroup and specify the strategy argument.
strategy: (default=”relator_based”) specifies the strategy of coset enumeration to be used,
possible values are “relator_based” or “coset_table_based”.

CosetTable

Class used to manipulate the information regarding the coset enumeration of the finitely
presented group G on the cosets of the subgroup H.
Basically a coset table CosetTable(G,H), is the permutation representation of the finitely
presented group on the cosets of a subgroup. Most of the set theoretic and group functions
use the regular representation of G, i.e., the coset table of G over the trivial subgroup.
The actual mathematical coset table is obtained using .table attribute and is a list of lists.
For each generator g of G it contains a column and the next column corresponds to g**-1 and
so on for other generators, so in total it has 2*G.rank() columns. Each column is simply a
list of integers. If l is the generator list for the generator g and if l[i] = j then generator g
takes the coset i to the coset j by multiplication from the right.
For finitely presented groups, a coset table is computed by a Todd-Coxeter coset enumeration.
Note that you may influence the performance of that enumeration by changing the values of
the variable CosetTable.coset_table_max_limit.

Attributes of CosetTable

For CosetTable(G, H) where G is the group and H is the subgroup.

• n: A non-negative integer, non-mutable attribute, dependently calculated as the maxi-
mum among the live-cosets (i.e. Ω).
• table: A list of lists, mutable attribute, mathematically represents the coset table.
• omega: A list, dependent on the internal attribute p. Ω represents the list of live-cosets.
A standard coset-table has its Ω = {0, 1, . . . , index − 1} where index is the index of subgroup
H in G.
For experienced users we have a number of parameters that can be used to manipulate the
algorithm, like
• coset_table_max_limit (default value = 4096000): manipulate the maximum number of
cosets allowed in coset enumeration, i.e. the number of rows allowed in coset table. A
coset enumeration will not finish if the subgroup does not have finite index, and even if
it has it may take many more intermediate cosets than the actual index of the subgroup
is. To avoid a coset enumeration “running away” therefore SymPy has a “safety stop”

5.2. Combinatorics Module 303

SymPy Documentation, Release 1.3

built-in. This is controlled by this variable. To change it, use maxc osets keyword. For
example:

>>> F, a, b = free_group(”a, b”)

>>> Cox = FpGroup(F, [a**6, b**6, (a*b)**2, (a**2*b**2)**2, (a**3*b**3)**5])
>>> C_r = coset_enumeration_r(Cox, [a], max_cosets=50)
Traceback (most recent call last):
...
ValueError: the coset enumeration has defined more than 50 cosets

• max_stack_size (default value = 500): manipulate the maximum size of deduc-

tion_stack above or equal to which the stack is emptied.

Compression and Standardization

For any two entries i, j with i < j in coset table, the first occurrence of i in a coset table
precedes the first occurrence of j with respect to the usual row-wise ordering of the table
entries. We call such a table a standard coset table. To standardize a CosetTable we use the
.standardize method.
Note the method alters the given table, it does not create a copy.

Subgroups of Finite Index

The functionality in this section are concerned with the construction of subgroups of finite
index. We describe a method for computing all subgroups whose index does not exceed some
(modest) integer bound.

Low Index Subgroups

low_index_subgroups(G, N): Given a finitely presented group G = ⟨X | R⟩ (can be a free

group), and N a positive integer, determine the conjugacy classes of subgroups of G whose
indices is less than or equal to N.
For example to find all subgroups of G = ⟨a, b | a2 = b3 = (ab)4 = 1⟩ having index <= 4, can be
found as follows:

>>> from sympy.combinatorics.fp_groups import low_index_subgroups

>>> F, a, b = free_group(”a, b”)
>>> G = FpGroup(F, [a**2, b**3, (a*b)**4])
>>> l = low_index_subgroups(G, 4)
>>> for coset_table in l:
... print(coset_table.table)
...
[[0, 0, 0, 0]]
[[0, 0, 1, 2], [1, 1, 2, 0], [3, 3, 0, 1], [2, 2, 3, 3]]
[[0, 0, 1, 2], [2, 2, 2, 0], [1, 1, 0, 1]]
[[1, 1, 0, 0], [0, 0, 1, 1]]

This returns the coset tables of subgroups of satisfying the property that index, index, of
subgroup in group is ≤ n.

304 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Constructing a presentation for a subgroup

In this section we discuss finding the presentation of a subgroup in a finitely presentation

group. While the subgroup is currently allowed as input only in the form of a list of generators
for the subgroup, you can expect the functionality of a coset table as input for subgroup in
the group in near future.
There are two ways to construct a set of defining relations for subgroup from those of G. First
is on a set of Schreier generators, known generally as Reidemeister-Schreier algorithm or on
the given list of generators of H.

Reidemeister Schreier algorithm

called using reidemeister_presentation(G, Y) where G is the group and Y is a list of gen-

erators for subgroup H whose presentation we want to find.

>>> from sympy.combinatorics.fp_groups import reidemeister_presentation

>>> F, x, y = free_group(”x, y”)
>>> f = FpGroup(F, [x**3, y**5, (x*y)**2])
>>> H = [x*y, x**-1*y**-1*x*y*x]
>>> p1 = reidemeister_presentation(f, H)
>>> p1
((y_1, y_2), (y_1**2, y_2**3, y_2*y_1*y_2*y_1*y_2*y_1))

Bibliography

5.3 Number Theory

5.3.1 Ntheory Class Reference

class sympy.ntheory.generate.Sieve
An infinite list of prime numbers, implemented as a dynamically growing sieve of Eratos-
thenes. When a lookup is requested involving an odd number that has not been sieved,
the sieve is automatically extended up to that number.

Examples

>>> from sympy import sieve

>>> sieve._reset() # this line for doctest only
>>> 25 in sieve
False
>>> sieve._list
array('l', [2, 3, 5, 7, 11, 13, 17, 19, 23])

extend(n)
Grow the sieve to cover all primes <= n (a real number).

5.3. Number Theory 305

SymPy Documentation, Release 1.3

Examples

>>> from sympy import sieve

>>> sieve._reset() # this line for doctest only
>>> sieve.extend(30)
>>> sieve[10] == 29
True

extend_to_no(i)
Extend to include the ith prime number.
i must be an integer.
The list is extended by 50% if it is too short, so it is likely that it will be longer than
requested.

Examples

>>> from sympy import sieve

>>> sieve._reset() # this line for doctest only
>>> sieve.extend_to_no(9)
>>> sieve._list
array('l', [2, 3, 5, 7, 11, 13, 17, 19, 23])

mobiusrange(a, b)
Generate all mobius numbers for the range [a, b).

Examples

>>> from sympy import sieve

>>> print([i for i in sieve.mobiusrange(7, 18)])
[-1, 0, 0, 1, -1, 0, -1, 1, 1, 0, -1]

primerange(a, b)
Generate all prime numbers in the range [a, b).

Examples

>>> from sympy import sieve

>>> print([i for i in sieve.primerange(7, 18)])
[7, 11, 13, 17]

search(n)
Return the indices i, j of the primes that bound n.
If n is prime then i == j.
Although n can be an expression, if ceiling cannot convert it to an integer then an n
error will be raised.

306 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import sieve

>>> sieve.search(25)
(9, 10)
>>> sieve.search(23)
(9, 9)

totientrange(a, b)
Generate all totient numbers for the range [a, b).

Examples

>>> from sympy import sieve

>>> print([i for i in sieve.totientrange(7, 18)])
[6, 4, 6, 4, 10, 4, 12, 6, 8, 8, 16]

5.3.2 Ntheory Functions Reference

sympy.ntheory.generate.prime(nth)
Return the nth prime, with the primes indexed as prime(1) = 2, prime(2) = 3, etc…. The
nth prime is approximately n*log(n).
Logarithmic integral of x is a pretty nice approximation for number of primes <= x, i.e.
li(x) ~ pi(x) In fact, for the numbers we are concerned about( x<1e11 ), li(x) - pi(x) <
50000
Also, li(x) > pi(x) can be safely assumed for the numbers which can be evaluated by this
function.
Here, we find the least integer m such that li(m) > n using binary search. Now pi(m-1)
< li(m-1) <= n,
We find pi(m - 1) using primepi function.
Starting from m, we have to find n - pi(m-1) more primes.
For the inputs this implementation can handle, we will have to test primality for at max
about 10**5 numbers, to get our answer.
See also:

sympy.ntheory.primetest.isprime (page 333) Test if n is prime

primerange (page 309) Generate all primes in a given range
primepi (page 308) Return the number of primes less than or equal to n

References

• https://en.wikipedia.org/wiki/Prime_number_theorem#Table_of_.CF.80.28x.29.2C_
x_.2F_log_x.2C_and_li.28x.29
• https://en.wikipedia.org/wiki/Prime_number_theorem#Approximations_for_the_
nth_prime_number

5.3. Number Theory 307

SymPy Documentation, Release 1.3

• https://en.wikipedia.org/wiki/Skewes%27_number

Examples

>>> from sympy import prime

>>> prime(10)
29
>>> prime(1)
2
>>> prime(100000)
1299709

sympy.ntheory.generate.primepi(n)
Return the value of the prime counting function pi(n) = the number of prime numbers
less than or equal to n.
Algorithm Description:
In sieve method, we remove all multiples of prime p except p itself.
Let phi(i,j) be the number of integers 2 <= k <= i which remain after sieving from primes
less than or equal to j. Clearly, pi(n) = phi(n, sqrt(n))
If j is not a prime, phi(i,j) = phi(i, j - 1)
if j is a prime, We remove all numbers(except j) whose smallest prime factor is j.
Let x= j*a be such a number, where 2 <= a<= i / j Now, after sieving from primes <= j
- 1, a must remain (because x, and hence a has no prime factor <= j - 1) Clearly, there
are phi(i / j, j - 1) such a which remain on sieving from primes <= j - 1
Now, if a is a prime less than equal to j - 1, x= j*a has smallest prime factor = a, and has
already been removed(by sieving from a). So, we don’t need to remove it again. (Note:
there will be pi(j - 1) such x)
Thus, number of x, that will be removed are: phi(i / j, j - 1) - phi(j - 1, j - 1) (Note that pi(j
- 1) = phi(j - 1, j - 1))
=> phi(i,j) = phi(i, j - 1) - phi(i / j, j - 1) + phi(j - 1, j - 1)
So,following recursion is used and implemented as dp:
phi(a, b) = phi(a, b - 1), if b is not a prime phi(a, b) = phi(a, b-1)-phi(a / b, b-1) + phi(b-1,
b-1), if b is prime
Clearly a is always of the form floor(n / k), which can take at most 2*sqrt(n) values. Two
arrays arr1,arr2 are maintained arr1[i] = phi(i, j), arr2[i] = phi(n // i, j)
Finally the answer is arr2[1]
See also:

sympy.ntheory.primetest.isprime (page 333) Test if n is prime

primerange (page 309) Generate all primes in a given range
prime (page 307) Return the nth prime

308 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import primepi

>>> primepi(25)
9

sympy.ntheory.generate.nextprime(n, ith=1)
Return the ith prime greater than n.
i must be an integer.
See also:

prevprime (page 309) Return the largest prime smaller than n

primerange (page 309) Generate all primes in a given range

Notes

Potential primes are located at 6*j +/- 1. This property is used during searching.

>>> from sympy import nextprime

>>> [(i, nextprime(i)) for i in range(10, 15)]
[(10, 11), (11, 13), (12, 13), (13, 17), (14, 17)]
>>> nextprime(2, ith=2) # the 2nd prime after 2
5

sympy.ntheory.generate.prevprime(n)
Return the largest prime smaller than n.
See also:

nextprime (page 309) Return the ith prime greater than n

primerange (page 309) Generates all primes in a given range

Notes

Potential primes are located at 6*j +/- 1. This property is used during searching.

>>> from sympy import prevprime

>>> [(i, prevprime(i)) for i in range(10, 15)]
[(10, 7), (11, 7), (12, 11), (13, 11), (14, 13)]

sympy.ntheory.generate.primerange(a, b)
Generate a list of all prime numbers in the range [a, b).
If the range exists in the default sieve, the values will be returned from there; otherwise
values will be returned but will not modify the sieve.
See also:

nextprime (page 309) Return the ith prime greater than n

prevprime (page 309) Return the largest prime smaller than n
randprime (page 310) Returns a random prime in a given range

5.3. Number Theory 309

SymPy Documentation, Release 1.3

primorial (page 311) Returns the product of primes based on condition

Sieve.primerange (page 306) return range from already computed primes or extend
the sieve to contain the requested range.

Notes

Some famous conjectures about the occurrence of primes in a given range are [1]:
• Twin primes: though often not, the following will give 2 primes
an infinite number of times: primerange(6*n - 1, 6*n + 2)
• Legendre’s: the following always yields at least one prime primerange(n**2,
(n+1)**2+1)
• Bertrand’s (proven): there is always a prime in the range primerange(n,
2*n)
• Brocard’s: there are at least four primes in the range
primerange(prime(n)**2, prime(n+1)**2)
The average gap between primes is log(n) [2]; the gap between primes can be arbitrarily
large since sequences of composite numbers are arbitrarily large, e.g. the numbers in
the sequence n! + 2, n! + 3 … n! + n are all composite.

References

1. http://en.wikipedia.org/wiki/Prime_number
2. http://primes.utm.edu/notes/gaps.html

Examples

>>> from sympy import primerange, sieve

>>> print([i for i in primerange(1, 30)])
[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

The Sieve method, primerange, is generally faster but it will occupy more memory as
the sieve stores values. The default instance of Sieve, named sieve, can be used:

>>> list(sieve.primerange(1, 30))

[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

sympy.ntheory.generate.randprime(a, b)
Return a random prime number in the range [a, b).
Bertrand’s postulate assures that randprime(a, 2*a) will always succeed for a > 1.
See also:

primerange (page 309) Generate all primes in a given range

310 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

• http://en.wikipedia.org/wiki/Bertrand’s_postulate

Examples

>>> from sympy import randprime, isprime

>>> randprime(1, 30) #doctest: +SKIP
13
>>> isprime(randprime(1, 30))
True

sympy.ntheory.generate.primorial(n, nth=True)
Returns the product of the first n primes (default) or the primes less than or equal to n
(when nth=False).

>>> from sympy.ntheory.generate import primorial, randprime, primerange

>>> from sympy import factorint, Mul, primefactors, sqrt
>>> primorial(4) # the first 4 primes are 2, 3, 5, 7
210
>>> primorial(4, nth=False) # primes <= 4 are 2 and 3
6
>>> primorial(1)
2
>>> primorial(1, nth=False)
1
>>> primorial(sqrt(101), nth=False)
210

One can argue that the primes are infinite since if you take a set of primes and multiply
them together (e.g. the primorial) and then add or subtract 1, the result cannot be
divided by any of the original factors, hence either 1 or more new primes must divide
this product of primes.
In this case, the number itself is a new prime:

>>> factorint(primorial(4) + 1)
{211: 1}

In this case two new primes are the factors:

>>> factorint(primorial(4) - 1)
{11: 1, 19: 1}

Here, some primes smaller and larger than the primes multiplied together are obtained:

>>> p = list(primerange(10, 20))

>>> sorted(set(primefactors(Mul(*p) + 1)).difference(set(p)))
[2, 5, 31, 149]

See also:

primerange (page 309) Generate all primes in a given range

sympy.ntheory.generate.cycle_length(f, x0, nmax=None, values=False)

For a given iterated sequence, return a generator that gives the length of the iterated

5.3. Number Theory 311

SymPy Documentation, Release 1.3

cycle (lambda) and the length of terms before the cycle begins (mu); if values is True
then the terms of the sequence will be returned instead. The sequence is started with
value x0.
Note: more than the first lambda + mu terms may be returned and this is the cost of
cycle detection with Brent’s method; there are, however, generally less terms calculated
than would have been calculated if the proper ending point were determined, e.g. by
using Floyd’s method.

>>> from sympy.ntheory.generate import cycle_length

This will yield successive values of i <– func(i):

>>> def iter(func, i):

... while 1:
... ii = func(i)
... yield ii
... i = ii
...

A function is defined:

>>> func = lambda i: (i**2 + 1) % 51

and given a seed of 4 and the mu and lambda terms calculated:

>>> next(cycle_length(func, 4))

(6, 2)

We can see what is meant by looking at the output:

>>> n = cycle_length(func, 4, values=True)

>>> list(ni for ni in n)
[17, 35, 2, 5, 26, 14, 44, 50, 2, 5, 26, 14]

There are 6 repeating values after the first 2.

If a sequence is suspected of being longer than you might wish, nmax can be used to exit
early (and mu will be returned as None):

>>> next(cycle_length(func, 4, nmax = 4))

(4, None)
>>> [ni for ni in cycle_length(func, 4, nmax = 4, values=True)]
[17, 35, 2, 5]

Code modified from: http://en.wikipedia.org/wiki/Cycle_detection.

sympy.ntheory.generate.composite(nth)
Return the nth composite number, with the composite numbers indexed as composite(1)
= 4, composite(2) = 6, etc….
See also:

sympy.ntheory.primetest.isprime (page 333) Test if n is prime

primerange (page 309) Generate all primes in a given range
primepi (page 308) Return the number of primes less than or equal to n

312 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

prime (page 307) Return the nth prime

compositepi (page 313) Return the number of positive composite numbers less than
or equal to n

Examples

>>> from sympy import composite

>>> composite(36)
52
>>> composite(1)
4
>>> composite(17737)
20000

sympy.ntheory.generate.compositepi(n)
Return the number of positive composite numbers less than or equal to n. The first
positive composite is 4, i.e. compositepi(4) = 1.
See also:

sympy.ntheory.primetest.isprime (page 333) Test if n is prime

primerange (page 309) Generate all primes in a given range
prime (page 307) Return the nth prime
primepi (page 308) Return the number of primes less than or equal to n
composite (page 312) Return the nth composite number

Examples

>>> from sympy import compositepi

>>> compositepi(25)
15
>>> compositepi(1000)
831

sympy.ntheory.factor_.smoothness(n)
Return the B-smooth and B-power smooth values of n.
The smoothness of n is the largest prime factor of n; the power- smoothness is the largest
divisor raised to its multiplicity.

>>> from sympy.ntheory.factor_ import smoothness

>>> smoothness(2**7*3**2)
(3, 128)
>>> smoothness(2**4*13)
(13, 16)
>>> smoothness(2)
(2, 2)

See also:
factorint (page 319), smoothness_p (page 313)

5.3. Number Theory 313

SymPy Documentation, Release 1.3

sympy.ntheory.factor_.smoothness_p(n, m=-1, power=0, visual=None)

Return a list of [m, (p, (M, sm(p + m), psm(p + m)))…] where:
1. p**M is the base-p divisor of n
2. sm(p + m) is the smoothness of p + m (m = -1 by default)
3. psm(p + m) is the power smoothness of p + m
The list is sorted according to smoothness (default) or by power smoothness if power=1.
The smoothness of the numbers to the left (m = -1) or right (m = 1) of a factor govern
the results that are obtained from the p +/- 1 type factoring methods.

>>> from sympy.ntheory.factor_ import smoothness_p, factorint

>>> smoothness_p(10431, m=1)
(1, [(3, (2, 2, 4)), (19, (1, 5, 5)), (61, (1, 31, 31))])
>>> smoothness_p(10431)
(-1, [(3, (2, 2, 2)), (19, (1, 3, 9)), (61, (1, 5, 5))])
>>> smoothness_p(10431, power=1)
(-1, [(3, (2, 2, 2)), (61, (1, 5, 5)), (19, (1, 3, 9))])

If visual=True then an annotated string will be returned:

>>> print(smoothness_p(21477639576571, visual=1))

p**i=4410317**1 has p-1 B=1787, B-pow=1787
p**i=4869863**1 has p-1 B=2434931, B-pow=2434931

This string can also be generated directly from a factorization dictionary and vice versa:

>>> factorint(17*9)
{3: 2, 17: 1}
>>> smoothness_p(_)
'p**i=3**2 has p-1 B=2, B-pow=2\np**i=17**1 has p-1 B=2, B-pow=16'
>>> smoothness_p(_)
{3: 2, 17: 1}

The table of the output logic is:

Visual

Input True False other

dict str tuple str
str str tuple dict
tuple str tuple str
n str tuple tuple
mul str tuple tuple

See also:
factorint (page 319), smoothness (page 313)
sympy.ntheory.factor_.trailing(n)
Count the number of trailing zero digits in the binary representation of n, i.e. determine
the largest power of 2 that divides n.

314 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import trailing

>>> trailing(128)
7
>>> trailing(63)
0

sympy.ntheory.factor_.multiplicity(p, n)
Find the greatest integer m such that p**m divides n.

Examples

>>> from sympy.ntheory import multiplicity

>>> from sympy.core.numbers import Rational as R
>>> [multiplicity(5, n) for n in [8, 5, 25, 125, 250]]
[0, 1, 2, 3, 3]
>>> multiplicity(3, R(1, 9))
-2

sympy.ntheory.factor_.perfect_power(n, candidates=None, big=True, fac-

tor=True)
Return (b, e) such that n == b**e if n is a perfect power; otherwise return False.
By default, the base is recursively decomposed and the exponents collected so the largest
possible e is sought. If big=False then the smallest possible e (thus prime) will be
chosen.
If candidates for exponents are given, they are assumed to be sorted and the first one
that is larger than the computed maximum will signal failure for the routine.
If factor=True then simultaneous factorization of n is attempted since finding a factor
indicates the only possible root for n. This is True by default since only a few small
factors will be tested in the course of searching for the perfect power.

Examples

>>> from sympy import perfect_power

>>> perfect_power(16)
(2, 4)
>>> perfect_power(16, big = False)
(4, 2)

sympy.ntheory.factor_.pollard_rho(n, s=2, a=1, retries=5, seed=1234,

max_steps=None, F=None)
Use Pollard’s rho method to try to extract a nontrivial factor of n. The returned factor
may be a composite number. If no factor is found, None is returned.
The algorithm generates pseudo-random values of x with a generator function, replacing
x with F(x). If F is not supplied then the function x**2 + a is used. The first value supplied
to F(x) is s. Upon failure (if retries is > 0) a new a and s will be supplied; the a will be
ignored if F was supplied.
The sequence of numbers generated by such functions generally have a a lead-up to some
number and then loop around back to that number and begin to repeat the sequence,

5.3. Number Theory 315

SymPy Documentation, Release 1.3

e.g. 1, 2, 3, 4, 5, 3, 4, 5 – this leader and loop look a bit like the Greek letter rho, and
thus the name, ‘rho’.
For a given function, very different leader-loop values can be obtained so it is a good
idea to allow for retries:

>>> from sympy.ntheory.generate import cycle_length

>>> n = 16843009
>>> F = lambda x:(2048*pow(x, 2, n) + 32767) % n
>>> for s in range(5):
... print('loop length = %4i; leader length = %3i' % next(cycle_length(F, s)))
...
loop length = 2489; leader length = 42
loop length = 78; leader length = 120
loop length = 1482; leader length = 99
loop length = 1482; leader length = 285
loop length = 1482; leader length = 100

Here is an explicit example where there is a two element leadup to a sequence of 3

numbers (11, 14, 4) that then repeat:

>>> x=2
>>> for i in range(9):
... x=(x**2+12)%17
... print(x)
...
16
13
11
14
4
11
14
4
11
>>> next(cycle_length(lambda x: (x**2+12)%17, 2))
(3, 2)
>>> list(cycle_length(lambda x: (x**2+12)%17, 2, values=True))
[16, 13, 11, 14, 4]

Instead of checking the differences of all generated values for a gcd with n, only the kth
and 2*kth numbers are checked, e.g. 1st and 2nd, 2nd and 4th, 3rd and 6th until it has
been detected that the loop has been traversed. Loops may be many thousands of steps
long before rho finds a factor or reports failure. If max_steps is specified, the iteration
is cancelled with a failure after the specified number of steps.

References

• Richard Crandall & Carl Pomerance (2005), “Prime Numbers: A Computational Per-
spective”, Springer, 2nd edition, 229-231

Examples

316 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import pollard_rho

>>> n=16843009
>>> F=lambda x:(2048*pow(x,2,n) + 32767) % n
>>> pollard_rho(n, F=F)
257

Use the default setting with a bad value of a and no retries:

>>> pollard_rho(n, a=n-2, retries=0)

If retries is > 0 then perhaps the problem will correct itself when new values are gener-
ated for a:

>>> pollard_rho(n, a=n-2, retries=1)

257

sympy.ntheory.factor_.pollard_pm1(n, B=10, a=2, retries=0, seed=1234)

Use Pollard’s p-1 method to try to extract a nontrivial factor of n. Either a divisor (per-
haps composite) or None is returned.
The value of a is the base that is used in the test gcd(a**M - 1, n). The default is 2. If
retries > 0 then if no factor is found after the first attempt, a new a will be generated
randomly (using the seed) and the process repeated.
Note: the value of M is lcm(1..B) = reduce(ilcm, range(2, B + 1)).
A search is made for factors next to even numbers having a power smoothness less than
B. Choosing a larger B increases the likelihood of finding a larger factor but takes longer.
Whether a factor of n is found or not depends on a and the power smoothness of the even
number just less than the factor p (hence the name p - 1).
Although some discussion of what constitutes a good a some descriptions are hard to
interpret. At the modular.math site referenced below it is stated that if gcd(a**M - 1, n)
= N then a**M % q**r is 1 for every prime power divisor of N. But consider the following:

>>> from sympy.ntheory.factor_ import smoothness_p, pollard_pm1

>>> n=257*1009
>>> smoothness_p(n)
(-1, [(257, (1, 2, 256)), (1009, (1, 7, 16))])

So we should (and can) find a root with B=16:

>>> pollard_pm1(n, B=16, a=3)

1009

If we attempt to increase B to 256 we find that it doesn’t work:

>>> pollard_pm1(n, B=256)

>>>

But if the value of a is changed we find that only multiples of 257 work, e.g.:

>>> pollard_pm1(n, B=256, a=257)

1009

Checking different a values shows that all the ones that didn’t work had a gcd value not
equal to n but equal to one of the factors:

5.3. Number Theory 317

SymPy Documentation, Release 1.3

>>> from sympy.core.numbers import ilcm, igcd

>>> from sympy import factorint, Pow
>>> M = 1
>>> for i in range(2, 256):
... M = ilcm(M, i)
...
>>> set([igcd(pow(a, M, n) - 1, n) for a in range(2, 256) if
... igcd(pow(a, M, n) - 1, n) != n])
{1009}

But does aM % d for every divisor of n give 1?

>>> aM = pow(255, M, n)
>>> [(d, aM%Pow(*d.args)) for d in factorint(n, visual=True).args]
[(257**1, 1), (1009**1, 1)]

No, only one of them. So perhaps the principle is that a root will be found for a given
value of B provided that:
1) the power smoothness of the p - 1 value next to the root does not exceed B
2) a**M % p != 1 for any of the divisors of n.
By trying more than one a it is possible that one of them will yield a factor.

References

• Richard Crandall & Carl Pomerance (2005), “Prime Numbers: A Computational Per-
spective”, Springer, 2nd edition, 236-238
• http://modular.math.washington.edu/edu/2007/spring/ent/ent-html/node81.html
• http://www.cs.toronto.edu/~yuvalf/Factorization.pdf

Examples

With the default smoothness bound, this number can’t be cracked:

>>> from sympy.ntheory import pollard_pm1, primefactors

>>> pollard_pm1(21477639576571)

Increasing the smoothness bound helps:

>>> pollard_pm1(21477639576571, B=2000)

4410317

Looking at the smoothness of the factors of this number we find:

>>> from sympy.utilities import flatten

>>> from sympy.ntheory.factor_ import smoothness_p, factorint
>>> print(smoothness_p(21477639576571, visual=1))
p**i=4410317**1 has p-1 B=1787, B-pow=1787
p**i=4869863**1 has p-1 B=2434931, B-pow=2434931

The B and B-pow are the same for the p - 1 factorizations of the divisors because those
factorizations had a very large prime factor:

318 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> factorint(4410317 - 1)
{2: 2, 617: 1, 1787: 1}
>>> factorint(4869863-1)
{2: 1, 2434931: 1}

Note that until B reaches the B-pow value of 1787, the number is not cracked;

>>> pollard_pm1(21477639576571, B=1786)

>>> pollard_pm1(21477639576571, B=1787)
4410317

The B value has to do with the factors of the number next to the divisor, not the divi-
sors themselves. A worst case scenario is that the number next to the factor p has a
large prime divisisor or is a perfect power. If these conditions apply then the power-
smoothness will be about p/2 or p. The more realistic is that there will be a large prime
factor next to p requiring a B value on the order of p/2. Although primes may have been
searched for up to this level, the p/2 is a factor of p - 1, something that we don’t know.
The modular.math reference below states that 15% of numbers in the range of 10**15
to 15**15 + 10**4 are 10**6 power smooth so a B of 10**6 will fail 85% of the time in
that range. From 10**8 to 10**8 + 10**3 the percentages are nearly reversed…but in
that range the simple trial division is quite fast.
sympy.ntheory.factor_.factorint(n, limit=None, use_trial=True, use_rho=True,
use_pm1=True, verbose=False, visual=None,
multiple=False)
Given a positive integer n, factorint(n) returns a dict containing the prime factors of
n as keys and their respective multiplicities as values. For example:

>>> from sympy.ntheory import factorint

>>> factorint(2000) # 2000 = (2**4) * (5**3)
{2: 4, 5: 3}
>>> factorint(65537) # This number is prime
{65537: 1}

For input less than 2, factorint behaves as follows:

• factorint(1) returns the empty factorization, {}
• factorint(0) returns {0:1}
• factorint(-n) adds -1:1 to the factors and then factors n
Partial Factorization:
If limit (> 3) is specified, the search is stopped after performing trial division up to (and
including) the limit (or taking a corresponding number of rho/p-1 steps). This is useful if
one has a large number and only is interested in finding small factors (if any). Note that
setting a limit does not prevent larger factors from being found early; it simply means
that the largest factor may be composite. Since checking for perfect power is relatively
cheap, it is done regardless of the limit setting.
This number, for example, has two small factors and a huge semi-prime factor that cannot
be reduced easily:

>>> from sympy.ntheory import isprime

>>> from sympy.core.compatibility import long
>>> a = 1407633717262338957430697921446883
>>> f = factorint(a, limit=10000)
(continues on next page)

5.3. Number Theory 319

SymPy Documentation, Release 1.3

(continued from previous page)

>>> f == {991: 1, long(202916782076162456022877024859): 1, 7: 1}
True
>>> isprime(max(f))
False

This number has a small factor and a residual perfect power whose base is greater than
the limit:

>>> factorint(3*101**7, limit=5)

{3: 1, 101: 7}

List of Factors:
If multiple is set to True then a list containing the prime factors including multiplicities
is returned.

>>> factorint(24, multiple=True)

[2, 2, 2, 3]

Visual Factorization:
If visual is set to True, then it will return a visual factorization of the integer. For
example:

>>> from sympy import pprint

>>> pprint(factorint(4200, visual=True))
3 1 2 1
2 *3 *5 *7

Note that this is achieved by using the evaluate=False flag in Mul and Pow. If you do other
manipulations with an expression where evaluate=False, it may evaluate. Therefore, you
should use the visual option only for visualization, and use the normal dictionary returned
by visual=False if you want to perform operations on the factors.
You can easily switch between the two forms by sending them back to factorint:

>>> from sympy import Mul, Pow

>>> regular = factorint(1764); regular
{2: 2, 3: 2, 7: 2}
>>> pprint(factorint(regular))
2 2 2
2 *3 *7

>>> visual = factorint(1764, visual=True); pprint(visual)

2 2 2
2 *3 *7
>>> print(factorint(visual))
{2: 2, 3: 2, 7: 2}

If you want to send a number to be factored in a partially factored form you can do so
with a dictionary or unevaluated expression:

>>> factorint(factorint({4: 2, 12: 3})) # twice to toggle to dict form

{2: 10, 3: 3}
>>> factorint(Mul(4, 12, evaluate=False))
{2: 4, 3: 1}

320 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The table of the output logic is:

Input True False other

dict mul dict mul
n mul dict dict
mul mul dict dict

See also:
smoothness (page 313), smoothness_p (page 313), divisors (page 322)

Notes

Algorithm:
The function switches between multiple algorithms. Trial division quickly finds small
factors (of the order 1-5 digits), and finds all large factors if given enough time. The
Pollard rho and p-1 algorithms are used to find large factors ahead of time; they will
often find factors of the order of 10 digits within a few seconds:

>>> factors = factorint(12345678910111213141516)

>>> for base, exp in sorted(factors.items()):
... print('%s %s' % (base, exp))
...
2 2
2507191691 1
1231026625769 1

Any of these methods can optionally be disabled with the following boolean parameters:
• use_trial: Toggle use of trial division
• use_rho: Toggle use of Pollard’s rho method
• use_pm1: Toggle use of Pollard’s p-1 method
factorint also periodically checks if the remaining part is a prime number or a perfect
power, and in those cases stops.
For unevaluated factorial, it uses Legendre’s formula(theorem).
If verbose is set to True, detailed progress is printed.
sympy.ntheory.factor_.primefactors(n, limit=None, verbose=False)
Return a sorted list of n’s prime factors, ignoring multiplicity and any composite factor
that remains if the limit was set too low for complete factorization. Unlike factorint(),
primefactors() does not return -1 or 0.
See also:
divisors (page 322)

Examples

5.3. Number Theory 321

SymPy Documentation, Release 1.3

>>> from sympy.ntheory import primefactors, factorint, isprime

>>> primefactors(6)
[2, 3]
>>> primefactors(-5)
[5]

>>> sorted(factorint(123456).items())
[(2, 6), (3, 1), (643, 1)]
>>> primefactors(123456)
[2, 3, 643]

>>> sorted(factorint(10000000001, limit=200).items())

[(101, 1), (99009901, 1)]
>>> isprime(99009901)
False
>>> primefactors(10000000001, limit=300)
[101]

sympy.ntheory.factor_.divisors(n, generator=False)
Return all divisors of n sorted from 1..n by default. If generator is True an unordered
generator is returned.
The number of divisors of n can be quite large if there are many prime factors (counting
repeated factors). If only the number of factors is desired use divisor_count(n).
See also:
primefactors (page 321), factorint (page 319), divisor_count (page 322)

Examples

>>> from sympy import divisors, divisor_count

>>> divisors(24)
[1, 2, 3, 4, 6, 8, 12, 24]
>>> divisor_count(24)
8

>>> list(divisors(120, generator=True))

[1, 2, 4, 8, 3, 6, 12, 24, 5, 10, 20, 40, 15, 30, 60, 120]

This is a slightly modified version of Tim Peters referenced at: http://stackoverflow.com/

questions/1010381/python-factorization
sympy.ntheory.factor_.divisor_count(n, modulus=1)
Return the number of divisors of n. If modulus is not 1 then only those that are divisible
by modulus are counted.
See also:
factorint (page 319), divisors (page 322), totient (page 324)

References

• http://www.mayer.dial.pipex.com/maths/formulae.htm

322 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import divisor_count

>>> divisor_count(6)
4

sympy.ntheory.factor_.udivisors(n, generator=False)
Return all unitary divisors of n sorted from 1..n by default. If generator is True an un-
ordered generator is returned.
The number of unitary divisors of n can be quite large if there are many prime factors.
If only the number of unitary divisors is desired use udivisor_count(n).
See also:
primefactors (page 321), factorint (page 319), divisors (page 322), divisor_count
(page 322), udivisor_count (page 323)

References

• http://en.wikipedia.org/wiki/Unitary_divisor
• http://mathworld.wolfram.com/UnitaryDivisor.html

Examples

>>> from sympy.ntheory.factor_ import udivisors, udivisor_count

>>> udivisors(15)
[1, 3, 5, 15]
>>> udivisor_count(15)
4

>>> sorted(udivisors(120, generator=True))

[1, 3, 5, 8, 15, 24, 40, 120]

sympy.ntheory.factor_.udivisor_count(n)
Return the number of unitary divisors of n.
See also:
factorint (page 319), divisors (page 322), udivisors (page 323), divisor_count
(page 322), totient (page 324)

References

• http://mathworld.wolfram.com/UnitaryDivisorFunction.html

>>> from sympy.ntheory.factor_ import udivisor_count

>>> udivisor_count(120)
8

sympy.ntheory.factor_.antidivisors(n, generator=False)
Return all antidivisors of n sorted from 1..n by default.
Antidivisors [R433] of n are numbers that do not divide n by the largest possible margin.
If generator is True an unordered generator is returned.

5.3. Number Theory 323

SymPy Documentation, Release 1.3

See also:
primefactors (page 321), factorint (page 319), divisors (page 322), divisor_count
(page 322), antidivisor_count (page 324)

References

[R433]

Examples

>>> from sympy.ntheory.factor_ import antidivisors

>>> antidivisors(24)
[7, 16]

>>> sorted(antidivisors(128, generator=True))

[3, 5, 15, 17, 51, 85]

sympy.ntheory.factor_.antidivisor_count(n)
Return the number of antidivisors [R434] of n.
See also:
factorint (page 319), divisors (page 322), antidivisors (page 323), divisor_count
(page 322), totient (page 324)

References

[R434]

Examples

>>> from sympy.ntheory.factor_ import antidivisor_count

>>> antidivisor_count(13)
4
>>> antidivisor_count(27)
5

class sympy.ntheory.factor_.totient
Calculate the Euler totient function phi(n)
totient(n) or ϕ(n) is the number of positive integers ≤ n that are relatively prime to n.
See also:
divisor_count (page 322)

References

[R435], [R436]

324 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.ntheory import totient

>>> totient(1)
1
>>> totient(25)
20

class sympy.ntheory.factor_.reduced_totient
Calculate the Carmichael reduced totient function lambda(n)
reduced_totient(n) or λ(n) is the smallest m > 0 such that k m ≡ 1 mod n for all k
relatively prime to n.
See also:
totient (page 324)

References

[R437], [R438]

Examples

>>> from sympy.ntheory import reduced_totient

>>> reduced_totient(1)
1
>>> reduced_totient(8)
2
>>> reduced_totient(30)
4

class sympy.ntheory.factor_.divisor_sigma
Calculate the divisor function σk (n) for positive integer n
divisor_sigma(n, k) is equal to sum([x**k for x in divisors(n)])
If n’s prime factorization is:
∏
ω
n= pm
i ,
i

i=1

then
∏
ω

i + · · · + pi
mi k
σk (n) = (1 + pki + p2k ).
i=1

Parameters k : power of divisors in the sum

for k = 0, 1: divisor_sigma(n, 0) is equal to divisor_count(n)
divisor_sigma(n, 1) is equal to sum(divisors(n))
Default for k is 1.
See also:
divisor_count (page 322), totient (page 324), divisors (page 322), factorint
(page 319)

5.3. Number Theory 325

SymPy Documentation, Release 1.3

References

[R439]

Examples

>>> from sympy.ntheory import divisor_sigma

>>> divisor_sigma(18, 0)
6
>>> divisor_sigma(39, 1)
56
>>> divisor_sigma(12, 2)
210
>>> divisor_sigma(37)
38

class sympy.ntheory.factor_.udivisor_sigma
Calculate the unitary divisor function σk∗ (n) for positive integer n
udivisor_sigma(n, k) is equal to sum([x**k for x in udivisors(n)])
If n’s prime factorization is:

∏
ω
n= pm
i ,
i

i=1

then
∏
ω
σk∗ (n) = (1 + pm
i
ik
).
i=1

Parameters k : power of divisors in the sum

for k = 0, 1: udivisor_sigma(n, 0) is equal to udivisor_count(n)
udivisor_sigma(n, 1) is equal to sum(udivisors(n))
Default for k is 1.
See also:
divisor_count (page 322), totient (page 324), divisors (page 322), udivisors
(page 323), udivisor_count (page 323), divisor_sigma (page 325), factorint
(page 319)

References

[R440]

Examples

>>> from sympy.ntheory.factor_ import udivisor_sigma

>>> udivisor_sigma(18, 0)
4
(continues on next page)

326 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> udivisor_sigma(74, 1)
114
>>> udivisor_sigma(36, 3)
47450
>>> udivisor_sigma(111)
152

sympy.ntheory.factor_.core(n, t=2)
Calculate core(n, t) = coret (n) of a positive integer n
core_2(n) is equal to the squarefree part of n
If n’s prime factorization is:

∏
ω
n= pm
i ,
i

i=1

then
∏
ω
mod t
coret (n) = pm
i
i
.
i=1

Parameters t : core(n, t) calculates the t-th power free part of n

core(n, 2) is the squarefree part of n core(n, 3) is the cubefree
part of n
Default for t is 2.
See also:
factorint (page 319), sympy.solvers.diophantine.square_factor (page 1361)

References

[R441]

Examples

>>> from sympy.ntheory.factor_ import core

>>> core(24, 2)
6
>>> core(9424, 3)
1178
>>> core(379238)
379238
>>> core(15**11, 10)
15

sympy.ntheory.factor_.digits(n, b=10)
Return a list of the digits of n in base b. The first element in the list is b (or -b if n is
negative).

5.3. Number Theory 327

SymPy Documentation, Release 1.3

Examples

>>> from sympy.ntheory.factor_ import digits

>>> digits(35)
[10, 3, 5]
>>> digits(27, 2)
[2, 1, 1, 0, 1, 1]
>>> digits(65536, 256)
[256, 1, 0, 0]
>>> digits(-3958, 27)
[-27, 5, 11, 16]

class sympy.ntheory.factor_.primenu
Calculate the number of distinct prime factors for a positive integer n.
If n’s prime factorization is:
∏
k
n= pm
i ,
i

i=1

then primenu(n) or ν(n) is:

ν(n) = k.

See also:
factorint (page 319)

References

[R442]

Examples

>>> from sympy.ntheory.factor_ import primenu

>>> primenu(1)
0
>>> primenu(30)
3

class sympy.ntheory.factor_.primeomega
Calculate the number of prime factors counting multiplicities for a positive integer n.
If n’s prime factorization is:
∏
k
n= pm
i ,
i

i=1

then primeomega(n) or Ω(n) is:

∑
k
Ω(n) = mi .
i=1

See also:
factorint (page 319)

328 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R443]

Examples

>>> from sympy.ntheory.factor_ import primeomega

>>> primeomega(1)
0
>>> primeomega(20)
3

sympy.ntheory.modular.symmetric_residue(a, m)
Return the residual mod m such that it is within half of the modulus.

>>> from sympy.ntheory.modular import symmetric_residue

>>> symmetric_residue(1, 6)
1
>>> symmetric_residue(4, 6)
-2

sympy.ntheory.modular.crt(m, v, symmetric=False, check=True)

Chinese Remainder Theorem.
The moduli in m are assumed to be pairwise coprime. The output is then an integer f,
such that f = v_i mod m_i for each pair out of v and m. If symmetric is False a positive
integer will be returned, else |f| will be less than or equal to the LCM of the moduli, and
thus f may be negative.
If the moduli are not co-prime the correct result will be returned if/when the test of the
result is found to be incorrect. This result will be None if there is no solution.
The keyword check can be set to False if it is known that the moduli are coprime.
As an example consider a set of residues U = [49, 76, 65] and a set of moduli M =
[99, 97, 95]. Then we have:

>>> from sympy.ntheory.modular import crt, solve_congruence

>>> crt([99, 97, 95], [49, 76, 65])

(639985, 912285)

This is the correct result because:

>>> [639985 % m for m in [99, 97, 95]]

[49, 76, 65]

If the moduli are not co-prime, you may receive an incorrect result if you use
check=False:

>>> crt([12, 6, 17], [3, 4, 2], check=False)

(954, 1224)
>>> [954 % m for m in [12, 6, 17]]
[6, 0, 2]
>>> crt([12, 6, 17], [3, 4, 2]) is None
True
(continues on next page)

5.3. Number Theory 329

SymPy Documentation, Release 1.3

(continued from previous page)

>>> crt([3, 6], [2, 5])
(5, 6)

Note: the order of gf_crt’s arguments is reversed relative to crt, and that
solve_congruence takes residue, modulus pairs.
Programmer’s note: rather than checking that all pairs of moduli share no GCD (an
O(n**2) test) and rather than factoring all moduli and seeing that there is no factor in
common, a check that the result gives the indicated residuals is performed – an O(n)
operation.
See also:
solve_congruence (page 330)
sympy.polys.galoistools.gf_crt (page 981) low level crt routine used by this rou-
tine
sympy.ntheory.modular.crt1(m)
First part of Chinese Remainder Theorem, for multiple application.

Examples

>>> from sympy.ntheory.modular import crt1

>>> crt1([18, 42, 6])
(4536, [252, 108, 756], [0, 2, 0])

sympy.ntheory.modular.crt2(m, v, mm, e, s, symmetric=False)

Second part of Chinese Remainder Theorem, for multiple application.

Examples

>>> from sympy.ntheory.modular import crt1, crt2

>>> mm, e, s = crt1([18, 42, 6])
>>> crt2([18, 42, 6], [0, 0, 0], mm, e, s)
(0, 4536)

sympy.ntheory.modular.solve_congruence(*remainder_modulus_pairs, **hint)
Compute the integer n that has the residual ai when it is divided by mi where the ai
and mi are given as pairs to this function: ((a1, m1), (a2, m2), …). If there is no solution,
return None. Otherwise return n and its modulus.
The mi values need not be co-prime. If it is known that the moduli are not co-prime then
the hint check can be set to False (default=True) and the check for a quicker solution
via crt() (valid when the moduli are co-prime) will be skipped.
If the hint symmetric is True (default is False), the value of n will be within 1/2 of the
modulus, possibly negative.
See also:

crt (page 329) high level routine implementing the Chinese Remainder Theorem

330 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.ntheory.modular import solve_congruence

What number is 2 mod 3, 3 mod 5 and 2 mod 7?

>>> solve_congruence((2, 3), (3, 5), (2, 7))

(23, 105)
>>> [23 % m for m in [3, 5, 7]]
[2, 3, 2]

If you prefer to work with all remainder in one list and all moduli in another, send the
arguments like this:

>>> solve_congruence(*zip((2, 3, 2), (3, 5, 7)))

(23, 105)

The moduli need not be co-prime; in this case there may or may not be a solution:

>>> solve_congruence((2, 3), (4, 6)) is None

True

>>> solve_congruence((2, 3), (5, 6))

(5, 6)

The symmetric flag will make the result be within 1/2 of the modulus:

>>> solve_congruence((2, 3), (5, 6), symmetric=True)

(-1, 6)

sympy.ntheory.multinomial.binomial_coefficients(n)
Return a dictionary containing pairs (k1, k2) : Ck n where Ck n are binomial coefficients and
n = k1 + k2. Examples ========

>>> from sympy.ntheory import binomial_coefficients

>>> binomial_coefficients(9)
{(0, 9): 1, (1, 8): 9, (2, 7): 36, (3, 6): 84,
(4, 5): 126, (5, 4): 126, (6, 3): 84, (7, 2): 36, (8, 1): 9, (9, 0): 1}

See also:
binomial_coefficients_list (page 331), multinomial_coefficients (page 331)
sympy.ntheory.multinomial.binomial_coefficients_list(n)
Return a list of binomial coefficients as rows of the Pascal’s triangle.
See also:
binomial_coefficients (page 331), multinomial_coefficients (page 331)

Examples

>>> from sympy.ntheory import binomial_coefficients_list

>>> binomial_coefficients_list(9)
[1, 9, 36, 84, 126, 126, 84, 36, 9, 1]

5.3. Number Theory 331

SymPy Documentation, Release 1.3

sympy.ntheory.multinomial.multinomial_coefficients(m, n)
Return a dictionary containing pairs {(k1,k2,..,km) : C_kn} where C_kn are multino-
mial coefficients such that n=k1+k2+..+km.
For example:

>>> from sympy.ntheory import multinomial_coefficients

>>> multinomial_coefficients(2, 5) # indirect doctest
{(0, 5): 1, (1, 4): 5, (2, 3): 10, (3, 2): 10, (4, 1): 5, (5, 0): 1}

The algorithm is based on the following result:

( ) m ( )
n k1 + 1 ∑ n
=
k1 , . . . , k m n − k1 i=2 k1 + 1, . . . , ki − 1, . . .

Code contributed to Sage by Yann Laigle-Chapuy, copied with permission of the author.
See also:
binomial_coefficients_list (page 331), binomial_coefficients (page 331)
sympy.ntheory.multinomial.multinomial_coefficients_iterator(m, n, _tu-
ple=<class
’tuple’>)
multinomial coefficient iterator
This routine has been optimized for m large with respect to n by taking advantage of the
fact that when the monomial tuples t are stripped of zeros, their coefficient is the same
as that of the monomial tuples from multinomial_coefficients(n, n). Therefore, the
latter coefficients are precomputed to save memory and time.

>>> from sympy.ntheory.multinomial import multinomial_coefficients

>>> m53, m33 = multinomial_coefficients(5,3), multinomial_coefficients(3,3)
>>> m53[(0,0,0,1,2)] == m53[(0,0,1,0,2)] == m53[(1,0,2,0,0)] == m33[(0,1,2)]
True

Examples

>>> from sympy.ntheory.multinomial import multinomial_coefficients_iterator

>>> it = multinomial_coefficients_iterator(20,3)
>>> next(it)
((3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0), 1)

sympy.ntheory.partitions_.npartitions(n, verbose=False)
Calculate the partition function P(n), i.e. the number of ways that n can be written as a
sum of positive integers.
P(n) is computed using the Hardy-Ramanujan-Rademacher formula [R444].
The correctness of this implementation has been tested through 10**10.

References

[R444]

332 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.ntheory import npartitions

>>> npartitions(25)
1958

sympy.ntheory.primetest.mr(n, bases)
Perform a Miller-Rabin strong pseudoprime test on n using a given list of
bases/witnesses.

References

• Richard Crandall & Carl Pomerance (2005), “Prime Numbers: A Computational Per-
spective”, Springer, 2nd edition, 135-138

A list of thresholds and the bases they require are here: http://en.wikipedia.org/wiki/
Miller%E2%80%93Rabin_primality_test#Deterministic_variants_of_the_test

Examples

>>> from sympy.ntheory.primetest import mr

>>> mr(1373651, [2, 3])
False
>>> mr(479001599, [31, 73])
True

sympy.ntheory.primetest.isprime(n)
Test if n is a prime number (True) or not (False). For n < 2^64 the answer is definitive;
larger n values have a small probability of actually being pseudoprimes.
Negative numbers (e.g. -2) are not considered prime.
The first step is looking for trivial factors, which if found enables a quick return. Next,
if the sieve is large enough, use bisection search on the sieve. For small numbers, a
set of deterministic Miller-Rabin tests are performed with bases that are known to have
no counterexamples in their range. Finally if the number is larger than 2^64, a strong
BPSW test is performed. While this is a probable prime test and we believe counterex-
amples exist, there are no known counterexamples.
See also:

sympy.ntheory.generate.primerange (page 309) Generates all primes in a given

range
sympy.ntheory.generate.primepi (page 308) Return the number of primes less than
or equal to n
sympy.ntheory.generate.prime (page 307) Return the nth prime

References

• http://en.wikipedia.org/wiki/Strong_pseudoprime

5.3. Number Theory 333

SymPy Documentation, Release 1.3

• “Lucas Pseudoprimes”, Baillie and Wagstaff, 1980. http://mpqs.free.fr/

LucasPseudoprimes.pdf
• https://en.wikipedia.org/wiki/Baillie-PSW_primality_test

Examples

>>> from sympy.ntheory import isprime

>>> isprime(13)
True
>>> isprime(15)
False

sympy.ntheory.residue_ntheory.n_order(a, n)
Returns the order of a modulo n.
The order of a modulo n is the smallest integer k such that a**k leaves a remainder of 1
with n.

Examples

>>> from sympy.ntheory import n_order

>>> n_order(3, 7)
6
>>> n_order(4, 7)
3

sympy.ntheory.residue_ntheory.is_primitive_root(a, p)
Returns True if a is a primitive root of p
a is said to be the primitive root of p if gcd(a, p) == 1 and totient(p) is the smallest
positive number s.t.
a**totient(p) cong 1 mod(p)

Examples

>>> from sympy.ntheory import is_primitive_root, n_order, totient

>>> is_primitive_root(3, 10)
True
>>> is_primitive_root(9, 10)
False
>>> n_order(3, 10) == totient(10)
True
>>> n_order(9, 10) == totient(10)
False

sympy.ntheory.residue_ntheory.primitive_root(p)
Returns the smallest primitive root or None
Parameters p : positive integer

334 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R445], [R446]

Examples

>>> from sympy.ntheory.residue_ntheory import primitive_root

>>> primitive_root(19)
2

sympy.ntheory.residue_ntheory.sqrt_mod(a, p, all_roots=False)
Find a root of x**2 = a mod p
Parameters a : integer
p : positive integer
all_roots : if True the list of roots is returned or None

Notes

If there is no root it is returned None; else the returned root is less or equal to p // 2;
in general is not the smallest one. It is returned p // 2 only if it is the only root.
Use all_roots only when it is expected that all the roots fit in memory; otherwise use
sqrt_mod_iter.

Examples

>>> from sympy.ntheory import sqrt_mod

>>> sqrt_mod(11, 43)
21
>>> sqrt_mod(17, 32, True)
[7, 9, 23, 25]

sympy.ntheory.residue_ntheory.quadratic_residues(p)
Returns the list of quadratic residues.

Examples

>>> from sympy.ntheory.residue_ntheory import quadratic_residues

>>> quadratic_residues(7)
[0, 1, 2, 4]

sympy.ntheory.residue_ntheory.nthroot_mod(a, n, p, all_roots=False)
Find the solutions to x**n = a mod p
Parameters a : integer
n : positive integer
p : positive integer
all_roots : if False returns the smallest root, else the list of roots

5.3. Number Theory 335

SymPy Documentation, Release 1.3

Examples

>>> from sympy.ntheory.residue_ntheory import nthroot_mod

>>> nthroot_mod(11, 4, 19)
8
>>> nthroot_mod(11, 4, 19, True)
[8, 11]
>>> nthroot_mod(68, 3, 109)
23

sympy.ntheory.residue_ntheory.is_nthpow_residue(a, n, m)
Returns True if x**n == a (mod m) has solutions.

References

[R447]
sympy.ntheory.residue_ntheory.is_quad_residue(a, p)
Returns True if a (mod p) is in the set of squares mod p, i.e a % p in set([i**2 % p for i in
range(p)]). If p is an odd prime, an iterative method is used to make the determination:

>>> from sympy.ntheory import is_quad_residue

>>> sorted(set([i**2 % 7 for i in range(7)]))
[0, 1, 2, 4]
>>> [j for j in range(7) if is_quad_residue(j, 7)]
[0, 1, 2, 4]

See also:
legendre_symbol (page 336), jacobi_symbol (page 336)
sympy.ntheory.residue_ntheory.legendre_symbol(a, p)
Returns the Legendre symbol (a/p).
For an integer a and an odd prime p, the Legendre symbol is defined as

( )  0 if p divides a
a
= 1 if a is a quadratic residue modulo p
p 

−1 if a is a quadratic nonresidue modulo p

Parameters a : integer
p : odd prime
See also:
is_quad_residue (page 336), jacobi_symbol (page 336)

Examples

>>> from sympy.ntheory import legendre_symbol

>>> [legendre_symbol(i, 7) for i in range(7)]
[0, 1, 1, -1, 1, -1, -1]
>>> sorted(set([i**2 % 7 for i in range(7)]))
[0, 1, 2, 4]

336 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.ntheory.residue_ntheory.jacobi_symbol(m, n)
Returns the Jacobi symbol (m/n).
For any integer m and any positive odd integer n the Jacobi symbol is defined as the
product of the Legendre symbols corresponding to the prime factors of n:
( ) ( )α1 ( )α2 ( )αk
m m m m αk
= ... k where n = pα1 α2
1 p2 ...pk
n p1 p2 p
( )
Like the Legendre symbol, if the Jacobi symbol mn = −1 then m is a quadratic nonresidue
modulo n.
( )
But, unlike the Legendre symbol, if the Jacobi symbol mn = 1 then m may or may not be
a quadratic residue modulo n.
Parameters m : integer
n : odd positive integer
See also:
is_quad_residue (page 336), legendre_symbol (page 336)

Examples

>>> from sympy.ntheory import jacobi_symbol, legendre_symbol

>>> from sympy import Mul, S
>>> jacobi_symbol(45, 77)
-1
>>> jacobi_symbol(60, 121)
1

The relationship between the jacobi_symbol and legendre_symbol can be demon-

strated as follows:

>>> L = legendre_symbol
>>> S(45).factors()
{3: 2, 5: 1}
>>> jacobi_symbol(7, 45) == L(7, 3)**2 * L(7, 5)**1
True

sympy.ntheory.residue_ntheory.discrete_log(n, a, b, order=None,
prime_order=None)
Compute the discrete logarithm of a to the base b modulo n.
This is a recursive function to reduce the discrete logarithm problem in cyclic groups of
composite order to the problem in cyclic groups of prime order.
It employs different algorithms depending on the problem (subgroup order size, prime
order or not):
• Trial multiplication
• Baby-step giant-step
• Pollard’s Rho
• Pohlig-Hellman

5.3. Number Theory 337

SymPy Documentation, Release 1.3

References

[R448], [R449]

Examples

>>> from sympy.ntheory import discrete_log

>>> discrete_log(41, 15, 7)
3

sympy.ntheory.continued_fraction.continued_fraction_convergents(cf)
Return an iterator over the convergents of a continued fraction (cf).
The parameter should be an iterable returning successive partial quotients of the con-
tinued fraction, such as might be returned by continued_fraction_iterator. In computing
the convergents, the continued fraction need not be strictly in canonical form (all inte-
gers, all but the first positive). Rational and negative elements may be present in the
expansion.
See also:
continued_fraction_iterator (page 338)

Examples

>>> from sympy.core import Rational, pi

>>> from sympy import S
>>> from sympy.ntheory.continued_fraction import continued_fraction_
,→convergents, continued_fraction_iterator

>>> list(continued_fraction_convergents([0, 2, 1, 2]))

[0, 1/2, 1/3, 3/8]

>>> list(continued_fraction_convergents([1, S('1/2'), -7, S('1/4')]))

[1, 3, 19/5, 7]

>>> it = continued_fraction_convergents(continued_fraction_iterator(pi))
>>> for n in range(7):
... print(next(it))
3
22/7
333/106
355/113
103993/33102
104348/33215
208341/66317

sympy.ntheory.continued_fraction.continued_fraction_iterator(x)
Return continued fraction expansion of x as iterator.

References

[R450]

338 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.core import Rational, pi

>>> from sympy.ntheory.continued_fraction import continued_fraction_iterator

>>> list(continued_fraction_iterator(Rational(3, 8)))

[0, 2, 1, 2]
>>> list(continued_fraction_iterator(Rational(-3, 8)))
[-1, 1, 1, 1, 2]

>>> for i, v in enumerate(continued_fraction_iterator(pi)):

... if i > 7:
... break
... print(v)
3
7
15
1
292
1
1
1

sympy.ntheory.continued_fraction.continued_fraction_periodic(p, q, d=0)
Find the periodic continued fraction expansion of a quadratic irrational.
Compute
√
the continued fraction expansion of a rational or a quadratic irrational number,
i.e. q , where p, q and d ≥ 0 are integers.
p+ d

Returns the continued fraction representation (canonical form) as a list of integers, op-
tionally ending (for quadratic irrationals) with repeating block as the last term of this
list.
Parameters p : int
the rational part of the number’s numerator
q : int
the denominator of the number
d : int, optional
the irrational part (discriminator) of the number’s numerator
See also:
continued_fraction_iterator (page 338), continued_fraction_reduce (page 340)

References

[R451], [R452]

Examples

5.3. Number Theory 339

SymPy Documentation, Release 1.3

>>> from sympy.ntheory.continued_fraction import continued_fraction_periodic

>>> continued_fraction_periodic(3, 2, 7)
[2, [1, 4, 1, 1]]

Golden ratio has the simplest continued fraction expansion:

>>> continued_fraction_periodic(1, 2, 5)
[[1]]

If the discriminator is zero or a perfect square then the number will be a rational number:

>>> continued_fraction_periodic(4, 3, 0)
[1, 3]
>>> continued_fraction_periodic(4, 3, 49)
[3, 1, 2]

sympy.ntheory.continued_fraction.continued_fraction_reduce(cf)
Reduce a continued fraction to a rational or quadratic irrational.
Compute the rational or quadratic irrational number from its terminating or periodic
continued fraction expansion. The continued fraction expansion (cf) should be supplied
as a terminating iterator supplying the terms of the expansion. For terminating contin-
ued fractions, this is equivalent to list(continued_fraction_convergents(cf))[-1],
only a little more efficient. If the expansion has a repeating part, a list of the repeat-
ing terms should be returned as the last element from the iterator. This is the format
returned by continued_fraction_periodic.
For quadratic irrationals, returns the largest solution found, which is generally the one
sought, if the fraction is in canonical form (all terms positive except possibly the first).
See also:
continued_fraction_periodic (page 339)

Examples

>>> from sympy.ntheory.continued_fraction import continued_fraction_reduce

>>> continued_fraction_reduce([1, 2, 3, 4, 5])
225/157
>>> continued_fraction_reduce([-2, 1, 9, 7, 1, 2])
-256/233
>>> continued_fraction_reduce([2, 1, 2, 1, 1, 4, 1, 1, 6, 1, 1, 8]).n(10)
2.718281835
>>> continued_fraction_reduce([1, 4, 2, [3, 1]])
(sqrt(21) + 287)/238
>>> continued_fraction_reduce([[1]])
1/2 + sqrt(5)/2
>>> from sympy.ntheory.continued_fraction import continued_fraction_periodic
>>> continued_fraction_reduce(continued_fraction_periodic(8, 5, 13))
(sqrt(13) + 8)/5

class sympy.ntheory.mobius
Möbius function maps natural number to {-1, 0, 1}
It is defined as follows:
1) 1 if n = 1.

340 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

2) 0 if n has a squared prime factor.

3) (−1)k if n is a square-free positive integer with k number of prime factors.
It is an important multiplicative function in number theory and combinatorics. It has
applications in mathematical series, algebraic number theory and also physics (Fermion
operator has very concrete realization with Möbius Function model).
Parameters n : positive integer

References

[R453], [R454]

Examples

>>> from sympy.ntheory import mobius

>>> mobius(13*7)
1
>>> mobius(1)
1
>>> mobius(13*7*5)
-1
>>> mobius(13**2)
0

sympy.ntheory.egyptian_fraction.egyptian_fraction(r, algorithm=’Greedy’)
Return the list of denominators of an Egyptian fraction expansion [R455] of the said
rational r.
Parameters r : Rational
a positive rational number.
algorithm : { “Greedy”, “Graham Jewett”, “Takenouchi”, “Golomb” }, op-
tional
Denotes the algorithm to be used (the default is “Greedy”).
See also:
sympy.core.numbers.Rational (page 145)

Notes

Currently the following algorithms are supported:

1) Greedy Algorithm
Also called the Fibonacci-Sylvester algorithm [R456]. At each step, extract the
largest unit fraction less than the target and replace the target with the remain-
der.
It has some distinct properties:
a) Given p/q in lowest terms, generates an expansion of maximum length p. Even
as the numerators get large, the number of terms is seldom more than a handful.

5.3. Number Theory 341

SymPy Documentation, Release 1.3

b) Uses minimal memory.

c) The terms can blow up (standard examples of this are 5/121 and 31/311). The
denominator is at most squared at each step (doubly-exponential growth) and
typically exhibits singly-exponential growth.
2) Graham Jewett Algorithm
The algorithm suggested by the result of Graham and Jewett. Note that this has a
tendency to blow up: the length of the resulting expansion is always 2**(x/gcd(x,
y)) - 1. See [R457].
3) Takenouchi Algorithm
The algorithm suggested by Takenouchi (1921). Differs from the Graham-Jewett
algorithm only in the handling of duplicates. See [R457].
4) Golomb’s Algorithm
A method given by Golumb (1962), using modular arithmetic and inverses. It yields
the same results as a method using continued fractions proposed by Bleicher (1972).
See [R458].
If the given rational is greater than or equal to 1, a greedy algorithm of summing the
harmonic sequence 1/1 + 1/2 + 1/3 + … is used, taking all the unit fractions of this
sequence until adding one more would be greater than the given number. This list of
denominators is prefixed to the result from the requested algorithm used on the remain-
der. For example, if r is 8/3, using the Greedy algorithm, we get [1, 2, 3, 4, 5, 6, 7, 14,
420], where the beginning of the sequence, [1, 2, 3, 4, 5, 6, 7] is part of the harmonic
sequence summing to 363/140, leaving a remainder of 31/420, which yields [14, 420] by
the Greedy algorithm. The result of egyptian_fraction(Rational(8, 3), “Golomb”) is [1, 2,
3, 4, 5, 6, 7, 14, 574, 2788, 6460, 11590, 33062, 113820], and so on.

References

[R455], [R456], [R457], [R458]

Examples

>>> from sympy import Rational

>>> from sympy.ntheory.egyptian_fraction import egyptian_fraction
>>> egyptian_fraction(Rational(3, 7))
[3, 11, 231]
>>> egyptian_fraction(Rational(3, 7), ”Graham Jewett”)
[7, 8, 9, 56, 57, 72, 3192]
>>> egyptian_fraction(Rational(3, 7), ”Takenouchi”)
[4, 7, 28]
>>> egyptian_fraction(Rational(3, 7), ”Golomb”)
[3, 15, 35]
>>> egyptian_fraction(Rational(11, 5), ”Golomb”)
[1, 2, 3, 4, 9, 234, 1118, 2580]

342 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.4 Basic Cryptography Module

Warning: This module is intended for educational purposes only. Do not use the functions
in this module for real cryptographic applications. If you wish to encrypt real data, we
recommend using something like the cryptography module.

Encryption is the process of hiding a message and a cipher is a means of doing so. Included
in this module are both block and stream ciphers:
• Shift cipher
• Affine cipher
• substitution ciphers
• Vigenere’s cipher
• Hill’s cipher
• Bifid ciphers
• RSA
• Kid RSA
• linear-feedback shift registers (for stream ciphers)
• ElGamal encryption
In a substitution cipher “units” (not necessarily single characters) of plaintext are replaced
with ciphertext according to a regular system.
A transposition cipher is a method of encryption by which the positions held by “units” of
plaintext are replaced by a permutation of the plaintext. That is, the order of the units is
changed using a bijective function on the position of the characters to perform the encryption.
A monoalphabetic cipher uses fixed substitution over the entire message, whereas a polyal-
phabetic cipher uses a number of substitutions at different times in the message.
sympy.crypto.crypto.AZ(s=None)
Return the letters of s in uppercase. In case more than one string is passed, each of
them will be processed and a list of upper case strings will be returned.
See also:
check_and_join (page 344)

Examples

>>> from sympy.crypto.crypto import AZ

>>> AZ('Hello, world!')
'HELLOWORLD'
>>> AZ('Hello, world!'.split())
['HELLO', 'WORLD']

sympy.crypto.crypto.padded_key(key, symbols, filter=True)

Return a string of the distinct characters of symbols with those of key appearing first,

5.4. Basic Cryptography Module 343

SymPy Documentation, Release 1.3

omitting characters in key that are not in symbols. A ValueError is raised if a) there are
duplicate characters in symbols or b) there are characters in key that are not in symbols.

Examples

>>> from sympy.crypto.crypto import padded_key

>>> padded_key('PUPPY', 'OPQRSTUVWXY')
'PUYOQRSTVWX'
>>> padded_key('RSA', 'ARTIST')
Traceback (most recent call last):
...
ValueError: duplicate characters in symbols: T

sympy.crypto.crypto.check_and_join(phrase, symbols=None, filter=None)

Joins characters of phrase and if symbols is given, raises an error if any character in
phrase is not in symbols.
Parameters phrase: string or list of strings to be returned as a string
symbols: iterable of characters allowed in ‘‘phrase‘‘;
if symbols is None, no checking is performed

Examples

>>> from sympy.crypto.crypto import check_and_join

>>> check_and_join('a phrase')
'a phrase'
>>> check_and_join('a phrase'.upper().split())
'APHRASE'
>>> check_and_join('a phrase!'.upper().split(), 'ARE', filter=True)
'ARAE'
>>> check_and_join('a phrase!'.upper().split(), 'ARE')
Traceback (most recent call last):
...
ValueError: characters in phrase but not symbols: ”!HPS”

sympy.crypto.crypto.cycle_list(k, n)
Returns the elements of the list range(n) shifted to the left by k (so the list starts with
k (mod n)).

Examples

>>> from sympy.crypto.crypto import cycle_list

>>> cycle_list(3, 10)
[3, 4, 5, 6, 7, 8, 9, 0, 1, 2]

sympy.crypto.crypto.encipher_shift(msg, key, symbols=None)

Performs shift cipher encryption on plaintext msg, and returns the ciphertext.

344 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notes

The shift cipher is also called the Caesar cipher, after Julius Caesar, who, according
to Suetonius, used it with a shift of three to protect messages of military significance.
Caesar’s nephew Augustus reportedly used a similar cipher, but with a right shift of 1.
ALGORITHM:
INPUT:
key: an integer (the secret key)
msg: plaintext of upper-case letters
OUTPUT:
ct: ciphertext of upper-case letters

STEPS:
0. Number the letters of the alphabet from 0, …, N
1. Compute from the string msg a list L1 of corresponding integers.
2. Compute from the list L1 a new list L2, given by adding (k mod 26) to
each element in L1.
3. Compute from the list L2 a string ct of corresponding letters.

Examples

>>> from sympy.crypto.crypto import encipher_shift, decipher_shift

>>> msg = ”GONAVYBEATARMY”
>>> ct = encipher_shift(msg, 1); ct
'HPOBWZCFBUBSNZ'

To decipher the shifted text, change the sign of the key:

>>> encipher_shift(ct, -1)

'GONAVYBEATARMY'

There is also a convenience function that does this with the original key:

>>> decipher_shift(ct, 1)
'GONAVYBEATARMY'

sympy.crypto.crypto.decipher_shift(msg, key, symbols=None)

Return the text by shifting the characters of msg to the left by the amount given by key.

Examples

>>> from sympy.crypto.crypto import encipher_shift, decipher_shift

>>> msg = ”GONAVYBEATARMY”
>>> ct = encipher_shift(msg, 1); ct
'HPOBWZCFBUBSNZ'

To decipher the shifted text, change the sign of the key:

5.4. Basic Cryptography Module 345

SymPy Documentation, Release 1.3

>>> encipher_shift(ct, -1)

'GONAVYBEATARMY'

Or use this function with the original key:

>>> decipher_shift(ct, 1)
'GONAVYBEATARMY'

sympy.crypto.crypto.encipher_affine(msg, key, symbols=None, _inverse=False)

Performs the affine cipher encryption on plaintext msg, and returns the ciphertext.
Encryption is based on the map x → ax+b (mod N ) where N is the number of characters in
the alphabet. Decryption is based on the map x → cx + d (mod N ), where c = a−1 (mod N )
and d = −a−1 b (mod N ). In particular, for the map to be invertible, we need gcd(a, N ) = 1
and an error will be raised if this is not true.
See also:
decipher_affine (page 346)

Notes

This is a straightforward generalization of the shift cipher with the added complexity of
requiring 2 characters to be deciphered in order to recover the key.
ALGORITHM:
INPUT:
msg: string of characters that appear in symbols
a, b: a pair integers, with gcd(a, N) = 1 (the secret key)
symbols: string of characters (default = uppercase letters). When no
symbols are given, msg is converted to upper case letters and all other
charactes are ignored.
OUTPUT:
ct: string of characters (the ciphertext message)

STEPS:
0. Number the letters of the alphabet from 0, …, N
1. Compute from the string msg a list L1 of corresponding integers.
2. Compute from the list L1 a new list L2, given by replacing x by a*x + b
(mod N), for each element x in L1.
3. Compute from the list L2 a string ct of corresponding letters.

sympy.crypto.crypto.decipher_affine(msg, key, symbols=None)

Return the deciphered text that was made from the mapping, x → ax + b (mod N ), where
N is the number of characters in the alphabet. Deciphering is done by reciphering with
a new key: x → cx + d (mod N ), where c = a−1 (mod N ) and d = −a−1 b (mod N ).

346 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import encipher_affine, decipher_affine

>>> msg = ”GO NAVY BEAT ARMY”
>>> key = (3, 1)
>>> encipher_affine(msg, key)
'TROBMVENBGBALV'
>>> decipher_affine(_, key)
'GONAVYBEATARMY'

sympy.crypto.crypto.encipher_substitution(msg, old, new=None)

Returns the ciphertext obtained by replacing each character that appears in old with
the corresponding character in new. If old is a mapping, then new is ignored and the
replacements defined by old are used.

Notes

This is a more general than the affine cipher in that the key can only be recovered by
determining the mapping for each symbol. Though in practice, once a few symbols are
recognized the mappings for other characters can be quickly guessed.

Examples

>>> from sympy.crypto.crypto import encipher_substitution, AZ

>>> old = 'OEYAG'
>>> new = '034^6'
>>> msg = AZ(”go navy! beat army!”)
>>> ct = encipher_substitution(msg, old, new); ct
'60N^V4B3^T^RM4'

To decrypt a substitution, reverse the last two arguments:

>>> encipher_substitution(ct, new, old)

'GONAVYBEATARMY'

In the special case where old and new are a permutation of order 2 (representing a
transposition of characters) their order is immaterial:

>>> old = 'NAVY'

>>> new = 'ANYV'
>>> encipher = lambda x: encipher_substitution(x, old, new)
>>> encipher('NAVY')
'ANYV'
>>> encipher(_)
'NAVY'

The substitution cipher, in general, is a method whereby “units” (not necessarily single
characters) of plaintext are replaced with ciphertext according to a regular system.

>>> ords = dict(zip('abc', ['\\%i' % ord(i) for i in 'abc']))

>>> print(encipher_substitution('abc', ords))
\97\98\99

5.4. Basic Cryptography Module 347

SymPy Documentation, Release 1.3

sympy.crypto.crypto.encipher_vigenere(msg, key, symbols=None)

Performs the Vigenère cipher encryption on plaintext msg, and returns the ciphertext.

Notes

The Vigenère cipher is named after Blaise de Vigenère, a sixteenth century diplomat
and cryptographer, by a historical accident. Vigenère actually invented a different and
more complicated cipher. The so-called Vigenère cipher was actually invented by Giovan
Batista Belaso in 1553.
This cipher was used in the 1800’s, for example, during the American Civil War. The
Confederacy used a brass cipher disk to implement the Vigenère cipher (now on display
in the NSA Museum in Fort Meade) [R78].
The Vigenère cipher is a generalization of the shift cipher. Whereas the shift cipher
shifts each letter by the same amount (that amount being the key of the shift cipher) the
Vigenère cipher shifts a letter by an amount determined by the key (which is a word or
phrase known only to the sender and receiver).
For example, if the key was a single letter, such as “C”, then the so-called Vigenere cipher
is actually a shift cipher with a shift of 2 (since “C” is the 2nd letter of the alphabet, if
you start counting at 0). If the key was a word with two letters, such as “CA”, then the so-
called Vigenère cipher will shift letters in even positions by 2 and letters in odd positions
are left alone (shifted by 0, since “A” is the 0th letter, if you start counting at 0).
ALGORITHM:
INPUT:
msg: string of characters that appear in symbols (the plaintext)
key: a string of characters that appear in symbols (the secret key)
symbols: a string of letters defining the alphabet
OUTPUT:
ct: string of characters (the ciphertext message)

STEPS:
0. Number the letters of the alphabet from 0, …, N
1. Compute from the string key a list L1 of corresponding integers. Let n1
= len(L1).
2. Compute from the string msg a list L2 of corresponding integers. Let n2
= len(L2).
3. Break L2 up sequentially into sublists of size n1; the last sublist may be
smaller than n1
4. For each of these sublists L of L2, compute a new list C given by C[i] =
L[i] + L1[i] (mod N) to the i-th element in the sublist, for each i.
5. Assemble these lists C by concatenation into a new list of length n2.
6. Compute from the new list a string ct of corresponding letters.

Once it is known that the key is, say, n characters long, frequency analysis can be applied
to every n-th letter of the ciphertext to determine the plaintext. This method is called

348 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Kasiski examination (although it was first discovered by Babbage). If they key is as long
as the message and is comprised of randomly selected characters – a one-time pad – the
message is theoretically unbreakable.
The cipher Vigenère actually discovered is an “auto-key” cipher described as follows.
ALGORITHM:
INPUT:
key: a string of letters (the secret key)
msg: string of letters (the plaintext message)
OUTPUT:
ct: string of upper-case letters (the ciphertext message)

STEPS:
0. Number the letters of the alphabet from 0, …, N
1. Compute from the string msg a list L2 of corresponding integers. Let n2
= len(L2).
2. Let n1 be the length of the key. Append to the string key the first n2 -
n1 characters of the plaintext message. Compute from this string (also
of length n2) a list L1 of integers corresponding to the letter numbers in
the first step.
3. Compute a new list C given by C[i] = L1[i] + L2[i] (mod N).
4. Compute from the new list a string ct of letters corresponding to the
new integers.

To decipher the auto-key ciphertext, the key is used to decipher the first n1 characters
and then those characters become the key to decipher the next n1 characters, etc…:

>>> m = AZ('go navy, beat army! yes you can'); m

'GONAVYBEATARMYYESYOUCAN'
>>> key = AZ('gold bug'); n1 = len(key); n2 = len(m)
>>> auto_key = key + m[:n2 - n1]; auto_key
'GOLDBUGGONAVYBEATARMYYE'
>>> ct = encipher_vigenere(m, auto_key); ct
'MCYDWSHKOGAMKZCELYFGAYR'
>>> n1 = len(key)
>>> pt = []
>>> while ct:
... part, ct = ct[:n1], ct[n1:]
... pt.append(decipher_vigenere(part, key))
... key = pt[-1]
...
>>> ''.join(pt) == m
True

References

[R78], [R79]

5.4. Basic Cryptography Module 349

SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import encipher_vigenere, AZ

>>> key = ”encrypt”
>>> msg = ”meet me on monday”
>>> encipher_vigenere(msg, key)
'QRGKKTHRZQEBPR'

Section 1 of the Kryptos sculpture at the CIA headquarters uses this cipher and also
changes the order of the the alphabet [R79]. Here is the first line of that section of the
sculpture:

>>> from sympy.crypto.crypto import decipher_vigenere, padded_key

>>> alp = padded_key('KRYPTOS', AZ())
>>> key = 'PALIMPSEST'
>>> msg = 'EMUFPHZLRFAXYUSDJKZLDKRNSHGNFIVJ'
>>> decipher_vigenere(msg, key, alp)
'BETWEENSUBTLESHADINGANDTHEABSENC'

sympy.crypto.crypto.decipher_vigenere(msg, key, symbols=None)

Decode using the Vigenère cipher.

Examples

>>> from sympy.crypto.crypto import decipher_vigenere

>>> key = ”encrypt”
>>> ct = ”QRGK kt HRZQE BPR”
>>> decipher_vigenere(ct, key)
'MEETMEONMONDAY'

sympy.crypto.crypto.encipher_hill(msg, key, symbols=None, pad=’Q’)

Return the Hill cipher encryption of msg.
See also:
decipher_hill (page 351)

Notes

The Hill cipher [R80], invented by Lester S. Hill in the 1920’s [R81], was the first poly-
graphic cipher in which it was practical (though barely) to operate on more than three
symbols at once. The following discussion assumes an elementary knowledge of matri-
ces.
First, each letter is first encoded as a number starting with 0. Suppose your message
msg consists of n capital letters, with no spaces. This may be regarded an n-tuple M of
elements of Z26 (if the letters are those of the English alphabet). A key in the Hill cipher
is a kxk matrix K, all of whose entries are in Z26 , such that the matrix K is invertible (i.e.,
the linear transformation K : ZN k
→ ZNk
is one-to-one).
ALGORITHM:
INPUT:

350 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

msg: plaintext message of n upper-case letters

key: a kxk invertible matrix K, all of whose entries are in Z26 (or whatever
number of symbols are being used).
pad: character (default “Q”) to use to make length of text be a multiple
of k
OUTPUT:
ct: ciphertext of upper-case letters

STEPS:
0. Number the letters of the alphabet from 0, …, N
1. Compute from the string msg a list L of corresponding integers. Let n =
len(L).
2. Break the list L up into t = ceiling(n/k) sublists L_1, …, L_t of size k
(with the last list “padded” to ensure its size is k).
3. Compute new list C_1, …, C_t given by C[i] = K*L_i (arithmetic is done
mod N), for each i.
4. Concatenate these into a list C = C_1 + ... + C_t.
5. Compute from C a string ct of corresponding letters. This has length
k*t.

References

[R80], [R81]
sympy.crypto.crypto.decipher_hill(msg, key, symbols=None)
Deciphering is the same as enciphering but using the inverse of the key matrix.

Examples

>>> from sympy.crypto.crypto import encipher_hill, decipher_hill

>>> from sympy import Matrix

>>> key = Matrix([[1, 2], [3, 5]])

>>> encipher_hill(”meet me on monday”, key)
'UEQDUEODOCTCWQ'
>>> decipher_hill(_, key)
'MEETMEONMONDAY'

When the length of the plaintext (stripped of invalid characters) is not a multiple of the
key dimension, extra characters will appear at the end of the enciphered and deciphered
text. In order to decipher the text, those characters must be included in the text to be
deciphered. In the following, the key has a dimension of 4 but the text is 2 short of being
a multiple of 4 so two characters will be added.

5.4. Basic Cryptography Module 351

SymPy Documentation, Release 1.3

>>> key = Matrix([[1, 1, 1, 2], [0, 1, 1, 0],

... [2, 2, 3, 4], [1, 1, 0, 1]])
>>> msg = ”ST”
>>> encipher_hill(msg, key)
'HJEB'
>>> decipher_hill(_, key)
'STQQ'
>>> encipher_hill(msg, key, pad=”Z”)
'ISPK'
>>> decipher_hill(_, key)
'STZZ'

If the last two characters of the ciphertext were ignored in either case, the wrong plain-
text would be recovered:

>>> decipher_hill(”HD”, key)

'ORMV'
>>> decipher_hill(”IS”, key)
'UIKY'

sympy.crypto.crypto.encipher_bifid(msg, key, symbols=None)

Performs the Bifid cipher encryption on plaintext msg, and returns the ciphertext.
This is the version of the Bifid cipher that uses an n × n Polybius square.
INPUT:
msg: plaintext string
key: short string for key; duplicate characters are ignored and then it is
padded with the characters in symbols that were not in the short key
symbols: n × n characters defining the alphabet (default is
string.printable)
OUTPUT:
ciphertext (using Bifid5 cipher without spaces)
See also:
decipher_bifid (page 352), encipher_bifid5 (page 354), encipher_bifid6 (page 356)
sympy.crypto.crypto.decipher_bifid(msg, key, symbols=None)
Performs the Bifid cipher decryption on ciphertext msg, and returns the plaintext.
This is the version of the Bifid cipher that uses the n × n Polybius square.
INPUT:
msg: ciphertext string
key: short string for key; duplicate characters are ignored and then it is
padded with the characters in symbols that were not in the short key
symbols: n × n characters defining the alphabet (de-
fault=string.printable, a 10 × 10 matrix)
OUTPUT:
deciphered text

352 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import (

... encipher_bifid, decipher_bifid, AZ)

Do an encryption using the bifid5 alphabet:

>>> alp = AZ().replace('J', '')

>>> ct = AZ(”meet me on monday!”)
>>> key = AZ(”gold bug”)
>>> encipher_bifid(ct, key, alp)
'IEILHHFSTSFQYE'

When entering the text or ciphertext, spaces are ignored so it can be formatted as de-
sired. Re-entering the ciphertext from the preceding, putting 4 characters per line and
padding with an extra J, does not cause problems for the deciphering:

>>> decipher_bifid('''
... IEILH
... HFSTS
... FQYEJ''', key, alp)
'MEETMEONMONDAY'

When no alphabet is given, all 100 printable characters will be used:

>>> key = ''

>>> encipher_bifid('hello world!', key)
'bmtwmg-bIo*w'
>>> decipher_bifid(_, key)
'hello world!'

If the key is changed, a different encryption is obtained:

>>> key = 'gold bug'

>>> encipher_bifid('hello world!', 'gold_bug')
'hg2sfuei7t}w'

And if the key used to decrypt the message is not exact, the original text will not be
perfectly obtained:

>>> decipher_bifid(_, 'gold pug')

'heldo~wor6d!'

sympy.crypto.crypto.bifid5_square(key=None)
5x5 Polybius square.
Produce the Polybius square for the 5 × 5 Bifid cipher.

Examples

>>> from sympy.crypto.crypto import bifid5_square

>>> bifid5_square(”gold bug”)
Matrix([
[G, O, L, D, B],
[U, A, C, E, F],
(continues on next page)

5.4. Basic Cryptography Module 353

SymPy Documentation, Release 1.3

(continued from previous page)

[H, I, K, M, N],
[P, Q, R, S, T],
[V, W, X, Y, Z]])

sympy.crypto.crypto.encipher_bifid5(msg, key)
Performs the Bifid cipher encryption on plaintext msg, and returns the ciphertext.
This is the version of the Bifid cipher that uses the 5 × 5 Polybius square. The letter
“J” is ignored so it must be replaced with something else (traditionally an “I”) before
encryption.
See also:
decipher_bifid5 (page 355), encipher_bifid (page 352)

Notes

The Bifid cipher was invented around 1901 by Felix Delastelle. It is a fractional substi-
tution cipher, where letters are replaced by pairs of symbols from a smaller alphabet.
The cipher uses a 5 × 5 square filled with some ordering of the alphabet, except that
“J” is replaced with “I” (this is a so-called Polybius square; there is a 6 × 6 analog if you
add back in “J” and also append onto the usual 26 letter alphabet, the digits 0, 1, …, 9).
According to Helen Gaines’ book Cryptanalysis, this type of cipher was used in the field
by the German Army during World War I.
ALGORITHM: (5x5 case)
INPUT:
msg: plaintext string; converted to upper case and filtered of anything
but all letters except J.
key: short string for key; non-alphabetic letters, J and duplicated char-
acters are ignored and then, if the length is less than 25 characters, it
is padded with other letters of the alphabet (in alphabetical order).
OUTPUT:
ciphertext (all caps, no spaces)

STEPS:
0. Create the 5 × 5 Polybius square S associated to key as follows:
a) moving from left-to-right, top-to-bottom, place the letters of the key
into a 5 × 5 matrix,
b) if the key has less than 25 letters, add the letters of the alphabet not
in the key until the 5 × 5 square is filled.
1. Create a list P of pairs of numbers which are the coordinates in the Poly-
bius square of the letters in msg.
2. Let L1 be the list of all first coordinates of P (length of L1 = n), let L2 be
the list of all second coordinates of P (so the length of L2 is also n).
3. Let L be the concatenation of L1 and L2 (length L = 2*n), except that
consecutive numbers are paired (L[2*i], L[2*i + 1]). You can regard
L as a list of pairs of length n.

354 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

4. Let C be the list of all letters which are of the form S[i, j], for all (i,
j) in L. As a string, this is the ciphertext of msg.

Examples

>>> from sympy.crypto.crypto import (

... encipher_bifid5, decipher_bifid5)

“J” will be omitted unless it is replaced with something else:

>>> round_trip = lambda m, k: \

... decipher_bifid5(encipher_bifid5(m, k), k)
>>> key = 'a'
>>> msg = ”JOSIE”
>>> round_trip(msg, key)
'OSIE'
>>> round_trip(msg.replace(”J”, ”I”), key)
'IOSIE'
>>> j = ”QIQ”
>>> round_trip(msg.replace(”J”, j), key).replace(j, ”J”)
'JOSIE'

sympy.crypto.crypto.decipher_bifid5(msg, key)
Return the Bifid cipher decryption of msg.
This is the version of the Bifid cipher that uses the 5 × 5 Polybius square; the letter “J” is
ignored unless a key of length 25 is used.
INPUT:
msg: ciphertext string
key: short string for key; duplicated characters are ignored and if the length is
less then 25 characters, it will be padded with other letters from the alphabet
omitting “J”. Non-alphabetic characters are ignored.
OUTPUT:
plaintext from Bifid5 cipher (all caps, no spaces)

Examples

>>> from sympy.crypto.crypto import encipher_bifid5, decipher_bifid5

>>> key = ”gold bug”
>>> encipher_bifid5('meet me on friday', key)
'IEILEHFSTSFXEE'
>>> encipher_bifid5('meet me on monday', key)
'IEILHHFSTSFQYE'
>>> decipher_bifid5(_, key)
'MEETMEONMONDAY'

sympy.crypto.crypto.bifid5_square(key=None)
5x5 Polybius square.
Produce the Polybius square for the 5 × 5 Bifid cipher.

5.4. Basic Cryptography Module 355

SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import bifid5_square

>>> bifid5_square(”gold bug”)
Matrix([
[G, O, L, D, B],
[U, A, C, E, F],
[H, I, K, M, N],
[P, Q, R, S, T],
[V, W, X, Y, Z]])

sympy.crypto.crypto.encipher_bifid6(msg, key)
Performs the Bifid cipher encryption on plaintext msg, and returns the ciphertext.
This is the version of the Bifid cipher that uses the 6 × 6 Polybius square.
INPUT:
msg: plaintext string (digits okay)
key: short string for key (digits okay). If key is less than 36 characters long,
the square will be filled with letters A through Z and digits 0 through 9.
OUTPUT:
ciphertext from Bifid cipher (all caps, no spaces)
See also:
decipher_bifid6 (page 356), encipher_bifid (page 352)
sympy.crypto.crypto.decipher_bifid6(msg, key)
Performs the Bifid cipher decryption on ciphertext msg, and returns the plaintext.
This is the version of the Bifid cipher that uses the 6 × 6 Polybius square.
INPUT:
msg: ciphertext string (digits okay); converted to upper case
key: short string for key (digits okay). If key is less than 36 characters long, the
square will be filled with letters A through Z and digits 0 through 9. All letters
are converted to uppercase.
OUTPUT:
plaintext from Bifid cipher (all caps, no spaces)

Examples

>>> from sympy.crypto.crypto import encipher_bifid6, decipher_bifid6

>>> key = ”gold bug”
>>> encipher_bifid6('meet me on monday at 8am', key)
'KFKLJJHF5MMMKTFRGPL'
>>> decipher_bifid6(_, key)
'MEETMEONMONDAYAT8AM'

sympy.crypto.crypto.bifid6_square(key=None)
6x6 Polybius square.

356 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Produces the Polybius square for the 6 × 6 Bifid cipher. Assumes alphabet of symbols is
“A”, …, “Z”, “0”, …, “9”.

Examples

>>> from sympy.crypto.crypto import bifid6_square

>>> key = ”gold bug”
>>> bifid6_square(key)
Matrix([
[G, O, L, D, B, U],
[A, C, E, F, H, I],
[J, K, M, N, P, Q],
[R, S, T, V, W, X],
[Y, Z, 0, 1, 2, 3],
[4, 5, 6, 7, 8, 9]])

sympy.crypto.crypto.rsa_public_key(p, q, e)
Return the RSA public key pair, (n, e), where n is a product of two primes and e is relatively
prime (coprime) to the Euler totient ϕ(n). False is returned if any assumption is violated.

Examples

>>> from sympy.crypto.crypto import rsa_public_key

>>> p, q, e = 3, 5, 7
>>> rsa_public_key(p, q, e)
(15, 7)
>>> rsa_public_key(p, q, 30)
False

sympy.crypto.crypto.rsa_private_key(p, q, e)
Return the RSA private key, (n, d), where n is a product of two primes and d is the inverse
of e (mod ϕ(n)). False is returned if any assumption is violated.

Examples

>>> from sympy.crypto.crypto import rsa_private_key

>>> p, q, e = 3, 5, 7
>>> rsa_private_key(p, q, e)
(15, 7)
>>> rsa_private_key(p, q, 30)
False

sympy.crypto.crypto.encipher_rsa(i, key)
Return encryption of i by computing ie (mod n), where key is the public key (n, e).

Examples

>>> from sympy.crypto.crypto import encipher_rsa, rsa_public_key

>>> p, q, e = 3, 5, 7
>>> puk = rsa_public_key(p, q, e)
(continues on next page)

5.4. Basic Cryptography Module 357

SymPy Documentation, Release 1.3

(continued from previous page)

>>> msg = 12
>>> encipher_rsa(msg, puk)
3

sympy.crypto.crypto.decipher_rsa(i, key)
Return decyption of i by computing id (mod n), where key is the private key (n, d).

Examples

>>> from sympy.crypto.crypto import decipher_rsa, rsa_private_key

>>> p, q, e = 3, 5, 7
>>> prk = rsa_private_key(p, q, e)
>>> msg = 3
>>> decipher_rsa(msg, prk)
12

sympy.crypto.crypto.kid_rsa_public_key(a, b, A, B)
Kid RSA is a version of RSA useful to teach grade school children since it does not involve
exponentiation.
Alice wants to talk to Bob. Bob generates keys as follows. Key generation:
• Select positive integers a, b, A, B at random.
• Compute M = ab − 1, e = AM + a, d = BM + b, n = (ed − 1)//M .
• The public key is (n, e). Bob sends these to Alice.
• The private key is (n, d), which Bob keeps secret.
Encryption: If p is the plaintext message then the ciphertext is c = pe (mod n).
Decryption: If c is the ciphertext message then the plaintext is p = cd (mod n).

Examples

>>> from sympy.crypto.crypto import kid_rsa_public_key

>>> a, b, A, B = 3, 4, 5, 6
>>> kid_rsa_public_key(a, b, A, B)
(369, 58)

sympy.crypto.crypto.kid_rsa_private_key(a, b, A, B)
Compute M = ab − 1, e = AM + a, d = BM + b, n = (ed − 1)/M . The private key is d, which
Bob keeps secret.

Examples

>>> from sympy.crypto.crypto import kid_rsa_private_key

>>> a, b, A, B = 3, 4, 5, 6
>>> kid_rsa_private_key(a, b, A, B)
(369, 70)

sympy.crypto.crypto.encipher_kid_rsa(msg, key)
Here msg is the plaintext and key is the public key.

358 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import (

... encipher_kid_rsa, kid_rsa_public_key)
>>> msg = 200
>>> a, b, A, B = 3, 4, 5, 6
>>> key = kid_rsa_public_key(a, b, A, B)
>>> encipher_kid_rsa(msg, key)
161

sympy.crypto.crypto.decipher_kid_rsa(msg, key)
Here msg is the plaintext and key is the private key.

Examples

>>> from sympy.crypto.crypto import (

... kid_rsa_public_key, kid_rsa_private_key,
... decipher_kid_rsa, encipher_kid_rsa)
>>> a, b, A, B = 3, 4, 5, 6
>>> d = kid_rsa_private_key(a, b, A, B)
>>> msg = 200
>>> pub = kid_rsa_public_key(a, b, A, B)
>>> pri = kid_rsa_private_key(a, b, A, B)
>>> ct = encipher_kid_rsa(msg, pub)
>>> decipher_kid_rsa(ct, pri)
200

sympy.crypto.crypto.encode_morse(msg, sep=’|’, mapping=None)

Encodes a plaintext into popular Morse Code with letters separated by sep and words by
a double sep.

References

[R82]

Examples

>>> from sympy.crypto.crypto import encode_morse

>>> msg = 'ATTACK RIGHT FLANK'
>>> encode_morse(msg)
'.-|-|-|.-|-.-.|-.-||.-.|..|--.|....|-||..-.|.-..|.-|-.|-.-'

sympy.crypto.crypto.decode_morse(msg, sep=’|’, mapping=None)

Decodes a Morse Code with letters separated by sep (default is ‘|’) and words by words ep
(default is ‘||) into plaintext.

References

[R83]

5.4. Basic Cryptography Module 359

SymPy Documentation, Release 1.3

Examples

>>> from sympy.crypto.crypto import decode_morse

>>> mc = '--|---|...-|.||.|.-|...|-'
>>> decode_morse(mc)
'MOVE EAST'

sympy.crypto.crypto.lfsr_sequence(key, fill, n)
This function creates an lfsr sequence.
INPUT:
key: a list of finite field elements, [c0 , c1 , . . . , ck ].
fill: the list of the initial terms of the lfsr sequence, [x0 , x1 , . . . , xk ].
n: number of terms of the sequence that the function returns.
OUTPUT:
The lfsr sequence defined by xn+1 = ck xn + . . . + c0 xn−k , for n ≤ k.

Notes

S. Golomb [G83] gives a list of three statistical properties a sequence of numbers a =

{an }∞
n=1 , an ∈ {0, 1}, should display to be considered “random”. Define the autocorrelation
of a to be

1 ∑
N
C(k) = C(k, a) = lim (−1)an +an+k .
N →∞ N
n=1

In the case where a is periodic with period P then this reduces to

1 ∑
P
C(k) = (−1)an +an+k .
P n=1

Assume a is periodic with period P .

• balance:
∑
P
(−1)an ≤ 1.
n=1

• low autocorrelation:

{
1, k = 0,
C(k) =
̸ 0.
ϵ, k =

(For sequences satisfying these first two properties, it is known that ϵ = −1/P must
hold.)
• proportional runs property: In each period, half the runs have length 1, one-fourth
have length 2, etc. Moreover, there are as many runs of 1’s as there are of 0’s.

360 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[G83]

Examples

>>> from sympy.crypto.crypto import lfsr_sequence

>>> from sympy.polys.domains import FF
>>> F = FF(2)
>>> fill = [F(1), F(1), F(0), F(1)]
>>> key = [F(1), F(0), F(0), F(1)]
>>> lfsr_sequence(key, fill, 10)
[1 mod 2, 1 mod 2, 0 mod 2, 1 mod 2, 0 mod 2,
1 mod 2, 1 mod 2, 0 mod 2, 0 mod 2, 1 mod 2]

sympy.crypto.crypto.lfsr_autocorrelation(L, P, k)
This function computes the LFSR autocorrelation function.
INPUT:
L: is a periodic sequence of elements of GF (2). L must have length larger than
P.
P: the period of L
k: an integer (0 < k < p)
OUTPUT:
the k-th value of the autocorrelation of the LFSR L

Examples

>>> from sympy.crypto.crypto import (

... lfsr_sequence, lfsr_autocorrelation)
>>> from sympy.polys.domains import FF
>>> F = FF(2)
>>> fill = [F(1), F(1), F(0), F(1)]
>>> key = [F(1), F(0), F(0), F(1)]
>>> s = lfsr_sequence(key, fill, 20)
>>> lfsr_autocorrelation(s, 15, 7)
-1/15
>>> lfsr_autocorrelation(s, 15, 0)
1

sympy.crypto.crypto.lfsr_connection_polynomial(s)
This function computes the LFSR connection polynomial.
INPUT:
s: a sequence of elements of even length, with entries in a finite field
OUTPUT:
C(x): the connection polynomial of a minimal LFSR yielding s.
This implements the algorithm in section 3 of J. L. Massey’s article [M84].

5.4. Basic Cryptography Module 361

SymPy Documentation, Release 1.3

References

[M84]

Examples

>>> from sympy.crypto.crypto import (

... lfsr_sequence, lfsr_connection_polynomial)
>>> from sympy.polys.domains import FF
>>> F = FF(2)
>>> fill = [F(1), F(1), F(0), F(1)]
>>> key = [F(1), F(0), F(0), F(1)]
>>> s = lfsr_sequence(key, fill, 20)
>>> lfsr_connection_polynomial(s)
x**4 + x + 1
>>> fill = [F(1), F(0), F(0), F(1)]
>>> key = [F(1), F(1), F(0), F(1)]
>>> s = lfsr_sequence(key, fill, 20)
>>> lfsr_connection_polynomial(s)
x**3 + 1
>>> fill = [F(1), F(0), F(1)]
>>> key = [F(1), F(1), F(0)]
>>> s = lfsr_sequence(key, fill, 20)
>>> lfsr_connection_polynomial(s)
x**3 + x**2 + 1
>>> fill = [F(1), F(0), F(1)]
>>> key = [F(1), F(0), F(1)]
>>> s = lfsr_sequence(key, fill, 20)
>>> lfsr_connection_polynomial(s)
x**3 + x + 1

sympy.crypto.crypto.elgamal_public_key(key)
Return three number tuple as public key.
Parameters key : Tuple (p, r, e) generated by elgamal_private_key
Returns (p, r, e = r**d mod p) : d is a random number in private key.

Examples

>>> from sympy.crypto.crypto import elgamal_public_key

>>> elgamal_public_key((1031, 14, 636))
(1031, 14, 212)

sympy.crypto.crypto.elgamal_private_key(digit=10, seed=None)
Return three number tuple as private key.
Elgamal encryption is based on the mathmatical problem called the Discrete Logarithm
Problem (DLP). For example,
ab ≡ c (mod p)
In general, if a and b are known, ct is easily calculated. If b is unknown, it is hard to use
a and ct to get b.
Parameters digit : minimum number of binary digits for key

362 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns (p, r, d) : p = prime number, r = primitive root, d = random number

Notes

For testing purposes, the seed parameter may be set to control the output of this routine.
See sympy.utilities.randtest._randrange.

Examples

>>> from sympy.crypto.crypto import elgamal_private_key

>>> from sympy.ntheory import is_primitive_root, isprime
>>> a, b, _ = elgamal_private_key()
>>> isprime(a)
True
>>> is_primitive_root(b, a)
True

sympy.crypto.crypto.encipher_elgamal(i, key, seed=None)

Encrypt message with public key
i is a plaintext message expressed as an integer. key is public key (p, r, e). In order to
encrypt a message, a random number a in range(2, p) is generated and the encryped
message is returned as c1 and c2 where:
c1 ≡ ra (mod p)
c2 ≡ mea (mod p)
Parameters msg : int of encoded message
key : public key
Returns (c1, c2) : Encipher into two number

Notes

For testing purposes, the seed parameter may be set to control the output of this routine.
See sympy.utilities.randtest._randrange.

Examples

>>> from sympy.crypto.crypto import encipher_elgamal, elgamal_private_key,␣

,→elgamal_public_key

>>> pri = elgamal_private_key(5, seed=[3]); pri

(37, 2, 3)
>>> pub = elgamal_public_key(pri); pub
(37, 2, 8)
>>> msg = 36
>>> encipher_elgamal(msg, pub, seed=[3])
(8, 6)

5.4. Basic Cryptography Module 363

SymPy Documentation, Release 1.3

sympy.crypto.crypto.decipher_elgamal(msg, key)
Decrypt message with private key
msg = (c1 , c2 )
key = (p, r, d)
According to extended Eucliden theorem, ucd1 + pn = 1
u ≡ 1/c1 d (mod p)
uc2 ≡ 1
cd
c2 ≡ 1
c
r ad 2
(mod p)
1

1
r ad
mea ≡ 1
r ad
mrda ≡ m (mod p)

Examples

>>> from sympy.crypto.crypto import decipher_elgamal

>>> from sympy.crypto.crypto import encipher_elgamal
>>> from sympy.crypto.crypto import elgamal_private_key
>>> from sympy.crypto.crypto import elgamal_public_key

>>> pri = elgamal_private_key(5, seed=[3])

>>> pub = elgamal_public_key(pri); pub
(37, 2, 8)
>>> msg = 17
>>> decipher_elgamal(encipher_elgamal(msg, pub), pri) == msg
True

sympy.crypto.crypto.dh_public_key(key)
Return three number tuple as public key.
This is the tuple that Alice sends to Bob.
Parameters key: Tuple (p, g, a) generated by ‘‘dh_private_key‘‘
Returns (p, g, g^a mod p) : p, g and a as in Parameters

Examples

>>> from sympy.crypto.crypto import dh_private_key, dh_public_key

>>> p, g, a = dh_private_key();
>>> _p, _g, x = dh_public_key((p, g, a))
>>> p == _p and g == _g
True
>>> x == pow(g, a, p)
True

sympy.crypto.crypto.dh_private_key(digit=10, seed=None)
Return three integer tuple as private key.
Diffie-Hellman key exchange is based on the mathematical problem called the Discrete
Logarithm Problem (see ElGamal).
Diffie-Hellman key exchange is divided into the following steps:
• Alice and Bob agree on a base that consist of a prime p and a primitive root of p
called g

364 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• Alice choses a number a and Bob choses a number b where a and b are random
numbers in range [2, p). These are their private keys.
• Alice then publicly sends Bob g a (mod p) while Bob sends Alice g b (mod p)
• They both raise the received value to their secretly chosen number (a or b) and now
have both as their shared key g ab (mod p)

Parameters digit: minimum number of binary digits required in key

Returns (p, g, a) : p = prime number, g = primitive root of p,
a = random number from 2 through p - 1

Notes

For testing purposes, the seed parameter may be set to control the output of this routine.
See sympy.utilities.randtest._randrange.

Examples

>>> from sympy.crypto.crypto import dh_private_key

>>> from sympy.ntheory import isprime, is_primitive_root
>>> p, g, _ = dh_private_key()
>>> isprime(p)
True
>>> is_primitive_root(g, p)
True
>>> p, g, _ = dh_private_key(5)
>>> isprime(p)
True
>>> is_primitive_root(g, p)
True

sympy.crypto.crypto.dh_shared_key(key, b)
Return an integer that is the shared key.
This is what Bob and Alice can both calculate using the public keys they received from
each other and their private keys.
Parameters key: Tuple (p, g, x) generated by ‘‘dh_public_key‘‘
b: Random number in the range of 2 to p - 1
(Chosen by second key exchange member (Bob))
Returns shared key (int)

Examples

>>> from sympy.crypto.crypto import (

... dh_private_key, dh_public_key, dh_shared_key)
>>> prk = dh_private_key();
>>> p, g, x = dh_public_key(prk);
>>> sk = dh_shared_key((p, g, x), 1000)
(continues on next page)

5.4. Basic Cryptography Module 365

SymPy Documentation, Release 1.3

(continued from previous page)

>>> sk == pow(x, 1000, p)
True

sympy.crypto.crypto.encipher_elgamal(i, key, seed=None)

Encrypt message with public key
i is a plaintext message expressed as an integer. key is public key (p, r, e). In order to
encrypt a message, a random number a in range(2, p) is generated and the encryped
message is returned as c1 and c2 where:
c1 ≡ ra (mod p)
c2 ≡ mea (mod p)
Parameters msg : int of encoded message
key : public key
Returns (c1, c2) : Encipher into two number

Notes

For testing purposes, the seed parameter may be set to control the output of this routine.
See sympy.utilities.randtest._randrange.

Examples

>>> from sympy.crypto.crypto import encipher_elgamal, elgamal_private_key,␣

,→elgamal_public_key

>>> pri = elgamal_private_key(5, seed=[3]); pri

(37, 2, 3)
>>> pub = elgamal_public_key(pri); pub
(37, 2, 8)
>>> msg = 36
>>> encipher_elgamal(msg, pub, seed=[3])
(8, 6)

sympy.crypto.crypto.decipher_elgamal(msg, key)
Decrypt message with private key
msg = (c1 , c2 )
key = (p, r, d)
According to extended Eucliden theorem, ucd1 + pn = 1
u ≡ 1/c1 d (mod p)
uc2 ≡ 1
cd
c2 ≡ 1
c
r ad 2
(mod p)
1

1
r ad
mea ≡ 1
r ad
mrda ≡ m (mod p)

Examples

366 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.crypto.crypto import decipher_elgamal

>>> from sympy.crypto.crypto import encipher_elgamal
>>> from sympy.crypto.crypto import elgamal_private_key
>>> from sympy.crypto.crypto import elgamal_public_key

>>> pri = elgamal_private_key(5, seed=[3])

>>> pub = elgamal_public_key(pri); pub
(37, 2, 8)
>>> msg = 17
>>> decipher_elgamal(encipher_elgamal(msg, pub), pri) == msg
True

sympy.crypto.crypto.gm_public_key(p, q, a=None, seed=None)

Compute public keys for p and q. Note that in Goldwasser-Micali Encrpytion, public keys
are randomly selected.
Parameters p, q, a : (int) initialization variables
Returns (a, N) : tuple[int]
a is the input a if it is not None otherwise some random integer co-
prime to p and q.
N is the product of p and q
sympy.crypto.crypto.gm_private_key(p, q, a=None)
Check if p and q can be used as private keys for the Goldwasser-Micali encryption. The
method works roughly as follows.
Pick two large primes p ands q. Call their product N. Given a message as an integer i,
write i in its bit representation b_0,…,b_n. For each k,
if b_k = 0: let a_k be a random square (quadratic residue) modulo p * q such
that jacobi_symbol(a, p * q) = 1
if b_k = 1: let a_k be a random non-square (non-quadratic residue) modulo p *
q such that jacobi_symbol(a, p * q) = 1
return [a_1, a_2,…]
b_k can be recovered by checking whether or not a_k is a residue. And from the b_k’s,
the message can be reconstructed.
The idea is that, while jacobi_symbol(a, p * q) can be easily computed (and when it is
equal to -1 will tell you that a is not a square mod p * q), quadratic residuosity modulo a
composite number is hard to compute without knowing its factorization.
Moreover, approximately half the numbers coprime to p * q have jacobi_symbol equal
to 1. And among those, approximately half are residues and approximately half are not.
This maximizes the entropy of the code.
Parameters p, q, a : initialization variables
Returns p, q : the input value p and q
Raises ValueError : if p and q are not distinct odd primes
sympy.crypto.crypto.encipher_gm(i, key, seed=None)
Encrypt integer ‘i’ using public_key ‘key’ Note that gm uses random encrpytion.
Parameters i: (int) the message to encrypt
key: Tuple (a, N) the public key

5.4. Basic Cryptography Module 367

SymPy Documentation, Release 1.3

Returns List[int] the randomized encrpyted message.

sympy.crypto.crypto.decipher_gm(message, key)
Decrypt message ‘message’ using public_key ‘key’.
Parameters List[int]: the randomized encrpyted message.
key: Tuple (p, q) the private key
Returns i (int) the encrpyted message

5.5 Concrete Mathematics

5.5.1 Hypergeometric terms

The center stage, in recurrence solving and summations, play hypergeometric terms. For-
mally these are sequences annihilated by first order linear recurrence operators. In simple
words if we are given term a(n) then it is hypergeometric if its consecutive term ratio is a
rational function in n.
To check if a sequence is of this type you can use the is_hypergeometric method which is
available in Basic class. Here is simple example involving a polynomial:

>>> from sympy import *

>>> n, k = symbols('n,k')
>>> (n**2 + 1).is_hypergeometric(n)
True

Of course polynomials are hypergeometric but are there any more complicated sequences of
this type? Here are some trivial examples:

>>> factorial(n).is_hypergeometric(n)
True
>>> binomial(n, k).is_hypergeometric(n)
True
>>> rf(n, k).is_hypergeometric(n)
True
>>> ff(n, k).is_hypergeometric(n)
True
>>> gamma(n).is_hypergeometric(n)
True
>>> (2**n).is_hypergeometric(n)
True

We see that all species used in summations and other parts of concrete mathematics are
hypergeometric. Note also that binomial coefficients and both rising and falling factorials
are hypergeometric in both their arguments:

>>> binomial(n, k).is_hypergeometric(k)

True
>>> rf(n, k).is_hypergeometric(k)
True
>>> ff(n, k).is_hypergeometric(k)
True

To say more, all previously shown examples are valid for integer linear arguments:

368 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> factorial(2*n).is_hypergeometric(n)
True
>>> binomial(3*n+1, k).is_hypergeometric(n)
True
>>> rf(n+1, k-1).is_hypergeometric(n)
True
>>> ff(n-1, k+1).is_hypergeometric(n)
True
>>> gamma(5*n).is_hypergeometric(n)
True
>>> (2**(n-7)).is_hypergeometric(n)
True

However nonlinear arguments make those sequences fail to be hypergeometric:

>>> factorial(n**2).is_hypergeometric(n)
False
>>> (2**(n**3 + 1)).is_hypergeometric(n)
False

If not only the knowledge of being hypergeometric or not is needed, you can use hypersimp()
function. It will try to simplify combinatorial expression and if the term given is hypergeo-
metric it will return a quotient of polynomials of minimal degree. Otherwise is will return
N one to say that sequence is not hypergeometric:

>>> hypersimp(factorial(2*n), n)
2*(n + 1)*(2*n + 1)
>>> hypersimp(factorial(n**2), n)

5.5.2 Concrete Class Reference

class sympy.concrete.summations.Sum
Represents unevaluated summation.
Sum represents a finite or infinite series, with the first argument being the general form
of terms in the series, and the second argument being (dummy_variable, start, end),
with dummy_variable taking all integer values from start through end. In accordance
with long-standing mathematical convention, the end term is included in the summation.
See also:
summation (page 379), Product, product

References

[R37], [R38], [R39]

Examples

>>> from sympy.abc import i, k, m, n, x

>>> from sympy import Sum, factorial, oo, IndexedBase, Function
>>> Sum(k, (k, 1, m))
(continues on next page)

5.5. Concrete Mathematics 369

SymPy Documentation, Release 1.3

(continued from previous page)

Sum(k, (k, 1, m))
>>> Sum(k, (k, 1, m)).doit()
m**2/2 + m/2
>>> Sum(k**2, (k, 1, m))
Sum(k**2, (k, 1, m))
>>> Sum(k**2, (k, 1, m)).doit()
m**3/3 + m**2/2 + m/6
>>> Sum(x**k, (k, 0, oo))
Sum(x**k, (k, 0, oo))
>>> Sum(x**k, (k, 0, oo)).doit()
Piecewise((1/(-x + 1), Abs(x) < 1), (Sum(x**k, (k, 0, oo)), True))
>>> Sum(x**k/factorial(k), (k, 0, oo)).doit()
exp(x)

Here are examples to do summation with symbolic indices. You can use either Function
of IndexedBase classes:

>>> f = Function('f')
>>> Sum(f(n), (n, 0, 3)).doit()
f(0) + f(1) + f(2) + f(3)
>>> Sum(f(n), (n, 0, oo)).doit()
Sum(f(n), (n, 0, oo))
>>> f = IndexedBase('f')
>>> Sum(f[n]**2, (n, 0, 3)).doit()
f[0]**2 + f[1]**2 + f[2]**2 + f[3]**2

An example showing that the symbolic result of a summation is still valid for seemingly
nonsensical values of the limits. Then the Karr convention allows us to give a perfectly
valid interpretation to those sums by interchanging the limits according to the above
rules:

>>> S = Sum(i, (i, 1, n)).doit()

>>> S
n**2/2 + n/2
>>> S.subs(n, -4)
6
>>> Sum(i, (i, 1, -4)).doit()
6
>>> Sum(-i, (i, -3, 0)).doit()
6

An explicit example of the Karr summation convention:

>>> S1 = Sum(i**2, (i, m, m+n-1)).doit()

>>> S1
m**2*n + m*n**2 - m*n + n**3/3 - n**2/2 + n/6
>>> S2 = Sum(i**2, (i, m+n, m-1)).doit()
>>> S2
-m**2*n - m*n**2 + m*n - n**3/3 + n**2/2 - n/6
>>> S1 + S2
0
>>> S3 = Sum(i, (i, m, m-1)).doit()
>>> S3
0

370 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Finite Sums

For finite sums (and sums with symbolic limits assumed to be finite) we follow the sum-
mation convention described by Karr [1], especially definition 3 of section 1.4. The sum:
∑
f (i)
m≤i<n

has the obvious meaning for m < n, namely:

∑
f (i) = f (m) + f (m + 1) + . . . + f (n − 2) + f (n − 1)
m≤i<n

with the upper limit value f (n) excluded. The sum over an empty set is zero if and only
if m = n:
∑
f (i) = 0 for m = n
m≤i<n

Finally, for all other sums over empty sets we assume the following definition:
∑ ∑
f (i) = − f (i) for m > n
m≤i<n n≤i<m

It is important to note that Karr defines all sums with the upper limit being exclusive.
This is in contrast to the usual mathematical notation, but does not affect the summation
convention. Indeed we have:
∑ ∑
n−1
f (i) = f (i)
m≤i<n i=m

where the difference in notation is intentional to emphasize the meaning, with limits
typeset on the top being inclusive.
euler_maclaurin(m=0, n=0, eps=0, eval_integral=True)
Return an Euler-Maclaurin approximation of self, where m is the number of leading
terms to sum directly and n is the number of terms in the tail.
With m = n = 0, this is simply the corresponding integral plus a first-order endpoint
correction.
Returns (s, e) where s is the Euler-Maclaurin approximation and e is the estimated
error (taken to be the magnitude of the first omitted term in the tail):

>>> from sympy.abc import k, a, b

>>> from sympy import Sum
>>> Sum(1/k, (k, 2, 5)).doit().evalf()
1.28333333333333
>>> s, e = Sum(1/k, (k, 2, 5)).euler_maclaurin()
>>> s
-log(2) + 7/20 + log(5)
>>> from sympy import sstr
>>> print(sstr((s.evalf(), e.evalf()), full_prec=True))
(1.26629073187415, 0.0175000000000000)

The endpoints may be symbolic:

5.5. Concrete Mathematics 371

SymPy Documentation, Release 1.3

>>> s, e = Sum(1/k, (k, a, b)).euler_maclaurin()

>>> s
-log(a) + log(b) + 1/(2*b) + 1/(2*a)
>>> e
Abs(1/(12*b**2) - 1/(12*a**2))

If the function is a polynomial of degree at most 2n+1, the Euler-Maclaurin formula

becomes exact (and e = 0 is returned):

>>> Sum(k, (k, 2, b)).euler_maclaurin()

(b**2/2 + b/2 - 1, 0)
>>> Sum(k, (k, 2, b)).doit()
b**2/2 + b/2 - 1

With a nonzero eps specified, the summation is ended as soon as the remainder term
is less than the epsilon.
eval_zeta_function(f, limits)
Check whether the function matches with the zeta function. If it matches, then
return a P iecewise expression because zeta function does not converge unless s > 1
and q > 0
is_absolutely_convergent()
Checks for the absolute convergence of an infinite series.
Same as checking convergence of absolute value of sequence_term of an infinite
series.
See also:
Sum.is_convergent (page 372)

References

[R40]

Examples

>>> from sympy import Sum, Symbol, sin, oo

>>> n = Symbol('n', integer=True)
>>> Sum((-1)**n, (n, 1, oo)).is_absolutely_convergent()
False
>>> Sum((-1)**n/n**2, (n, 1, oo)).is_absolutely_convergent()
True

is_convergent()
Checks for the convergence of a Sum.
We divide the study of convergence of infinite sums and products in two parts.
First Part: One part is the question whether all the terms are well defined, i.e., they
are finite in a sum and also non-zero in a product. Zero is the analogy of (minus)
infinity in products as e−∞ = 0.
Second Part: The second part is the question of convergence after infinities, and
zeros in products, have been omitted assuming that their number is finite. This

372 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

means that we only consider the tail of the sum or product, starting from some point
after which all terms are well defined.
For example, in a sum of the form:
∑ 1
n2 + an + b
1≤i<∞

where a and b are numbers. The routine will return true, even if there are infinities
in the term sequence (at most two). An analogous product would be:
∏ 1
e n2 +an+b
1≤i<∞

This is how convergence is interpreted. It is concerned with what happens at the

limit. Finding the bad terms is another independent matter.
Note: It is responsibility of user to see that the sum or product is well defined.
There are various tests employed to check the convergence like divergence test,
root test, integral test, alternating series test, comparison tests, Dirichlet tests. It
returns true if Sum is convergent and false if divergent and NotImplementedError
if it can not be checked.
See also:
Sum.is_absolutely_convergent (page 372), Product.is_convergent

References

[R41]

Examples

>>> from sympy import factorial, S, Sum, Symbol, oo

>>> n = Symbol('n', integer=True)
>>> Sum(n/(n - 1), (n, 4, 7)).is_convergent()
True
>>> Sum(n/(2*n + 1), (n, 1, oo)).is_convergent()
False
>>> Sum(factorial(n)/5**n, (n, 1, oo)).is_convergent()
False
>>> Sum(1/n**(S(6)/5), (n, 1, oo)).is_convergent()
True

reverse_order(*indices)
Reverse the order of a limit in a Sum.
See also:
index, reorder_limit, reorder

References

[R42]

5.5. Concrete Mathematics 373

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Sum

>>> from sympy.abc import x, y, a, b, c, d

>>> Sum(x, (x, 0, 3)).reverse_order(x)

Sum(-x, (x, 4, -1))
>>> Sum(x*y, (x, 1, 5), (y, 0, 6)).reverse_order(x, y)
Sum(x*y, (x, 6, 0), (y, 7, -1))
>>> Sum(x, (x, a, b)).reverse_order(x)
Sum(-x, (x, b + 1, a - 1))
>>> Sum(x, (x, a, b)).reverse_order(0)
Sum(-x, (x, b + 1, a - 1))

While one should prefer variable names when specifying which limits to reverse, the
index counting notation comes in handy in case there are several symbols with the
same name.

>>> S = Sum(x**2, (x, a, b), (x, c, d))

>>> S
Sum(x**2, (x, a, b), (x, c, d))
>>> S0 = S.reverse_order(0)
>>> S0
Sum(-x**2, (x, b + 1, a - 1), (x, c, d))
>>> S1 = S0.reverse_order(1)
>>> S1
Sum(x**2, (x, b + 1, a - 1), (x, d + 1, c - 1))

Of course we can mix both notations:

>>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(x, 1)

Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
>>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(y, x)
Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))

Usage

reverse_order(self, *indices) reverses some limits in the expression self

which can be either a Sum or a Product. The selectors in the argument indices
specify some indices whose limits get reversed. These selectors are either variable
names or numerical indices counted starting from the inner-most limit tuple.
class sympy.concrete.products.Product
Represents unevaluated products.
Product represents a finite or infinite product, with the first argument being the general
form of terms in the series, and the second argument being (dummy_variable, start,
end), with dummy_variable taking all integer values from start through end. In ac-
cordance with long-standing mathematical convention, the end term is included in the
product.
See also:
Sum, summation, product (page 380)

374 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R43], [R44], [R45]

Examples

>>> from sympy.abc import a, b, i, k, m, n, x

>>> from sympy import Product, factorial, oo
>>> Product(k, (k, 1, m))
Product(k, (k, 1, m))
>>> Product(k, (k, 1, m)).doit()
factorial(m)
>>> Product(k**2,(k, 1, m))
Product(k**2, (k, 1, m))
>>> Product(k**2,(k, 1, m)).doit()
factorial(m)**2

Wallis’ product for pi:

>>> W = Product(2*i/(2*i-1) * 2*i/(2*i+1), (i, 1, oo))
>>> W
Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, oo))

Direct computation currently fails:

>>> W.doit()
Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, oo))

But we can approach the infinite product by a limit of finite products:

>>> from sympy import limit
>>> W2 = Product(2*i/(2*i-1)*2*i/(2*i+1), (i, 1, n))
>>> W2
Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, n))
>>> W2e = W2.doit()
>>> W2e
2**(-2*n)*4**n*factorial(n)**2/(RisingFactorial(1/2, n)*RisingFactorial(3/2, n))
>>> limit(W2e, n, oo)
pi/2

By the same formula we can compute sin(pi/2):

>>> from sympy import pi, gamma, simplify
>>> P = pi * x * Product(1 - x**2/k**2, (k, 1, n))
>>> P = P.subs(x, pi/2)
>>> P
pi**2*Product(1 - pi**2/(4*k**2), (k, 1, n))/2
>>> Pe = P.doit()
>>> Pe
pi**2*RisingFactorial(1 + pi/2, n)*RisingFactorial(-pi/2 + 1, n)/
,→(2*factorial(n)**2)

>>> Pe = Pe.rewrite(gamma)
>>> Pe
pi**2*gamma(n + 1 + pi/2)*gamma(n - pi/2 + 1)/(2*gamma(1 + pi/2)*gamma(-pi/2 +␣
,→1)*gamma(n + 1)**2)

>>> Pe = simplify(Pe)
(continues on next page)

5.5. Concrete Mathematics 375

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Pe
sin(pi**2/2)*gamma(n + 1 + pi/2)*gamma(n - pi/2 + 1)/gamma(n + 1)**2
>>> limit(Pe, n, oo)
sin(pi**2/2)

Products with the lower limit being larger than the upper one:

>>> Product(1/i, (i, 6, 1)).doit()

120
>>> Product(i, (i, 2, 5)).doit()
120

The empty product:

>>> Product(i, (i, n, n-1)).doit()

1

An example showing that the symbolic result of a product is still valid for seemingly
nonsensical values of the limits. Then the Karr convention allows us to give a perfectly
valid interpretation to those products by interchanging the limits according to the above
rules:

>>> P = Product(2, (i, 10, n)).doit()

>>> P
2**(n - 9)
>>> P.subs(n, 5)
1/16
>>> Product(2, (i, 10, 5)).doit()
1/16
>>> 1/Product(2, (i, 6, 9)).doit()
1/16

An explicit example of the Karr summation convention applied to products:

>>> P1 = Product(x, (i, a, b)).doit()

>>> P1
x**(-a + b + 1)
>>> P2 = Product(x, (i, b+1, a-1)).doit()
>>> P2
x**(a - b - 1)
>>> simplify(P1 * P2)
1

And another one:

>>> P1 = Product(i, (i, b, a)).doit()

>>> P1
RisingFactorial(b, a - b + 1)
>>> P2 = Product(i, (i, a+1, b-1)).doit()
>>> P2
RisingFactorial(a + 1, -a + b - 1)
>>> P1 * P2
RisingFactorial(b, a - b + 1)*RisingFactorial(a + 1, -a + b - 1)
>>> simplify(P1 * P2)
1

376 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Finite Products

For finite products (and products with symbolic limits assumed to be finite) we follow
the analogue of the summation convention described by Karr [1], especially definition 3
of section 1.4. The product:
∏
f (i)
m≤i<n

has the obvious meaning for m < n, namely:

∏
f (i) = f (m)f (m + 1) · . . . · f (n − 2)f (n − 1)
m≤i<n

with the upper limit value f (n) excluded. The product over an empty set is one if and
only if m = n:
∏
f (i) = 1 for m = n
m≤i<n

Finally, for all other products over empty sets we assume the following definition:
∏ 1
f (i) = ∏ for m > n
m≤i<n n≤i<m f (i)

It is important to note that above we define all products with the upper limit being ex-
clusive. This is in contrast to the usual mathematical notation, but does not affect the
product convention. Indeed we have:
∏ ∏
n−1
f (i) = f (i)
m≤i<n i=m

where the difference in notation is intentional to emphasize the meaning, with limits
typeset on the top being inclusive.
is_convergent()
See docs of Sum.is_convergent() for explanation of convergence in SymPy.
The infinite product:
∏
f (i)
1≤i<∞

is defined by the sequence of partial products:

∏
n
f (i) = f (1)f (2) · · · f (n)
i=1

as n increases without bound. The product converges to a non-zero value if and only
if the sum:
∑
log f (n)
1≤i<∞

converges.

References

[R46]

5.5. Concrete Mathematics 377

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Interval, S, Product, Symbol, cos, pi, exp, oo
>>> n = Symbol('n', integer=True)
>>> Product(n/(n + 1), (n, 1, oo)).is_convergent()
False
>>> Product(1/n**2, (n, 1, oo)).is_convergent()
False
>>> Product(cos(pi/n), (n, 1, oo)).is_convergent()
True
>>> Product(exp(-n**2), (n, 1, oo)).is_convergent()
False

reverse_order(*indices)
Reverse the order of a limit in a Product.
See also:
index, reorder_limit, reorder

References

[R47]

Examples

>>> from sympy import Product, simplify, RisingFactorial, gamma, Sum

>>> from sympy.abc import x, y, a, b, c, d
>>> P = Product(x, (x, a, b))
>>> Pr = P.reverse_order(x)
>>> Pr
Product(1/x, (x, b + 1, a - 1))
>>> Pr = Pr.doit()
>>> Pr
1/RisingFactorial(b + 1, a - b - 1)
>>> simplify(Pr)
gamma(b + 1)/gamma(a)
>>> P = P.doit()
>>> P
RisingFactorial(a, -a + b + 1)
>>> simplify(P)
gamma(b + 1)/gamma(a)

While one should prefer variable names when specifying which limits to reverse, the
index counting notation comes in handy in case there are several symbols with the
same name.

>>> S = Sum(x*y, (x, a, b), (y, c, d))

>>> S
Sum(x*y, (x, a, b), (y, c, d))
>>> S0 = S.reverse_order(0)
>>> S0
Sum(-x*y, (x, b + 1, a - 1), (y, c, d))
>>> S1 = S0.reverse_order(1)
(continues on next page)

378 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> S1
Sum(x*y, (x, b + 1, a - 1), (y, d + 1, c - 1))

Of course we can mix both notations:

>>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(x, 1)

Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
>>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(y, x)
Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))

Usage

reverse_order(expr, *indices) reverses some limits in the expression expr

which can be either a Sum or a Product. The selectors in the argument indices
specify some indices whose limits get reversed. These selectors are either variable
names or numerical indices counted starting from the inner-most limit tuple.

5.5.3 Concrete Functions Reference

sympy.concrete.summations.summation(f, *symbols, **kwargs)

Compute the summation of f with respect to symbols.
The notation for symbols is similar to the notation used in Integral. summation(f, (i, a,
b)) computes the sum of f with respect to i from a to b, i.e.,

b
____
\ `
summation(f, (i, a, b)) = ) f
/___,
i = a

If it cannot compute the sum, it returns an unevaluated Sum object. Repeated sums can
be computed by introducing additional symbols tuples:

>>> from sympy import summation, oo, symbols, log

>>> i, n, m = symbols('i n m', integer=True)

>>> summation(2*i - 1, (i, 1, n))

n**2
>>> summation(1/2**i, (i, 0, oo))
2
>>> summation(1/log(n)**n, (n, 2, oo))
Sum(log(n)**(-n), (n, 2, oo))
>>> summation(i, (i, 0, n), (n, 0, m))
m**3/6 + m**2/2 + m/3

>>> from sympy.abc import x

>>> from sympy import factorial
>>> summation(x**n/factorial(n), (n, 0, oo))
exp(x)

5.5. Concrete Mathematics 379

SymPy Documentation, Release 1.3

See also:
Sum (page 369), Product, product
sympy.concrete.products.product(*args, **kwargs)
Compute the product.
The notation for symbols is similar to the notation used in Sum or Integral. product(f, (i,
a, b)) computes the product of f with respect to i from a to b, i.e.,

b
_____
product(f(n), (i, a, b)) = | | f(n)
| |
i = a

If it cannot compute the product, it returns an unevaluated Product object. Repeated

products can be computed by introducing additional symbols tuples:

>>> from sympy import product, symbols

>>> i, n, m, k = symbols('i n m k', integer=True)

>>> product(i, (i, 1, k))

factorial(k)
>>> product(m, (i, 1, k))
m**k
>>> product(i, (i, 1, k), (k, 1, n))
Product(factorial(k), (k, 1, n))

sympy.concrete.gosper.gosper_normal(f, g, n, polys=True)
Compute the Gosper’s normal form of f and g.
Given relatively prime univariate polynomials f and g, rewrite their quotient to a normal
form defined as follows:
f (n) A(n)C(n + 1)
=Z·
g(n) B(n)C(n)

where Z is an arbitrary constant and A, B, C are monic polynomials in n with the following
properties:
1. gcd(A(n), B(n + h)) = 1∀h ∈ N
2. gcd(B(n), C(n + 1)) = 1
3. gcd(A(n), C(n)) = 1
This normal form, or rational factorization in other words, is a crucial step in Gosper’s
algorithm and in solving of difference equations. It can be also used to decide if two
hypergeometric terms are similar or not.
This procedure will return a tuple containing elements of this factorization in the form
(Z*A, B, C).

Examples

>>> from sympy.concrete.gosper import gosper_normal

>>> from sympy.abc import n

380 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> gosper_normal(4*n+5, 2*(4*n+1)*(2*n+3), n, polys=False)

(1/4, n + 3/2, n + 1/4)

sympy.concrete.gosper.gosper_term(f, n)
Compute Gosper’s hypergeometric term for f.
Suppose f is a hypergeometric term such that:
∑
n−1
sn = fk
k=0

and fk doesn’t depend on n. Returns a hypergeometric term gn such that gn+1 − gn = fn .

Examples

>>> from sympy.concrete.gosper import gosper_term

>>> from sympy.functions import factorial
>>> from sympy.abc import n

>>> gosper_term((4*n + 1)*factorial(n)/factorial(2*n + 1), n)

(-n - 1/2)/(n + 1/4)

sympy.concrete.gosper.gosper_sum(f, k)
Gosper’s hypergeometric summation algorithm.
Given a hypergeometric term f such that:
∑
n−1
sn = fk
k=0

and f (n) doesn’t depend on n, returns gn − g(0) where gn+1 − gn = fn , or None if sn can not
be expressed in closed form as a sum of hypergeometric terms.

References

[R48]

Examples

>>> from sympy.concrete.gosper import gosper_sum

>>> from sympy.functions import factorial
>>> from sympy.abc import i, n, k

>>> f = (4*k + 1)*factorial(k)/factorial(2*k + 1)

>>> gosper_sum(f, (k, 0, n))
(-factorial(n) + 2*factorial(2*n + 1))/factorial(2*n + 1)
>>> _.subs(n, 2) == sum(f.subs(k, i) for i in [0, 1, 2])
True
>>> gosper_sum(f, (k, 3, n))
(-60*factorial(n) + factorial(2*n + 1))/(60*factorial(2*n + 1))
>>> _.subs(n, 5) == sum(f.subs(k, i) for i in [3, 4, 5])
True

5.5. Concrete Mathematics 381

SymPy Documentation, Release 1.3

5.6 Discrete Module

The discrete module in SymPy implements methods to compute discrete transforms and
convolutions of finite sequences.
This module contains functions which operate on discrete sequences.
Transforms - fft, ifft, ntt, intt, fwht, ifwht, mobius_transform, in-
verse_mobius_transform
Convolutions - convolution, convolution_fft, convolution_ntt, convolution_fwht,
convolution_subset, covering_product, intersecting_product
Since the discrete transforms can be used to reduce the computational complexity of the
discrete convolutions, the convolutions module makes use of the transforms module for
efficient computation (notable for long input sequences).

5.6.1 Transforms

This section lists the methods which implement the basic transforms for discrete sequences.

Fast Fourier Transform

sympy.discrete.transforms.fft(seq, dps=None)
Performs the Discrete Fourier Transform (DFT) in the complex domain.
The sequence is automatically padded to the right with zeros, as the radix-2 FFT requires
the number of sample points to be a power of 2.
This method should be used with default arguments only for short sequences as the
complexity of expressions increases with the size of the sequence.
Parameters seq : iterable
The sequence on which DFT is to be applied.
dps : Integer
Specifies the number of decimal digits for precision.

References

[R86], [R87]

Examples

>>> from sympy import fft, ifft

>>> fft([1, 2, 3, 4])

[10, -2 - 2*I, -2, -2 + 2*I]
>>> ifft(_)
[1, 2, 3, 4]

382 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> ifft([1, 2, 3, 4])

[5/2, -1/2 + I/2, -1/2, -1/2 - I/2]
>>> fft(_)
[1, 2, 3, 4]

>>> ifft([1, 7, 3, 4], dps=15)

[3.75, -0.5 - 0.75*I, -1.75, -0.5 + 0.75*I]
>>> fft(_)
[1.0, 7.0, 3.0, 4.0]

sympy.discrete.transforms.ifft(seq, dps=None)
Performs the Discrete Fourier Transform (DFT) in the complex domain.
The sequence is automatically padded to the right with zeros, as the radix-2 FFT requires
the number of sample points to be a power of 2.
This method should be used with default arguments only for short sequences as the
complexity of expressions increases with the size of the sequence.
Parameters seq : iterable
The sequence on which DFT is to be applied.
dps : Integer
Specifies the number of decimal digits for precision.

References

[R88], [R89]

Examples

>>> from sympy import fft, ifft

>>> fft([1, 2, 3, 4])

[10, -2 - 2*I, -2, -2 + 2*I]
>>> ifft(_)
[1, 2, 3, 4]

>>> ifft([1, 2, 3, 4])

[5/2, -1/2 + I/2, -1/2, -1/2 - I/2]
>>> fft(_)
[1, 2, 3, 4]

>>> ifft([1, 7, 3, 4], dps=15)

[3.75, -0.5 - 0.75*I, -1.75, -0.5 + 0.75*I]
>>> fft(_)
[1.0, 7.0, 3.0, 4.0]

5.6. Discrete Module 383

SymPy Documentation, Release 1.3

Number Theoretic Transform

sympy.discrete.transforms.ntt(seq, prime)
Performs the Number Theoretic Transform (NTT), which specializes the Discrete Fourier
Transform (DFT) over quotient ring Z/pZ for prime p instead of complex numbers C.
The sequence is automatically padded to the right with zeros, as the radix-2 NTT requires
the number of sample points to be a power of 2.
Parameters seq : iterable
The sequence on which DFT is to be applied.
prime : Integer
Prime modulus of the form (m2k + 1) to be used for performing NTT
on the sequence.

References

[R90], [R91], [R92]

Examples

>>> from sympy import ntt, intt

>>> ntt([1, 2, 3, 4], prime=3*2**8 + 1)
[10, 643, 767, 122]
>>> intt(_, 3*2**8 + 1)
[1, 2, 3, 4]
>>> intt([1, 2, 3, 4], prime=3*2**8 + 1)
[387, 415, 384, 353]
>>> ntt(_, prime=3*2**8 + 1)
[1, 2, 3, 4]

sympy.discrete.transforms.intt(seq, prime)
Performs the Number Theoretic Transform (NTT), which specializes the Discrete Fourier
Transform (DFT) over quotient ring Z/pZ for prime p instead of complex numbers C.
The sequence is automatically padded to the right with zeros, as the radix-2 NTT requires
the number of sample points to be a power of 2.
Parameters seq : iterable
The sequence on which DFT is to be applied.
prime : Integer
Prime modulus of the form (m2k + 1) to be used for performing NTT
on the sequence.

References

[R93], [R94], [R95]

384 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import ntt, intt

>>> ntt([1, 2, 3, 4], prime=3*2**8 + 1)
[10, 643, 767, 122]
>>> intt(_, 3*2**8 + 1)
[1, 2, 3, 4]
>>> intt([1, 2, 3, 4], prime=3*2**8 + 1)
[387, 415, 384, 353]
>>> ntt(_, prime=3*2**8 + 1)
[1, 2, 3, 4]

Fast Walsh Hadamard Transform

sympy.discrete.transforms.fwht(seq)
Performs the Walsh Hadamard Transform (WHT), and uses Hadamard ordering for the
sequence.
The sequence is automatically padded to the right with zeros, as the radix-2 FWHT re-
quires the number of sample points to be a power of 2.
Parameters seq : iterable
The sequence on which WHT is to be applied.

References

[R96], [R97]

Examples

>>> from sympy import fwht, ifwht

>>> fwht([4, 2, 2, 0, 0, 2, -2, 0])
[8, 0, 8, 0, 8, 8, 0, 0]
>>> ifwht(_)
[4, 2, 2, 0, 0, 2, -2, 0]

>>> ifwht([19, -1, 11, -9, -7, 13, -15, 5])

[2, 0, 4, 0, 3, 10, 0, 0]
>>> fwht(_)
[19, -1, 11, -9, -7, 13, -15, 5]

sympy.discrete.transforms.ifwht(seq)
Performs the Walsh Hadamard Transform (WHT), and uses Hadamard ordering for the
sequence.
The sequence is automatically padded to the right with zeros, as the radix-2 FWHT re-
quires the number of sample points to be a power of 2.
Parameters seq : iterable
The sequence on which WHT is to be applied.

5.6. Discrete Module 385

SymPy Documentation, Release 1.3

References

[R98], [R99]

Examples

>>> from sympy import fwht, ifwht

>>> fwht([4, 2, 2, 0, 0, 2, -2, 0])
[8, 0, 8, 0, 8, 8, 0, 0]
>>> ifwht(_)
[4, 2, 2, 0, 0, 2, -2, 0]

>>> ifwht([19, -1, 11, -9, -7, 13, -15, 5])

[2, 0, 4, 0, 3, 10, 0, 0]
>>> fwht(_)
[19, -1, 11, -9, -7, 13, -15, 5]

Möbius Transform

sympy.discrete.transforms.mobius_transform(seq, subset=True)
Performs the Möbius Transform for subset lattice with indices of sequence as bitmasks.
The indices of each argument, considered as bit strings, correspond to subsets of a finite
set.
The sequence is automatically padded to the right with zeros, as the definition of sub-
set/superset based on bitmasks (indices) requires the size of sequence to be a power of
2.
Parameters seq : iterable
The sequence on which Möbius Transform is to be applied.
subset : bool
Specifies if Möbius Transform is applied by enumerating subsets or
supersets of the given set.

References

[R100], [R101], [R102]

Examples

>>> from sympy import symbols

>>> from sympy import mobius_transform, inverse_mobius_transform
>>> x, y, z = symbols('x y z')

>>> mobius_transform([x, y, z])

[x, x + y, x + z, x + y + z]
>>> inverse_mobius_transform(_)
[x, y, z, 0]

386 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> mobius_transform([x, y, z], subset=False)

[x + y + z, y, z, 0]
>>> inverse_mobius_transform(_, subset=False)
[x, y, z, 0]

>>> mobius_transform([1, 2, 3, 4])

[1, 3, 4, 10]
>>> inverse_mobius_transform(_)
[1, 2, 3, 4]
>>> mobius_transform([1, 2, 3, 4], subset=False)
[10, 6, 7, 4]
>>> inverse_mobius_transform(_, subset=False)
[1, 2, 3, 4]

sympy.discrete.transforms.inverse_mobius_transform(seq, subset=True)
Performs the Möbius Transform for subset lattice with indices of sequence as bitmasks.
The indices of each argument, considered as bit strings, correspond to subsets of a finite
set.
The sequence is automatically padded to the right with zeros, as the definition of sub-
set/superset based on bitmasks (indices) requires the size of sequence to be a power of
2.
Parameters seq : iterable
The sequence on which Möbius Transform is to be applied.
subset : bool
Specifies if Möbius Transform is applied by enumerating subsets or
supersets of the given set.

References

[R103], [R104], [R105]

Examples

>>> from sympy import symbols

>>> from sympy import mobius_transform, inverse_mobius_transform
>>> x, y, z = symbols('x y z')

>>> mobius_transform([x, y, z])

[x, x + y, x + z, x + y + z]
>>> inverse_mobius_transform(_)
[x, y, z, 0]

>>> mobius_transform([x, y, z], subset=False)

[x + y + z, y, z, 0]
>>> inverse_mobius_transform(_, subset=False)
[x, y, z, 0]

5.6. Discrete Module 387

SymPy Documentation, Release 1.3

>>> mobius_transform([1, 2, 3, 4])

[1, 3, 4, 10]
>>> inverse_mobius_transform(_)
[1, 2, 3, 4]
>>> mobius_transform([1, 2, 3, 4], subset=False)
[10, 6, 7, 4]
>>> inverse_mobius_transform(_, subset=False)
[1, 2, 3, 4]

5.6.2 Convolutions

This section lists the methods which implement the basic convolutions for discrete sequences.

Convolution

This is a general method for calculating the convolution of discrete sequences, which inter-
nally calls one of the methods convolution_fft, convolution_ntt, convolution_fwht, or
convolution_subset.
sympy.discrete.convolutions.convolution(a, b, cycle=0, dps=None, prime=None,
dyadic=None, subset=None)
Performs convolution by determining the type of desired convolution using hints.
Exactly one of dps, prime, dyadic, subset arguments should be specified explicitly for
identifying the type of convolution, and the argument cycle can be specified optionally.
For the default arguments, linear convolution is performed using FFT.
Parameters a, b : iterables
The sequences for which convolution is performed.
cycle : Integer
Specifies the length for doing cyclic convolution.
dps : Integer
Specifies the number of decimal digits for precision for performing
FFT on the sequence.
prime : Integer
Prime modulus of the form (m2k + 1) to be used for performing NTT
on the sequence.
dyadic : bool
Identifies the convolution type as dyadic (bitwise-XOR) convolution,
which is performed using FWHT.
subset : bool
Identifies the convolution type as subset convolution.

388 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import convolution, symbols, S, I

>>> u, v, w, x, y, z = symbols('u v w x y z')

>>> convolution([1 + 2*I, 4 + 3*I], [S(5)/4, 6], dps=3)

[1.25 + 2.5*I, 11.0 + 15.8*I, 24.0 + 18.0*I]
>>> convolution([1, 2, 3], [4, 5, 6], cycle=3)
[31, 31, 28]

>>> convolution([111, 777], [888, 444], prime=19*2**10 + 1)

[1283, 19351, 14219]
>>> convolution([111, 777], [888, 444], prime=19*2**10 + 1, cycle=2)
[15502, 19351]

>>> convolution([u, v], [x, y, z], dyadic=True)

[u*x + v*y, u*y + v*x, u*z, v*z]
>>> convolution([u, v], [x, y, z], dyadic=True, cycle=2)
[u*x + u*z + v*y, u*y + v*x + v*z]

>>> convolution([u, v, w], [x, y, z], subset=True)

[u*x, u*y + v*x, u*z + w*x, v*z + w*y]
>>> convolution([u, v, w], [x, y, z], subset=True, cycle=3)
[u*x + v*z + w*y, u*y + v*x, u*z + w*x]

Convolution using Fast Fourier Transform

sympy.discrete.convolutions.convolution_fft(a, b, dps=None)
Performs linear convolution using Fast Fourier Transform.
Parameters a, b : iterables
The sequences for which convolution is performed.
dps : Integer
Specifies the number of decimal digits for precision.

References

[R106], [R107]

Examples

>>> from sympy import S, I

>>> from sympy.discrete.convolutions import convolution_fft

>>> convolution_fft([2, 3], [4, 5])

[8, 22, 15]
>>> convolution_fft([2, 5], [6, 7, 3])
[12, 44, 41, 15]
(continues on next page)

5.6. Discrete Module 389

SymPy Documentation, Release 1.3

(continued from previous page)

>>> convolution_fft([1 + 2*I, 4 + 3*I], [S(5)/4, 6])
[5/4 + 5*I/2, 11 + 63*I/4, 24 + 18*I]

Convolution using Number Theoretic Transform

sympy.discrete.convolutions.convolution_ntt(a, b, prime)
Performs linear convolution using Number Theoretic Transform.
Parameters a, b : iterables
The sequences for which convolution is performed.
prime : Integer
Prime modulus of the form (m2k + 1) to be used for performing NTT
on the sequence.

References

[R108], [R109]

Examples

>>> from sympy.discrete.convolutions import convolution_ntt

>>> convolution_ntt([2, 3], [4, 5], prime=19*2**10 + 1)
[8, 22, 15]
>>> convolution_ntt([2, 5], [6, 7, 3], prime=19*2**10 + 1)
[12, 44, 41, 15]
>>> convolution_ntt([333, 555], [222, 666], prime=19*2**10 + 1)
[15555, 14219, 19404]

Convolution using Fast Walsh Hadamard Transform

sympy.discrete.convolutions.convolution_fwht(a, b)
Performs dyadic (bitwise-XOR) convolution using Fast Walsh Hadamard Transform.
The convolution is automatically padded to the right with zeros, as the radix-2 FWHT
requires the number of sample points to be a power of 2.
Parameters a, b : iterables
The sequences for which convolution is performed.

References

[R110], [R111]

390 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, S, I

>>> from sympy.discrete.convolutions import convolution_fwht

>>> u, v, x, y = symbols('u v x y')

>>> convolution_fwht([u, v], [x, y])
[u*x + v*y, u*y + v*x]

>>> convolution_fwht([2, 3], [4, 5])

[23, 22]
>>> convolution_fwht([2, 5 + 4*I, 7], [6*I, 7, 3 + 4*I])
[56 + 68*I, -10 + 30*I, 6 + 50*I, 48 + 32*I]

>>> convolution_fwht([S(33)/7, S(55)/6, S(7)/4], [S(2)/3, 5])

[2057/42, 1870/63, 7/6, 35/4]

Subset Convolution

sympy.discrete.convolutions.convolution_subset(a, b)
Performs Subset Convolution of given sequences.
The indices of each argument, considered as bit strings, correspond to subsets of a finite
set.
The sequence is automatically padded to the right with zeros, as the definition of subset
based on bitmasks (indices) requires the size of sequence to be a power of 2.
Parameters a, b : iterables
The sequences for which convolution is performed.

References

[R112]

Examples

>>> from sympy import symbols, S, I

>>> from sympy.discrete.convolutions import convolution_subset
>>> u, v, x, y, z = symbols('u v x y z')

>>> convolution_subset([u, v], [x, y])

[u*x, u*y + v*x]
>>> convolution_subset([u, v, x], [y, z])
[u*y, u*z + v*y, x*y, x*z]

>>> convolution_subset([1, S(2)/3], [3, 4])

[3, 6]
>>> convolution_subset([1, 3, S(5)/7], [7])
[7, 21, 5, 0]

5.6. Discrete Module 391

SymPy Documentation, Release 1.3

Covering Product

sympy.discrete.convolutions.covering_product(a, b)
Returns the covering product of given sequences.
The indices of each argument, considered as bit strings, correspond to subsets of a finite
set.
The covering product of given sequences is a sequence which contains the sum of prod-
ucts of the elements of the given sequences grouped by the bitwise-OR of the corre-
sponding indices.
The sequence is automatically padded to the right with zeros, as the definition of subset
based on bitmasks (indices) requires the size of sequence to be a power of 2.
Parameters a, b : iterables
The sequences for which covering product is to be obtained.

References

[R113]

Examples

>>> from sympy import symbols, S, I, covering_product

>>> u, v, x, y, z = symbols('u v x y z')

>>> covering_product([u, v], [x, y])

[u*x, u*y + v*x + v*y]
>>> covering_product([u, v, x], [y, z])
[u*y, u*z + v*y + v*z, x*y, x*z]

>>> covering_product([1, S(2)/3], [3, 4 + 5*I])

[3, 26/3 + 25*I/3]
>>> covering_product([1, 3, S(5)/7], [7, 8])
[7, 53, 5, 40/7]

Intersecting Product

sympy.discrete.convolutions.intersecting_product(a, b)
Returns the intersecting product of given sequences.
The indices of each argument, considered as bit strings, correspond to subsets of a finite
set.
The intersecting product of given sequences is the sequence which contains the sum
of products of the elements of the given sequences grouped by the bitwise-AND of the
corresponding indices.
The sequence is automatically padded to the right with zeros, as the definition of subset
based on bitmasks (indices) requires the size of sequence to be a power of 2.
Parameters a, b : iterables

392 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The sequences for which intersecting product is to be obtained.

References

[R114]

Examples

>>> from sympy import symbols, S, I, intersecting_product

>>> u, v, x, y, z = symbols('u v x y z')

>>> intersecting_product([u, v], [x, y])

[u*x + u*y + v*x, v*y]
>>> intersecting_product([u, v, x], [y, z])
[u*y + u*z + v*y + x*y + x*z, v*z, 0, 0]

>>> intersecting_product([1, S(2)/3], [3, 4 + 5*I])

[9 + 5*I, 8/3 + 10*I/3]
>>> intersecting_product([1, 3, S(5)/7], [7, 8])
[327/7, 24, 0, 0]

5.7 Numerical evaluation

5.7.1 Basics

Exact SymPy expressions can be converted to floating-point approximations (decimal num-

bers) using either the .evalf() method or the N() function. N(expr, <args>) is equivalent
to sympify(expr).evalf(<args>).

>>> from sympy import *

>>> N(sqrt(2)*pi)
4.44288293815837
>>> (sqrt(2)*pi).evalf()
4.44288293815837

By default, numerical evaluation is performed to an accuracy of 15 decimal digits. You can

optionally pass a desired accuracy (which should be a positive integer) as an argument to
evalf or N:

>>> N(sqrt(2)*pi, 5)
4.4429
>>> N(sqrt(2)*pi, 50)
4.4428829381583662470158809900606936986146216893757

Complex numbers are supported:

>>> N(1/(pi + I), 20)

0.28902548222223624241 - 0.091999668350375232456*I

5.7. Numerical evaluation 393

SymPy Documentation, Release 1.3

If the expression contains symbols or for some other reason cannot be evaluated numerically,
calling .evalf() or N() returns the original expression, or in some cases a partially evalu-
ated expression. For example, when the expression is a polynomial in expanded form, the
coefficients are evaluated:

>>> x = Symbol('x')
>>> (pi*x**2 + x/3).evalf()
3.14159265358979*x**2 + 0.333333333333333*x

You can also use the standard Python functions float(), complex() to convert SymPy ex-
pressions to regular Python numbers:

>>> float(pi)
3.1415926535...
>>> complex(pi+E*I)
(3.1415926535...+2.7182818284...j)

If these functions are used, failure to evaluate the expression to an explicit number (for ex-
ample if the expression contains symbols) will raise an exception.
There is essentially no upper precision limit. The following command, for example, computes
the first 100,000 digits of π/e:

>>> N(pi/E, 100000) #doctest: +SKIP

...

This shows digits 999,951 through 1,000,000 of pi:

>>> str(N(pi, 10**6))[-50:] #doctest: +SKIP

'95678796130331164628399634646042209010610577945815'

High-precision calculations can be slow. It is recommended (but entirely optional) to install

gmpy (http://code.google.com/p/gmpy/), which will significantly speed up computations such
as the one above.

5.7.2 Floating-point numbers

Floating-point numbers in SymPy are instances of the class Float. A Float can be created
with a custom precision as second argument:

>>> Float(0.1)
0.100000000000000
>>> Float(0.1, 10)
0.1000000000
>>> Float(0.125, 30)
0.125000000000000000000000000000
>>> Float(0.1, 30)
0.100000000000000005551115123126

As the last example shows, some Python floats are only accurate to about 15 digits as inputs,
while others (those that have a denominator that is a power of 2, like 0.125 = 1/8) are exact.
To create a Float from a high-precision decimal number, it is better to pass a string, Rational,
or evalf a Rational:

394 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Float('0.1', 30)

0.100000000000000000000000000000
>>> Float(Rational(1, 10), 30)
0.100000000000000000000000000000
>>> Rational(1, 10).evalf(30)
0.100000000000000000000000000000

The precision of a number determines 1) the precision to use when performing arithmetic
with the number, and 2) the number of digits to display when printing the number. When two
numbers with different precision are used together in an arithmetic operation, the higher of
the precisions is used for the result. The product of 0.1 +/- 0.001 and 3.1415 +/- 0.0001 has
an uncertainty of about 0.003 and yet 5 digits of precision are shown.

>>> Float(0.1, 3)*Float(3.1415, 5)

0.31417

So the displayed precision should not be used as a model of error propagation or significance
arithmetic; rather, this scheme is employed to ensure stability of numerical algorithms.
N and evalf can be used to change the precision of existing floating-point numbers:

>>> N(3.5)
3.50000000000000
>>> N(3.5, 5)
3.5000
>>> N(3.5, 30)
3.50000000000000000000000000000

5.7.3 Accuracy and error handling

When the input to N or evalf is a complicated expression, numerical error propagation be-
comes a concern. As an example, consider
√ the 100’th Fibonacci number and the excellent
(but not exact) approximation φ100 / 5 where φ is the golden ratio. With ordinary floating-
point arithmetic, subtracting these numbers from each other erroneously results in a com-
plete cancellation:

>>> a, b = GoldenRatio**1000/sqrt(5), fibonacci(1000)

>>> float(a)
4.34665576869e+208
>>> float(b)
4.34665576869e+208
>>> float(a) - float(b)
0.0

N and evalf keep track of errors and automatically increase the precision used internally in
order to obtain a correct result:

>>> N(fibonacci(100) - GoldenRatio**100/sqrt(5))

-5.64613129282185e-22

Unfortunately, numerical evaluation cannot tell an expression that is exactly zero apart from
one that is merely very small. The working precision is therefore capped, by default to around
100 digits. If we try with the 1000’th Fibonacci number, the following happens:

5.7. Numerical evaluation 395

SymPy Documentation, Release 1.3

>>> N(fibonacci(1000) - (GoldenRatio)**1000/sqrt(5))

0.e+85

The lack of digits in the returned number indicates that N failed to achieve full accuracy. The
result indicates that the magnitude of the expression is something less than 10^84, but that
is not a particularly good answer. To force a higher working precision, the maxn keyword
argument can be used:

>>> N(fibonacci(1000) - (GoldenRatio)**1000/sqrt(5), maxn=500)

-4.60123853010113e-210

Normally, maxn can be set very high (thousands of digits), but be aware that this may cause
significant slowdown in extreme cases. Alternatively, the strict=True option can be set to
force an exception instead of silently returning a value with less than the requested accuracy:

>>> N(fibonacci(1000) - (GoldenRatio)**1000/sqrt(5), strict=True)

Traceback (most recent call last):
...
PrecisionExhausted: Failed to distinguish the expression:
<BLANKLINE>
-sqrt(5)*GoldenRatio**1000/5 +␣
,→434665576869374564356885276750406258025646605173717804024817290895365554179490518904038798400792551

<BLANKLINE>
from zero. Try simplifying the input, using chop=True, or providing a higher maxn for␣
,→evalf

If we add a term so that the Fibonacci approximation becomes exact (the full form of Binet’s
formula), we get an expression that is exactly zero, but N does not know this:

>>> f = fibonacci(100) - (GoldenRatio**100 - (GoldenRatio-1)**100)/sqrt(5)

>>> N(f)
0.e-104
>>> N(f, maxn=1000)
0.e-1336

In situations where such cancellations are known to occur, the chop options is useful. This
basically replaces very small numbers in the real or imaginary portions of a number with
exact zeros:

>>> N(f, chop=True)

0
>>> N(3 + I*f, chop=True)
3.00000000000000

In situations where you wish to remove meaningless digits, re-evaluation or the use of the
round method are useful:

>>> Float('.1', '')*Float('.12345', '')

0.012297
>>> ans = _
>>> N(ans, 1)
0.01
>>> ans.round(2)
0.01

If you are dealing with a numeric expression that contains no floats, it can be evaluated to
arbitrary precision. To round the result relative to a given decimal, the round method is

396 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

useful:

>>> v = 10*pi + cos(1)

>>> N(v)
31.9562288417661
>>> v.round(3)
31.956

5.7.4 Sums and integrals

Sums (in particular, infinite series) and integrals can be used like regular closed-form expres-
sions, and support arbitrary-precision evaluation:

>>> var('n x')

(n, x)
>>> Sum(1/n**n, (n, 1, oo)).evalf()
1.29128599706266
>>> Integral(x**(-x), (x, 0, 1)).evalf()
1.29128599706266
>>> Sum(1/n**n, (n, 1, oo)).evalf(50)
1.2912859970626635404072825905956005414986193682745
>>> Integral(x**(-x), (x, 0, 1)).evalf(50)
1.2912859970626635404072825905956005414986193682745
>>> (Integral(exp(-x**2), (x, -oo, oo)) ** 2).evalf(30)
3.14159265358979323846264338328

By default, the tanh-sinh quadrature algorithm is used to evaluate integrals. This algorithm
is very efficient and robust for smooth integrands (and even integrals with endpoint singulari-
ties), but may struggle with integrals that are highly oscillatory or have mid-interval disconti-
nuities. In many cases, evalf/N will correctly estimate the error. With the following integral,
the result is accurate but only good to four digits:

>>> f = abs(sin(x))
>>> Integral(abs(sin(x)), (x, 0, 4)).evalf()
2.346

It is better to split this integral into two pieces:

>>> (Integral(f, (x, 0, pi)) + Integral(f, (x, pi, 4))).evalf()

2.34635637913639

A similar example is the following oscillatory integral:

>>> Integral(sin(x)/x**2, (x, 1, oo)).evalf(maxn=20)

0.5

It can be dealt with much more efficiently by telling evalf or N to use an oscillatory quadrature
algorithm:

>>> Integral(sin(x)/x**2, (x, 1, oo)).evalf(quad='osc')

0.504067061906928
>>> Integral(sin(x)/x**2, (x, 1, oo)).evalf(20, quad='osc')
0.50406706190692837199

Oscillatory quadrature requires an integrand containing a factor cos(ax+b) or sin(ax+b).

Note that many other oscillatory integrals can be transformed to this form with a change

5.7. Numerical evaluation 397

SymPy Documentation, Release 1.3

of variables:

>>> init_printing(use_unicode=False, wrap_line=False)

>>> intgrl = Integral(sin(1/x), (x, 0, 1)).transform(x, 1/x)
>>> intgrl
oo
/
|
| sin(x)
| ------ dx
| 2
| x
|
/
1
>>> N(intgrl, quad='osc')
0.504067061906928

Infinite series use direct summation if the series converges quickly enough. Otherwise, ex-
trapolation methods (generally the Euler-Maclaurin formula but also Richardson extrapola-
tion) are used to speed up convergence. This allows high-precision evaluation of slowly con-
vergent series:

>>> var('k')
k
>>> Sum(1/k**2, (k, 1, oo)).evalf()
1.64493406684823
>>> zeta(2).evalf()
1.64493406684823
>>> Sum(1/k-log(1+1/k), (k, 1, oo)).evalf()
0.577215664901533
>>> Sum(1/k-log(1+1/k), (k, 1, oo)).evalf(50)
0.57721566490153286060651209008240243104215933593992
>>> EulerGamma.evalf(50)
0.57721566490153286060651209008240243104215933593992

The Euler-Maclaurin formula is also used for finite series, allowing them to be approximated
quickly without evaluating all terms:

>>> Sum(1/k, (k, 10000000, 20000000)).evalf()

0.693147255559946

Note that evalf makes some assumptions that are not always optimal. For fine-tuned con-
trol over numerical summation, it might be worthwhile to manually use the method Sum.
euler_maclaurin.
Special optimizations are used for rational hypergeometric series (where the term is a product
of polynomials, powers, factorials, binomial coefficients and the like). N/evalf sum series of
this type very rapidly to high precision. For example, this Ramanujan formula for pi can be
summed to 10,000 digits in a fraction of a second with a simple command:

>>> f = factorial
>>> n = Symbol('n', integer=True)
>>> R = 9801/sqrt(8)/Sum(f(4*n)*(1103+26390*n)/f(n)**4/396**(4*n),
... (n, 0, oo)) #doctest: +SKIP
>>> N(R, 10000) #doctest: +SKIP
3.141592653589793238462643383279502884197169399375105820974944592307816406286208
(continues on next page)

398 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

99862803482534211706798214808651328230664709384460955058223172535940812848111745
02841027019385211055596446229489549303819644288109756659334461284756482337867831
...

5.7.5 Numerical simplification

The function nsimplify attempts to find a formula that is numerically equal to the given
input. This feature can be used to guess an exact formula for an approximate floating-point
input, or to guess a simpler formula for a complicated symbolic input. The algorithm used
by nsimplify is capable of identifying simple fractions, simple algebraic expressions, linear
combinations of given constants, and certain elementary functional transformations of any of
the preceding.
Optionally, nsimplify can be passed a list of constants to include (e.g. pi) and a minimum
numerical tolerance. Here are some elementary examples:

>>> nsimplify(0.1)
1/10
>>> nsimplify(6.28, [pi], tolerance=0.01)
2*pi
>>> nsimplify(pi, tolerance=0.01)
22/7
>>> nsimplify(pi, tolerance=0.001)
355
---
113
>>> nsimplify(0.33333, tolerance=1e-4)
1/3
>>> nsimplify(2.0**(1/3.), tolerance=0.001)
635
---
504
>>> nsimplify(2.0**(1/3.), tolerance=0.001, full=True)
3 ___
\/ 2

Here are several more advanced examples:

>>> nsimplify(Float('0.130198866629986772369127970337',30), [pi, E])

1
----------
5*pi
---- + 2*E
7
>>> nsimplify(cos(atan('1/3')))
____
3*\/ 10
--------
10
>>> nsimplify(4/(1+sqrt(5)), [GoldenRatio])
-2 + 2*GoldenRatio
>>> nsimplify(2 + exp(2*atan('1/4')*I))
49 8*I
-- + ---
(continues on next page)

5.7. Numerical evaluation 399

SymPy Documentation, Release 1.3

(continued from previous page)

17 17
>>> nsimplify((1/(exp(3*pi*I/5)+1)))
___________
/ ___
1 / \/ 5 1
- - I* / ----- + -
2 \/ 10 4
>>> nsimplify(I**I, [pi])
-pi
----
2
e
>>> n = Symbol('n')
>>> nsimplify(Sum(1/n**2, (n, 1, oo)), [pi])
2
pi
---
6
>>> nsimplify(gamma('1/4')*gamma('3/4'), [pi])
___
\/ 2 *pi

5.8 Structural Details of Code Generation with SymPy

Several submodules in SymPy allow one to generate directly compilable and executable code
in a variety of different programming languages from SymPy expressions. In addition, there
are functions that generate Python importable objects that can evaluate SymPy expressions
very efficiently.
We will start with a brief introduction to the components that make up the code generation
capabilities of SymPy.

5.8.1 Introduction

There are four main levels of abstractions:

expression
|
code printers
|
code generators
|
autowrap

sympy.utilities.autowrap (page 1431) uses codegen, and codegen uses the code printers.
sympy.utilities.autowrap (page 1431) does everything: it lets you go from SymPy expres-
sion to numerical function in the same Python process in one step. Codegen is actual code
generation, i.e., to compile and use later, or to include in some larger project.
The code printers translate the SymPy objects into actual code, like abs(x) -> fabs(x) (for
C).

400 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The code printers don’t print optimal code in many cases. An example of this is powers in C.
x**2 prints as pow(x, 2) instead of x*x. Other optimizations (like mathematical simplifica-
tions) should happen before the code printers.
Currently, sympy.simplify.cse_main.cse() (page 1205) is not applied automatically any-
where in this chain. It ideally happens at the codegen level, or somewhere above it.
We will iterate through the levels below.
The following three lines will be used to setup each example:

>>> from sympy import *

>>> init_printing(use_unicode=True)
>>> from sympy.abc import a, e, k, n, r, t, x, y, z, T, Z
>>> from sympy.abc import beta, omega, tau
>>> f, g = symbols('f, g', cls=Function)

5.8.2 Code printers (sympy.printing)

This is where the meat of code generation is; the translation of SymPy actually more like a
lightweight version of codegen for Python, and Python (sympy.printing.pycode.pycode()
(page 1077)), and sympy.printing.lambdarepr.lambdarepr() (page 1072), which supports
many libraries (like NumPy), and theano (sympy.printing.theanocode.theano_function()
(page 1071)). The code printers are special cases of the other prints in SymPy (str printer,
pretty printer, etc.).
An important distinction is that the code printer has to deal with assignments (using the
sympy.codegen.ast.Assignment (page 414) object). This serves as building blocks for the
code printers and hence the codegen module. An example that shows the use of Assignment
in C code:

>>> from sympy.codegen.ast import Assignment

>>> print(ccode(Assignment(x, y + 1)))
x = y + 1;

Here is another simple example of printing a C version of a SymPy expression:

>>> expr = (Rational(-1, 2) * Z * k * (e**2) / r)

>>> expr
2
-Z⋅e ⋅k
────────
2⋅r
>>> ccode(expr)
-1.0/2.0*Z*pow(e, 2)*k/r
>>> from sympy.codegen.ast import real, float80
>>> ccode(expr, assign_to=”E”, type_aliases={real: float80})
E = -1.0L/2.0L*Z*powl(e, 2)*k/r;

To generate code with some math functions provided by e.g. the C99 standard we need to
import functions from sympy.codegen.cfunctions (page 429):

>>> from sympy.codegen.cfunctions import expm1

>>> ccode(expm1(x), standard='C99')
expm1(x)

5.8. Structural Details of Code Generation with SymPy 401

SymPy Documentation, Release 1.3

Piecewise expressions are converted into conditionals. If an assign_to variable is provided

an if statement is created, otherwise the ternary operator is used. Note that if the Piece-
wise lacks a default term, represented by (expr, True) then an error will be thrown. This
is to prevent generating an expression that may not evaluate to anything. A use case for
Piecewise:

>>> expr = Piecewise((x + 1, x > 0), (x, True))

>>> print(fcode(expr, tau))
if (x > 0) then
tau = x + 1
else
tau = x
end if

The various printers also tend to support Indexed objects well. With contract=True these
expressions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> len_y = 5
>>> mat_1 = IndexedBase('mat_1', shape=(len_y,))
>>> mat_2 = IndexedBase('mat_2', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> eq = Eq(Dy[i], (mat_1[i+1] - mat_1[i]) / (mat_2[i+1] - mat_2[i]))
>>> print(jscode(eq.rhs, assign_to=eq.lhs, contract=False))
Dy[i] = (mat_1[i + 1] - mat_1[i])/(mat_2[i + 1] - mat_2[i]);
>>> Res = IndexedBase('Res', shape=(len_y,))
>>> j = Idx('j', len_y)
>>> eq = Eq(Res[j], mat_1[j]*mat_2[j])
>>> print(jscode(eq.rhs, assign_to=eq.lhs, contract=True))
for (var j=0; j<5; j++){
Res[j] = 0;
}
for (var j=0; j<5; j++){
for (var j=0; j<5; j++){
Res[j] = Res[j] + mat_1[j]*mat_2[j];
}
}
>>> print(jscode(eq.rhs, assign_to=eq.lhs, contract=False))
Res[j] = mat_1[j]*mat_2[j];

Custom printing can be defined for certain types by passing a dictionary of “type” : “function”
to the user_functions kwarg. Alternatively, the dictionary value can be a list of tuples i.e.,
[(argument_test, cfunction_string)]. This can be used to call a custom Octave function:

>>> custom_functions = {
... ”f”: ”existing_octave_fcn”,
... ”g”: [(lambda x: x.is_Matrix, ”my_mat_fcn”),
... (lambda x: not x.is_Matrix, ”my_fcn”)]
... }
>>> mat = Matrix([[1, x]])
>>> octave_code(f(x) + g(x) + g(mat), user_functions=custom_functions)
existing_octave_fcn(x) + my_fcn(x) + my_mat_fcn([1 x])

An example of Mathematica code printer:

402 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> x_ = Function('x')
>>> expr = x_(n*T) * sin((t - n*T) / T)
>>> expr = expr / ((-T*n + t) / T)
>>> expr
⎛-T⋅n + t⎞
T⋅x(T⋅n)⋅sin⎜────────⎟
⎝ T ⎠
──────────────────────
-T⋅n + t

>>> expr = summation(expr, (n, -1, 1))

>>> mathematica_code(expr)
T*x[-T]*Sin[(T + t)/T]/(T + t) + T*x[T]*Sin[(-T + t)/T]/(-T + t) + T*x[0]*Sin[
t/T]/t

We can go through a common expression in different languages we support and see how it
works:

>>> k, g1, g2, r, I, S = symbols(”k, gamma_1, gamma_2, r, I, S”)

>>> expr = k * g1 * g2 / (r**3)
>>> expr = expr * 2 * I * S * (3 * (cos(beta))**2 - 1) / 2
>>> expr
⎛ 2 ⎞
I⋅S⋅γ 1 ⋅γ 2 ⋅k⋅⎝3⋅cos (β) - 1⎠
───────────────────────────
3
r
>>> print(jscode(expr, assign_to=”H_is”))
H_is = I*S*gamma_1*gamma_2*k*(3*Math.pow(Math.cos(beta), 2) - 1)/Math.pow(r, 3);
>>> print(ccode(expr, assign_to=”H_is”, standard='C89'))
H_is = I*S*gamma_1*gamma_2*k*(3*pow(cos(beta), 2) - 1)/pow(r, 3);
>>> print(fcode(expr, assign_to=”H_is”))
H_is = I*S*gamma_1*gamma_2*k*(3*cos(beta)**2 - 1)/r**3
>>> print(julia_code(expr, assign_to=”H_is”))
H_is = I.*S.*gamma_1.*gamma_2.*k.*(3*cos(beta).^2 - 1)./r.^3
>>> print(octave_code(expr, assign_to=”H_is”))
H_is = I.*S.*gamma_1.*gamma_2.*k.*(3*cos(beta).^2 - 1)./r.^3;
>>> print(rust_code(expr, assign_to=”H_is”))
H_is = I*S*gamma_1*gamma_2*k*(3*beta.cos().powi(2) - 1)/r.powi(3);
>>> print(mathematica_code(expr))
I*S*gamma_1*gamma_2*k*(3*Cos[beta]^2 - 1)/r^3

5.8.3 Codegen (sympy.utilities.codegen)

This module deals with creating compilable code from SymPy expressions. This is lower
level than autowrap, as it doesn’t actually attempt to compile the code, but higher level than
the printers, as it generates compilable files (including header files), rather than just code
snippets.
The user friendly functions, here, are codegen and make_routine. codegen takes a list of
(variable, expression) pairs and a language (C, F95, and Octave/Matlab are supported).
It returns, as strings, a code file and a header file (for relevant languages). The variables are
created as functions that return the value of the expression as output.

Note: The codegen callable is not in the sympy namespace automatically, to use it you must

5.8. Structural Details of Code Generation with SymPy 403

SymPy Documentation, Release 1.3

first import codegen from sympy.utilities.codegen

For instance:

>>> from sympy.utilities.codegen import codegen

>>> length, breadth, height = symbols('length, breadth, height')
>>> [(c_name, c_code), (h_name, c_header)] = \
... codegen(('volume', length*breadth*height), ”C99”, ”test”,
... header=False, empty=False)
>>> print(c_name)
test.c
>>> print(c_code)
#include ”test.h”
#include <math.h>
double volume(double breadth, double height, double length) {
double volume_result;
volume_result = breadth*height*length;
return volume_result;
}
>>> print(h_name)
test.h
>>> print(c_header)
#ifndef PROJECT__TEST__H
#define PROJECT__TEST__H
double volume(double breadth, double height, double length);
#endif

Various flags to codegen let you modify things. The project name for preprocessor instructions
can be varied using project. Variables listed as global variables in arg global_vars will not
show up as function arguments.
language is a case-insensitive string that indicates the source code language. Currently, C,
F95 and Octave are supported. Octave generates code compatible with both Octave and
Matlab.
header when True, a header is written on top of each source file. empty when True, empty
lines are used to structure the code. With argument_sequence a sequence of arguments for
the routine can be defined in a preferred order.
prefix defines a prefix for the names of the files that contain the source code. If omitted, the
name of the first name_expr tuple is used.
to_files when True, the code will be written to one or more files with the given prefix.
Here is an example:

>>> [(f_name, f_code), header] = codegen((”volume”, length*breadth*height),

... ”F95”, header=False, empty=False, argument_sequence=(breadth, length),
... global_vars=(height,))
>>> print(f_code)
REAL*8 function volume(breadth, length)
implicit none
REAL*8, intent(in) :: breadth
REAL*8, intent(in) :: length
volume = breadth*height*length
end function

The method make_routine creates a Routine object, which represents an evaluation rou-
tine for a set of expressions. This is only good for internal use by the CodeGen objects, as

404 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

an intermediate representation from SymPy expression to generated code. It is not recom-

mended to make a Routine object yourself. You should instead use make_routine method.
make_routine in turn calls the routine method of the CodeGen object depending upon the
language of choice. This creates the internal objects representing assignments and so on,
and creates the Routine class with them.
The various codegen objects such as Routine and Variable aren’t SymPy objects (they don’t
subclass from Basic).
For example:

>>> from sympy.utilities.codegen import make_routine

>>> from sympy.physics.hydrogen import R_nl
>>> expr = R_nl(3, y, x, 6)
>>> routine = make_routine('my_routine', expr)
>>> [arg.result_var for arg in routine.results]
[result5142341681397719428 ]
>>> [arg.expr for arg in routine.results]
⎡ ___________ ⎤
⎢ y ╱ (-y + 2)! -2⋅x ⎥
⎢4⋅√6⋅(4⋅x) ⋅ ╱ ───────── ⋅e ⋅assoc_laguerre(-y + 2, 2⋅y + 1, 4⋅x)⎥
⎢ ╲╱ (y + 3)! ⎥
⎢──────────────────────────────────────────────────────────────────────⎥
⎣ 3 ⎦
>>> [arg.name for arg in routine.arguments]
[x, y]

Another more complicated example with a mixture of specified and automatically-assigned

names. Also has Matrix output:

>>> routine = make_routine('fcn', [x*y, Eq(a, 1), Eq(r, x + r), Matrix([[x, 2]])])
>>> [arg.result_var for arg in routine.results]
[result_5397460570204848505]
>>> [arg.expr for arg in routine.results]
[x⋅y]
>>> [arg.name for arg in routine.arguments]
[x, y, a, r, out_8598435338387848786]

We can examine the various arguments more closely:

>>> from sympy.utilities.codegen import (InputArgument, OutputArgument,

... InOutArgument)
>>> [a.name for a in routine.arguments if isinstance(a, InputArgument)]
[x, y]

>>> [a.name for a in routine.arguments if isinstance(a, OutputArgument)]

[a, out_8598435338387848786]
>>> [a.expr for a in routine.arguments if isinstance(a, OutputArgument)]
[1, [x 2]]

>>> [a.name for a in routine.arguments if isinstance(a, InOutArgument)]

[r]
>>> [a.expr for a in routine.arguments if isinstance(a, InOutArgument)]
[r + x]

The full API reference can be viewed here (page 1437).

5.8. Structural Details of Code Generation with SymPy 405

SymPy Documentation, Release 1.3

5.8.4 Autowrap

Autowrap automatically generates code, writes it to disk, compiles it, and imports it into
the current session. Main functions of this module are autowrap, binary_function, and
ufuncify.
It also automatically converts expressions containing Indexed objects into summations. The
classes IndexedBase, Indexed and Idx represent a matrix element M[i, j]. See Tensor Module
(page 1399) for more on this.
autowrap creates a wrapper using f2py or Cython and creates a numerical function.

Note: The autowrap callable is not in the sympy namespace automatically, to use it you must
first import autowrap from sympy.utilities.autowrap

The callable returned from autowrap() is a binary Python function, not a SymPy object. For
example:

>>> from sympy.utilities.autowrap import autowrap

>>> expr = ((x - y + z)**(13)).expand()
>>> binary_func = autowrap(expr)
>>> binary_func(1, 4, 2)
-1.0

The various flags available with autowrap() help to modify the services provided by the
method. The argument tempdir tells autowrap to compile the code in a specific directory,
and leave the files intact when finished. For instance:

>>> from sympy.utilities.autowrap import autowrap

>>> from sympy.physics.qho_1d import psi_n
>>> x_ = IndexedBase('x')
>>> y_ = IndexedBase('y')
>>> m = symbols('m', integer=True)
>>> i = Idx('i', m)
>>> qho = autowrap(Eq(y_[i], psi_n(0, x_[i], m, omega)), tempdir='/tmp')

Checking the Fortran source code in the directory specified reveals this:

subroutine autofunc(m, omega, x, y)

implicit none
INTEGER*4, intent(in) :: m
REAL*8, intent(in) :: omega
REAL*8, intent(in), dimension(1:m) :: x
REAL*8, intent(out), dimension(1:m) :: y
INTEGER*4 :: i

REAL*8, parameter :: hbar = 1.05457162d-34

REAL*8, parameter :: pi = 3.14159265358979d0
do i = 1, m
y(i) = (m*omega)**(1.0d0/4.0d0)*exp(-4.74126166983329d+33*m*omega*x(i &
)**2)/(hbar**(1.0d0/4.0d0)*pi**(1.0d0/4.0d0))
end do

end subroutine

Using the argument args along with it changes argument sequence:

406 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> eq = Eq(y_[i], psi_n(0, x_[i], m, omega))

>>> qho = autowrap(eq, tempdir='/tmp', args=[y, x, m, omega])

yields:
subroutine autofunc(y, x, m, omega)
implicit none
INTEGER*4, intent(in) :: m
REAL*8, intent(in) :: omega
REAL*8, intent(out), dimension(1:m) :: y
REAL*8, intent(in), dimension(1:m) :: x
INTEGER*4 :: i

REAL*8, parameter :: hbar = 1.05457162d-34

REAL*8, parameter :: pi = 3.14159265358979d0
do i = 1, m
y(i) = (m*omega)**(1.0d0/4.0d0)*exp(-4.74126166983329d+33*m*omega*x(i &
)**2)/(hbar**(1.0d0/4.0d0)*pi**(1.0d0/4.0d0))
end do

end subroutine

The argument verbose is boolean, optional and if True, autowrap will not mute the command
line backends. This can be helpful for debugging.
The argument language and backend are used to change defaults: Fortran and f2py to C and
Cython. The argument helpers is used to define auxiliary expressions needed for the main
expression. If the main expression needs to call a specialized function it should be put in the
helpers iterable. Autowrap will then make sure that the compiled main expression can link to
the helper routine. Items should be tuples with (<function_name>, <sympy_expression>,
<arguments>). It is mandatory to supply an argument sequence to helper routines.
Another method available at the autowrap level is binary_function. It returns a sympy
function. The advantage is that we can have very fast functions as compared to SymPy speeds.
This is because we will be using compiled functions with Sympy attributes and methods. An
illustration:
>>> from sympy.utilities.autowrap import binary_function
>>> from sympy.physics.hydrogen import R_nl
>>> psi_nl = R_nl(1, 0, a, r)
>>> f = binary_function('f', psi_nl)
>>> f(a, r).evalf(3, subs={a: 1, r: 2})
0.766

While NumPy operations are very efficient for vectorized data but they sometimes incur un-
necessary costs when chained together. Consider the following operation
>>> x = get_numpy_array(...) # doctest: +SKIP
>>> y = sin(x) / x

The operators sin and / call routines that execute tight for loops in C. The resulting compu-
tation looks something like this
for(int i = 0; i < n; i++)
{
temp[i] = sin(x[i]);
}
(continues on next page)

5.8. Structural Details of Code Generation with SymPy 407

SymPy Documentation, Release 1.3

(continued from previous page)

for(int i = i; i < n; i++)
{
y[i] = temp[i] / x[i];
}

This is slightly sub-optimal because

1. We allocate an extra temp array
2. We walk over x memory twice when once would have been sufficient
A better solution would fuse both element-wise operations into a single for loop
for(int i = i; i < n; i++)
{
y[i] = sin(x[i]) / x[i];
}

Statically compiled projects like NumPy are unable to take advantage of such optimizations.
Fortunately, SymPy is able to generate efficient low-level C or Fortran code. It can then
depend on projects like Cython or f2py to compile and reconnect that code back up to Python.
Fortunately this process is well automated and a SymPy user wishing to make use of this code
generation should call the ufuncify function.
ufuncify is the third method available with Autowrap module. It basically implies ‘Universal
functions’ and follows an ideology set by NumPy. The main point of ufuncify as compared to
autowrap is that it allows arrays as arguments and can operate in an element-by-element fash-
ion. The core operation done element-wise is in accordance to Numpy’s array broadcasting
rules. See this for more.
>>> from sympy import *
>>> from sympy.abc import x
>>> expr = sin(x)/x

>>> from sympy.utilities.autowrap import ufuncify

>>> f = ufuncify([x], expr) # doctest: +SKIP

This function f consumes and returns a NumPy array. Generally ufuncify performs at least
as well as lambdify. If the expression is complicated then ufuncify often significantly out-
performs the NumPy backed solution. Jensen has a good blog post on this topic.
Let us see an example for some quantitative analysis:
>>> from sympy.physics.hydrogen import R_nl
>>> expr = R_nl(3, 1, x, 6)
>>> expr
-2⋅x
8⋅x⋅(-4⋅x + 4)⋅e
────────────────────
3

The lambdify function translates SymPy expressions into Python functions, leveraging a vari-
ety of numerical libraries. By default lambdify relies on implementations in the math standard
library. Naturally, Raw Python is faster than SymPy. However it also supports mpmath and
most notably, numpy. Using the NumPy library gives the generated function access to power-
ful vectorized ufuncs that are backed by compiled C code.
Let us compare the speeds:

408 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.utilities.autowrap import ufuncify

>>> from sympy.utilities.lambdify import lambdify
>>> fn_numpy = lambdify(x, expr, 'numpy')
>>> fn_fortran = ufuncify([x], expr, backend='f2py')
>>> from numpy import linspace
>>> xx = linspace(0, 1, 5)
>>> fn_numpy(xx)
[ 0. 1.21306132 0.98101184 0.44626032 0. ]
>>> fn_fortran(xx)
[ 0. 1.21306132 0.98101184 0.44626032 0. ]
>>> import timeit
>>> timeit.timeit('fn_numpy(xx)', 'from __main__ import fn_numpy, xx', number=10000)
0.18891601900395472
>>> timeit.timeit('fn_fortran(xx)', 'from __main__ import fn_fortran, xx',␣
,→number=10000)

0.004707066000264604

The options available with ufuncify are more or less the same as those available with au-
towrap.
There are other facilities available with SymPy to do efficient numeric computation. See this
(page 443) page for a comparison among them.

5.8.5 Classes and functions for rewriting expressions

(sympy.codegen.rewriting)

Classes and functions useful for rewriting expressions for optimized code generation. Some
languages (or standards thereof), e.g. C99, offer specialized math functions for better per-
formance and/or precision.
Using the optimize function in this module, together with a collection of rules (represented
as instances of Optimization), one can rewrite the expressions for this purpose:

>>> from sympy import Symbol, exp, log

>>> from sympy.codegen.rewriting import optimize, optims_c99
>>> x = Symbol('x')
>>> optimize(3*exp(2*x) - 3, optims_c99)
3*expm1(2*x)
>>> optimize(exp(2*x) - 3, optims_c99)
exp(2*x) - 3
>>> optimize(log(3*x + 3), optims_c99)
log1p(x) + log(3)
>>> optimize(log(2*x + 3), optims_c99)
log(2*x + 3)

The optims_c99 imported above is tuple containing the following instances (which may be
imported from sympy.codegen.rewriting):
• expm1_opt
• log1p_opt
• exp2_opt
• log2_opt
• log2const_opt

5.8. Structural Details of Code Generation with SymPy 409

SymPy Documentation, Release 1.3

class sympy.codegen.rewriting.Optimization(cost_function=None, priority=1)

Abstract base class for rewriting optimization.
Subclasses should implement __call__ taking an expression as argument.
Parameters cost_function : callable returning number
priority : number
class sympy.codegen.rewriting.ReplaceOptim(query, value, **kwargs)
Rewriting optimization calling replace on expressions.
The instance can be used as a function on expressions for which it will apply the replace
method (see sympy.core.basic.Basic.replace() (page 108)).
Parameters query : first argument passed to replace
value : second argument passed to replace

Examples

>>> from sympy import Symbol, Pow

>>> from sympy.codegen.rewriting import ReplaceOptim
>>> from sympy.codegen.cfunctions import exp2
>>> x = Symbol('x')
>>> exp2_opt = ReplaceOptim(lambda p: p.is_Pow and p.base == 2,
... lambda p: exp2(p.exp))
>>> exp2_opt(2**x)
exp2(x)

sympy.codegen.rewriting.create_expand_pow_optimization(limit)
Creates an instance of ReplaceOptim (page 410) for expanding Pow.
The requirements for expansions are that the base needs to be a symbol and the exponent
needs to be an integer (and be less than or equal to limit).
Parameters limit : int
The highest power which is expanded into multiplication.

Examples

>>> from sympy import Symbol, sin

>>> from sympy.codegen.rewriting import create_expand_pow_optimization
>>> x = Symbol('x')
>>> expand_opt = create_expand_pow_optimization(3)
>>> expand_opt(x**5 + x**3)
x**5 + x*x*x
>>> expand_opt(x**5 + x**3 + sin(x)**3)
x**5 + x*x*x + sin(x)**3

sympy.codegen.rewriting.optimize(expr, optimizations)
Apply optimizations to an expression.
Parameters expr : expression
optimizations : iterable of Optimization instances

410 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The optimizations will be sorted with respect to priority (highest

first).

Examples

>>> from sympy import log, Symbol

>>> from sympy.codegen.rewriting import optims_c99, optimize
>>> x = Symbol('x')
>>> optimize(log(x+3)/log(2) + log(x**2 + 1), optims_c99)
log1p(x**2) + log2(x + 3)

5.8.6 Tools for simplifying expressions using approximations

(sympy.codegen.approximations)

class sympy.codegen.approximations.SeriesApprox(bounds, reltol, max_order=4,

n_point_checks=4, **kwargs)
Approximates functions by expanding them as a series
Parameters bounds : dict
Mapping expressions to length 2 tuple of bounds (low, high).
reltol : number
Threshold for when to ignore a term. Taken relative to the largest
lower bound among bounds.
max_order : int
Largest order to include in series expansion
n_point_checks : int (even)
The validity of an expansion (with respect to reltol) is checked at dis-
crete points (linearly spaced over the bounds of the variable). The
number of points used in this numerical check is given by this num-
ber.

Examples

>>> from sympy import sin, pi

>>> from sympy.abc import x, y
>>> from sympy.codegen.rewriting import optimize
>>> from sympy.codegen.approximations import SeriesApprox
>>> bounds = {x: (-.1, .1), y: (pi-1, pi+1)}
>>> series_approx2 = SeriesApprox(bounds, reltol=1e-2)
>>> series_approx3 = SeriesApprox(bounds, reltol=1e-3)
>>> series_approx8 = SeriesApprox(bounds, reltol=1e-8)
>>> expr = sin(x)*sin(y)
>>> optimize(expr, [series_approx2])
x*(-y + (y - pi)**3/6 + pi)
>>> optimize(expr, [series_approx3])
(-x**3/6 + x)*sin(y)
>>> optimize(expr, [series_approx8])
sin(x)*sin(y)

5.8. Structural Details of Code Generation with SymPy 411

SymPy Documentation, Release 1.3

class sympy.codegen.approximations.SumApprox(bounds, reltol, **kwargs)

Approximates sum by neglecting small terms
If terms are expressions which can be determined to be monotonic, then bounds for those
expressions are added.
Parameters bounds : dict
Mapping expressions to length 2 tuple of bounds (low, high).
reltol : number
Threshold for when to ignore a term. Taken relative to the largest
lower bound among bounds.

Examples

>>> from sympy import exp

>>> from sympy.abc import x, y, z
>>> from sympy.codegen.rewriting import optimize
>>> from sympy.codegen.approximations import SumApprox
>>> bounds = {x: (-1, 1), y: (1000, 2000), z: (-10, 3)}
>>> sum_approx3 = SumApprox(bounds, reltol=1e-3)
>>> sum_approx2 = SumApprox(bounds, reltol=1e-2)
>>> sum_approx1 = SumApprox(bounds, reltol=1e-1)
>>> expr = 3*(x + y + exp(z))
>>> optimize(expr, [sum_approx3])
3*(x + y + exp(z))
>>> optimize(expr, [sum_approx2])
3*y + 3*exp(z)
>>> optimize(expr, [sum_approx1])
3*y

5.8.7 Classes for abstract syntax trees (sympy.codegen.ast)

Types used to represent a full function/module as an Abstract Syntax Tree.

Most types are small, and are merely used as tokens in the AST. A tree diagram has been
included below to illustrate the relationships between the AST types.

AST Type Tree

*Basic*
|--->AssignmentBase
| |--->Assignment
| |--->AugmentedAssignment
| |--->AddAugmentedAssignment
| |--->SubAugmentedAssignment
| |--->MulAugmentedAssignment
| |--->DivAugmentedAssignment
| |--->ModAugmentedAssignment
|
|--->CodeBlock
|
(continues on next page)

412 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

|
|--->Token
| |--->Attribute
| |--->For
| |--->String
| | |--->QuotedString
| | |--->Comment
| |--->Type
| | |--->IntBaseType
| | | |--->_SizedIntType
| | | |--->SignedIntType
| | | |--->UnsignedIntType
| | |--->FloatBaseType
| | |--->FloatType
| | |--->ComplexBaseType
| | |--->ComplexType
| |--->Node
| | |--->Variable
| | | |---> Pointer
| | |--->FunctionPrototype
| | |--->FunctionDefinition
| |--->Element
| |--->Declaration
| |--->While
| |--->Scope
| |--->Stream
| |--->Print
| |--->FunctionCall
| |--->BreakToken
| |--->ContinueToken
| |--->NoneToken
|
|--->Statement
|--->Return

Predefined types

A number of Type instances are provided in the sympy.codegen.ast module for convenience.
Perhaps the two most common ones for code-generation (of numeric codes) are float32 and
float64 (known as single and double precision respectively). There are also precision generic
versions of Types (for which the codeprinters selects the underlying data type at time of
printing): real, integer, complex_, bool_.
The other Type instances defined are:
• intc: Integer type used by C’s “int”.
• intp: Integer type used by C’s “unsigned”.
• int8, int16, int32, int64: n-bit integers.
• uint8, uint16, uint32, uint64: n-bit unsigned integers.
• float80: known as “extended precision” on modern x86/amd64 hardware.
• complex64: Complex number represented by two float32 numbers
• complex128: Complex number represented by two float64 numbers

5.8. Structural Details of Code Generation with SymPy 413

SymPy Documentation, Release 1.3

Using the nodes

It is possible to construct simple algorithms using the AST nodes. Let’s construct a loop
applying Newton’s method:

>>> from sympy import symbols, cos

>>> from sympy.codegen.ast import While, Assignment, aug_assign, Print
>>> t, dx, x = symbols('tol delta val')
>>> expr = cos(x) - x**3
>>> whl = While(abs(dx) > t, [
... Assignment(dx, -expr/expr.diff(x)),
... aug_assign(x, '+', dx),
... Print([x])
... ])
>>> from sympy.printing import pycode
>>> py_str = pycode(whl)
>>> print(py_str)
while (abs(delta) > tol):
delta = (val**3 - math.cos(val))/(-3*val**2 - math.sin(val))
val += delta
print(val)
>>> import math
>>> tol, val, delta = 1e-5, 0.5, float('inf')
>>> exec(py_str)
1.1121416371
0.909672693737
0.867263818209
0.865477135298
0.865474033111
>>> print('%3.1g' % (math.cos(val) - val**3))
-3e-11

If we want to generate Fortran code for the same while loop we simple call fcode:

>>> from sympy.printing.fcode import fcode

>>> print(fcode(whl, standard=2003, source_format='free'))
do while (abs(delta) > tol)
delta = (val**3 - cos(val))/(-3*val**2 - sin(val))
val = val + delta
print *, val
end do

There is a function constructing a loop (or a complete function) like this in sympy.codegen.
algorithms (page 441).
class sympy.codegen.ast.Assignment
Represents variable assignment for code generation.
Parameters lhs : Expr
Sympy object representing the lhs of the expression. These should
be singular objects, such as one would use in writing code. Notable
types include Symbol, MatrixSymbol, MatrixElement, and Indexed.
Types that subclass these types are also supported.
rhs : Expr
Sympy object representing the rhs of the expression. This can be any
type, provided its shape corresponds to that of the lhs. For example,

414 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

a Matrix type can be assigned to MatrixSymbol, but not to Symbol,

as the dimensions will not align.

Examples

>>> from sympy import symbols, MatrixSymbol, Matrix

>>> from sympy.codegen.ast import Assignment
>>> x, y, z = symbols('x, y, z')
>>> Assignment(x, y)
Assignment(x, y)
>>> Assignment(x, 0)
Assignment(x, 0)
>>> A = MatrixSymbol('A', 1, 3)
>>> mat = Matrix([x, y, z]).T
>>> Assignment(A, mat)
Assignment(A, Matrix([[x, y, z]]))
>>> Assignment(A[0, 1], x)
Assignment(A[0, 1], x)

class sympy.codegen.ast.AssignmentBase
Abstract base class for Assignment and AugmentedAssignment.

Attributes:

op [str] Symbol for assignment operator, e.g. “=”, “+=”, etc.

class sympy.codegen.ast.Attribute(possibly parametrized)

For use with sympy.codegen.ast.Node (page 422) (which takes instances of Attribute
as attrs).
Parameters name : str
parameters : Tuple

Examples

>>> from sympy.codegen.ast import Attribute

>>> volatile = Attribute('volatile')
>>> volatile
volatile
>>> print(repr(volatile))
Attribute(String('volatile'))
>>> a = Attribute('foo', [1, 2, 3])
>>> a
foo(1, 2, 3)
>>> a.parameters == (1, 2, 3)
True

class sympy.codegen.ast.AugmentedAssignment
Base class for augmented assignments.

5.8. Structural Details of Code Generation with SymPy 415

SymPy Documentation, Release 1.3

Attributes:

binop [str] Symbol for binary operation being applied in the assignment, such as “+”,
“*”, etc.

class sympy.codegen.ast.BreakToken
Represents ‘break’ in C/Python (‘exit’ in Fortran).
Use the premade instance break_ or instantiate manually.

Examples

>>> from sympy.printing import ccode, fcode

>>> from sympy.codegen.ast import break_
>>> ccode(break_)
'break'
>>> fcode(break_, source_format='free')
'exit'

class sympy.codegen.ast.CodeBlock
Represents a block of code
For now only assignments are supported. This restriction will be lifted in the future.
Useful attributes on this object are:
left_hand_sides: Tuple of left-hand sides of assignments, in order.
left_hand_sides: Tuple of right-hand sides of assignments, in order.
free_symbols: Free symbols of the expressions in the right-hand sides which do
not appear in the left-hand side of an assignment.
Useful methods on this object are:
topological_sort: Class method. Return a CodeBlock with assignments sorted so that
variables are assigned before they are used.
cse: Return a new CodeBlock with common subexpressions eliminated and pulled out
as assignments.

Example

>>> from sympy import symbols, ccode

>>> from sympy.codegen.ast import CodeBlock, Assignment
>>> x, y = symbols('x y')
>>> c = CodeBlock(Assignment(x, 1), Assignment(y, x + 1))
>>> print(ccode(c))
x = 1;
y = x + 1;

cse(symbols=None, optimizations=None, postprocess=None, order=’canonical’)

Return a new code block with common subexpressions eliminated
See the docstring of sympy.simplify.cse_main.cse() (page 1205) for more infor-
mation.

416 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, sin

>>> from sympy.codegen.ast import CodeBlock, Assignment
>>> x, y, z = symbols('x y z')

>>> c = CodeBlock(
... Assignment(x, 1),
... Assignment(y, sin(x) + 1),
... Assignment(z, sin(x) - 1),
... )
...
>>> c.cse()
CodeBlock(
Assignment(x, 1),
Assignment(x0, sin(x)),
Assignment(y, x0 + 1),
Assignment(z, x0 - 1)
)

classmethod topological_sort(assignments)
Return a CodeBlock with topologically sorted assignments so that variables are as-
signed before they are used.
The existing order of assignments is preserved as much as possible.
This function assumes that variables are assigned to only once.
This is a class constructor so that the default constructor for CodeBlock can error
when variables are used before they are assigned.

Example

>>> from sympy import symbols

>>> from sympy.codegen.ast import CodeBlock, Assignment
>>> x, y, z = symbols('x y z')

>>> assignments = [
... Assignment(x, y + z),
... Assignment(y, z + 1),
... Assignment(z, 2),
... ]
>>> CodeBlock.topological_sort(assignments)
CodeBlock(
Assignment(z, 2),
Assignment(y, z + 1),
Assignment(x, y + z)
)

class sympy.codegen.ast.Comment
Represents a comment.
class sympy.codegen.ast.ComplexType
Represents a complex floating point number.
class sympy.codegen.ast.ContinueToken
Represents ‘continue’ in C/Python (‘cycle’ in Fortran)

5.8. Structural Details of Code Generation with SymPy 417

SymPy Documentation, Release 1.3

Use the premade instance continue_ or instantiate manually.

Examples

>>> from sympy.printing import ccode, fcode

>>> from sympy.codegen.ast import continue_
>>> ccode(continue_)
'continue'
>>> fcode(continue_, source_format='free')
'cycle'

class sympy.codegen.ast.Declaration
Represents a variable declaration
Parameters variable : Variable

Examples

>>> from sympy import Symbol

>>> from sympy.codegen.ast import Declaration, Type, Variable, integer, untyped
>>> z = Declaration('z')
>>> z.variable.type == untyped
True
>>> z.variable.value == None
True

class sympy.codegen.ast.Element
Element in (a possibly N-dimensional) array.

Examples

>>> from sympy.codegen.ast import Element

>>> elem = Element('x', 'ijk')
>>> elem.symbol.name == 'x'
True
>>> elem.indices
(i, j, k)
>>> from sympy import ccode
>>> ccode(elem)
'x[i][j][k]'
>>> ccode(Element('x', 'ijk', strides='lmn', offset='o'))
'x[i*l + j*m + k*n + o]'

class sympy.codegen.ast.FloatBaseType
Represents a floating point number type.
cast_nocheck
alias of sympy.core.numbers.Float (page 143)
class sympy.codegen.ast.FloatType
Represents a floating point type with fixed bit width.
Base 2 & one sign bit is assumed.

418 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters name : str

Name of the type.
nbits : integer
Number of bits used (storage).
nmant : integer
Number of bits used to represent the mantissa.
nexp : integer
Number of bits used to represent the mantissa.

Examples

>>> from sympy import S, Float

>>> from sympy.codegen.ast import FloatType
>>> half_precision = FloatType('f16', nbits=16, nmant=10, nexp=5)
>>> half_precision.max
65504
>>> half_precision.tiny == S(2)**-14
True
>>> half_precision.eps == S(2)**-10
True
>>> half_precision.dig == 3
True
>>> half_precision.decimal_dig == 5
True
>>> half_precision.cast_check(1.0)
1.0
>>> half_precision.cast_check(1e5) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Maximum value for data type smaller than new value.

cast_nocheck(value)
Casts without checking if out of bounds or subnormal.
decimal_dig
Number of digits needed to store & load without loss.
Number of decimal digits needed to guarantee that two consecutive conversions
(float -> text -> float) to be idempotent. This is useful when one do not want to loose
precision due to rounding errors when storing a floating point value as text.
dig
Number of decimal digits that are guaranteed to be preserved in text.
When converting text -> float -> text, you are guaranteed that at least dig number
of digits are preserved with respect to rounding or overflow.
eps
Difference between 1.0 and the next representable value.
max
Maximum value representable.

5.8. Structural Details of Code Generation with SymPy 419

SymPy Documentation, Release 1.3

max_exponent
The largest positive number n, such that 2**(n - 1) is a representable finite value.
min_exponent
The lowest negative number n, such that 2**(n - 1) is a valid normalized number.
tiny
The minimum positive normalized value.
class sympy.codegen.ast.For
Represents a ‘for-loop’ in the code.
Expressions are of the form:
“for target in iter: body…”

Parameters target : symbol

iter : iterable body : CodeBlock or iterable
! When passed an iterable it is used to instantiate a CodeBlock.

Examples

>>> from sympy import symbols, Range

>>> from sympy.codegen.ast import aug_assign, For
>>> x, i, j, k = symbols('x i j k')
>>> for_i = For(i, Range(10), [aug_assign(x, '+', i*j*k)])
>>> for_i # doctest: -NORMALIZE_WHITESPACE
For(i, iterable=Range(0, 10, 1), body=CodeBlock(
AddAugmentedAssignment(x, i*j*k)
))
>>> for_ji = For(j, Range(7), [for_i])
>>> for_ji # doctest: -NORMALIZE_WHITESPACE
For(j, iterable=Range(0, 7, 1), body=CodeBlock(
For(i, iterable=Range(0, 10, 1), body=CodeBlock(
AddAugmentedAssignment(x, i*j*k)
))
))
>>> for_kji =For(k, Range(5), [for_ji])
>>> for_kji # doctest: -NORMALIZE_WHITESPACE
For(k, iterable=Range(0, 5, 1), body=CodeBlock(
For(j, iterable=Range(0, 7, 1), body=CodeBlock(
For(i, iterable=Range(0, 10, 1), body=CodeBlock(
AddAugmentedAssignment(x, i*j*k)
))
))
))

class sympy.codegen.ast.FunctionCall
Represents a call to a function in the code.
Parameters name : str
function_args : Tuple

420 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.codegen.ast import FunctionCall

>>> from sympy.printing.pycode import pycode
>>> fcall = FunctionCall('foo', 'bar baz'.split())
>>> print(pycode(fcall))
foo(bar, baz)

class sympy.codegen.ast.FunctionDefinition
Represents a function definition in the code.
Parameters return_type : Type
name : str
parameters: iterable of Variable instances
body : CodeBlock or iterable
attrs : iterable of Attribute instances

Examples

>>> from sympy import symbols

>>> from sympy.codegen.ast import real, FunctionPrototype
>>> from sympy.printing.ccode import ccode
>>> x, y = symbols('x y', real=True)
>>> fp = FunctionPrototype(real, 'foo', [x, y])
>>> ccode(fp)
'double foo(double x, double y)'
>>> from sympy.codegen.ast import FunctionDefinition, Return
>>> body = [Return(x*y)]
>>> fd = FunctionDefinition.from_FunctionPrototype(fp, body)
>>> print(ccode(fd))
double foo(double x, double y){
return x*y;
}

class sympy.codegen.ast.FunctionPrototype
Represents a function prototype
Allows the user to generate forward declaration in e.g. C/C++.
Parameters return_type : Type
name : str
parameters: iterable of Variable instances
attrs : iterable of Attribute instances

Examples

>>> from sympy import symbols

>>> from sympy.codegen.ast import real, FunctionPrototype
>>> from sympy.printing.ccode import ccode
>>> x, y = symbols('x y', real=True)
(continues on next page)

5.8. Structural Details of Code Generation with SymPy 421

SymPy Documentation, Release 1.3

(continued from previous page)

>>> fp = FunctionPrototype(real, 'foo', [x, y])
>>> ccode(fp)
'double foo(double x, double y)'

class sympy.codegen.ast.IntBaseType
Integer base type, contains no size information.
class sympy.codegen.ast.Node
Subclass of Token, carrying the attribute ‘attrs’ (Tuple)

Examples

>>> from sympy.codegen.ast import Node, value_const, pointer_const

>>> n1 = Node([value_const])
>>> n1.attr_params('value_const') # get the parameters of attribute (by name)
()
>>> from sympy.codegen.fnodes import dimension
>>> n2 = Node([value_const, dimension(5, 3)])
>>> n2.attr_params(value_const) # get the parameters of attribute (by Attribute␣
,→instance)

()
>>> n2.attr_params('dimension') # get the parameters of attribute (by name)
(5, 3)
>>> n2.attr_params(pointer_const) is None
True

attr_params(looking_for)
Returns the parameters of the Attribute with name looking_for in self.attrs
class sympy.codegen.ast.NoneToken
The AST equivalence of Python’s NoneType
The corresponding instance of Python’s None is none.

Examples

>>> from sympy.codegen.ast import none, Variable

>>> from sympy.printing.pycode import pycode
>>> print(pycode(Variable('x').as_Declaration(value=none)))
x = None

class sympy.codegen.ast.Pointer
Represents a pointer. See Variable.

Examples

Can create instances of Element:

>>> from sympy import Symbol
>>> from sympy.codegen.ast import Pointer
>>> i = Symbol('i', integer=True)
>>> p = Pointer('x')
(continues on next page)

422 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> p[i+1]
Element(x, indices=((i + 1,),))

class sympy.codegen.ast.Print
Represents print command in the code.
Parameters formatstring : str
*args : Basic instances (or convertible to such through sympify)

Examples

>>> from sympy.codegen.ast import Print

>>> from sympy.printing.pycode import pycode
>>> print(pycode(Print('x y'.split(), ”coordinate: %12.5g %12.5g”)))
print(”coordinate: %12.5g %12.5g” % (x, y))

class sympy.codegen.ast.QuotedString
Represents a string which should be printed with quotes.
class sympy.codegen.ast.Return
Represents a return command in the code.
class sympy.codegen.ast.Scope
Represents a scope in the code.
Parameters body : CodeBlock or iterable
When passed an iterable it is used to instantiate a CodeBlock.
class sympy.codegen.ast.SignedIntType
Represents a signed integer type.
class sympy.codegen.ast.Stream
Represents a stream.
There are two predefined Stream instances stdout & stderr.
Parameters name : str

Examples

>>> from sympy import Symbol

>>> from sympy.printing.pycode import pycode
>>> from sympy.codegen.ast import Print, stderr, QuotedString
>>> print(pycode(Print(['x'], file=stderr)))
print(x, file=sys.stderr)
>>> x = Symbol('x')
>>> print(pycode(Print([QuotedString('x')], file=stderr))) # print literally ”x”
print(”x”, file=sys.stderr)

class sympy.codegen.ast.String
SymPy object representing a string.
Atomic object which is not an expression (as opposed to Symbol).
Parameters text : str

5.8. Structural Details of Code Generation with SymPy 423

SymPy Documentation, Release 1.3

Examples

>>> from sympy.codegen.ast import String

>>> f = String('foo')
>>> f
foo
>>> str(f)
'foo'
>>> f.text
'foo'
>>> print(repr(f))
String('foo')

class sympy.codegen.ast.Token
Base class for the AST types.
Defining fields are set in __slots__. Attributes (defined in __slots__) are only allowed
to contain instances of Basic (unless atomic, see String). The arguments to __new__()
correspond to the attributes in the order defined in __slots__`. The ``defaults class
attribute is a dictionary mapping attribute names to their default values.
Subclasses should not need to override the __new__() method. They may define a class
or static method named _construct_<attr> for each attribute to process the value
passed to __new__(). Attributes listed in the class attribute not_in_args are not passed
to sympy.Basic.
kwargs(exclude=(), apply=None)
Get instance’s attributes as dict of keyword arguments.
Parameters exclude : collection of str
Collection of keywords to exclude.
apply : callable, optional
Function to apply to all values.
class sympy.codegen.ast.Type
Represents a type.
The naming is a super-set of NumPy naming. Type has a classmethod from_expr which
offer type deduction. It also has a method cast_check which casts the argument to its
type, possibly raising an exception if rounding error is not within tolerances, or if the
value is not representable by the underlying data type (e.g. unsigned integers).
Parameters name : str
Name of the type, e.g. object, int16, float16 (where the latter two
would use the Type sub-classes IntType and FloatType respectively).
If a Type instance is given, the said instance is returned.

References

[R25]

424 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.codegen.ast import Type

>>> t = Type.from_expr(42)
>>> t
integer
>>> print(repr(t))
IntBaseType(String('integer'))
>>> from sympy.codegen.ast import uint8
>>> uint8.cast_check(-1) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Minimum value for data type bigger than new value.
>>> from sympy.codegen.ast import float32
>>> v6 = 0.123456
>>> float32.cast_check(v6)
0.123456
>>> v10 = 12345.67894
>>> float32.cast_check(v10) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Casting gives a significantly different value.
>>> boost_mp50 = Type('boost::multiprecision::cpp_dec_float_50')
>>> from sympy import Symbol
>>> from sympy.printing.cxxcode import cxxcode
>>> from sympy.codegen.ast import Declaration, Variable
>>> cxxcode(Declaration(Variable('x', type=boost_mp50)))
'boost::multiprecision::cpp_dec_float_50 x'

cast_check(value, rtol=None, atol=0, limits=None, precision_targets=None)

Casts a value to the data type of the instance.
Parameters value : number
rtol : floating point number
Relative tolerance. (will be deduced if not given).
atol : floating point number
Absolute tolerance (in addition to rtol).
limits : dict
Values given by limits.h, x86/IEEE754 defaults if not given. Default:
default_limits.
type_aliases : dict
Maps substitutions for Type, e.g. {integer: int64, real: float32}

Examples

>>> from sympy.codegen.ast import Type, integer, float32, int8

>>> integer.cast_check(3.0) == 3
True
>>> float32.cast_check(1e-40) # doctest: +ELLIPSIS
Traceback (most recent call last):
(continues on next page)

5.8. Structural Details of Code Generation with SymPy 425

SymPy Documentation, Release 1.3

(continued from previous page)

...
ValueError: Minimum value for data type bigger than new value.
>>> int8.cast_check(256) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Maximum value for data type smaller than new value.
>>> v10 = 12345.67894
>>> float32.cast_check(v10) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Casting gives a significantly different value.
>>> from sympy.codegen.ast import float64
>>> float64.cast_check(v10)
12345.67894
>>> from sympy import Float
>>> v18 = Float('0.123456789012345646')
>>> float64.cast_check(v18)
Traceback (most recent call last):
...
ValueError: Casting gives a significantly different value.
>>> from sympy.codegen.ast import float80
>>> float80.cast_check(v18)
0.123456789012345649

classmethod from_expr(expr)
Deduces type from an expression or a Symbol.
Parameters expr : number or SymPy object
The type will be deduced from type or properties.
Raises ValueError when type deduction fails.

Examples

>>> from sympy.codegen.ast import Type, integer, complex_

>>> Type.from_expr(2) == integer
True
>>> from sympy import Symbol
>>> Type.from_expr(Symbol('z', complex=True)) == complex_
True
>>> Type.from_expr(sum) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Could not deduce type from expr.

class sympy.codegen.ast.UnsignedIntType
Represents an unsigned integer type.
class sympy.codegen.ast.Variable
Represents a variable
Parameters symbol : Symbol
type : Type (optional)
Type of the variable.

426 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

attrs : iterable of Attribute instances

Will be stored as a Tuple.

Examples

>>> from sympy import Symbol

>>> from sympy.codegen.ast import Variable, float32, integer
>>> x = Symbol('x')
>>> v = Variable(x, type=float32)
>>> v.attrs
()
>>> v == Variable('x')
False
>>> v == Variable('x', type=float32)
True
>>> v
Variable(x, type=float32)

One may also construct a Variable instance with the type deduced from assumptions
about the symbol using the deduced classmethod:

>>> i = Symbol('i', integer=True)

>>> v = Variable.deduced(i)
>>> v.type == integer
True
>>> v == Variable('i')
False
>>> from sympy.codegen.ast import value_const
>>> value_const in v.attrs
False
>>> w = Variable('w', attrs=[value_const])
>>> w
Variable(w, attrs=(value_const,))
>>> value_const in w.attrs
True
>>> w.as_Declaration(value=42)
Declaration(Variable(w, value=42, attrs=(value_const,)))

as_Declaration(**kwargs)
Convenience method for creating a Declaration instance.
If the variable of the Declaration need to wrap a modified variable keyword argu-
ments may be passed (overriding e.g. the value of the Variable instance).

Examples

>>> from sympy.codegen.ast import Variable

>>> x = Variable('x')
>>> decl1 = x.as_Declaration()
>>> decl1.variable.value == None
True
>>> decl2 = x.as_Declaration(value=42.0)
>>> decl2.variable.value == 42
True

5.8. Structural Details of Code Generation with SymPy 427

SymPy Documentation, Release 1.3

classmethod deduced(symbol, value=None, attrs=(), cast_check=True)

Alt. constructor with type deduction from Type.from_expr.
Deduces type primarily from symbol, secondarily from value.
Parameters symbol : Symbol
value : expr
(optional) value of the variable.
attrs : iterable of Attribute instances
cast_check : bool
Whether to apply Type.cast_check on value.

Examples

>>> from sympy import Symbol

>>> from sympy.codegen.ast import Variable, complex_
>>> n = Symbol('n', integer=True)
>>> str(Variable.deduced(n).type)
'integer'
>>> x = Symbol('x', real=True)
>>> v = Variable.deduced(x)
>>> v.type
real
>>> z = Symbol('z', complex=True)
>>> Variable.deduced(z).type == complex_
True

class sympy.codegen.ast.While
Represents a ‘for-loop’ in the code.
Expressions are of the form:
“while condition: body…”

Parameters condition : expression convertable to Boolean

body : CodeBlock or iterable
When passed an iterable it is used to instantiate a CodeBlock.

Examples

>>> from sympy import symbols, Gt, Abs

>>> from sympy.codegen import aug_assign, Assignment, While
>>> x, dx = symbols('x dx')
>>> expr = 1 - x**2
>>> whl = While(Gt(Abs(dx), 1e-9), [
... Assignment(dx, -expr/expr.diff(x)),
... aug_assign(x, '+', dx)
... ])

sympy.codegen.ast.aug_assign(lhs, op, rhs)

Create ‘lhs op= rhs’.

428 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Represents augmented variable assignment for code generation. This is a convenience

function. You can also use the AugmentedAssignment classes directly, like AddAug-
mentedAssignment(x, y).
Parameters lhs : Expr
Sympy object representing the lhs of the expression. These should
be singular objects, such as one would use in writing code. Notable
types include Symbol, MatrixSymbol, MatrixElement, and Indexed.
Types that subclass these types are also supported.
op : str
Operator (+, -, /, *, %).
rhs : Expr
Sympy object representing the rhs of the expression. This can be any
type, provided its shape corresponds to that of the lhs. For example,
a Matrix type can be assigned to MatrixSymbol, but not to Symbol,
as the dimensions will not align.

Examples

>>> from sympy import symbols

>>> from sympy.codegen.ast import aug_assign
>>> x, y = symbols('x, y')
>>> aug_assign(x, '+', y)
AddAugmentedAssignment(x, y)

5.8.8 Special C math functions (sympy.codegen.cfunctions)

This module contains SymPy functions mathcin corresponding to special math functions in
the C standard library (since C99, also available in C++11).
The functions defined in this module allows the user to express functions such as expm1 as a
SymPy function for symbolic manipulation.
class sympy.codegen.cfunctions.Cbrt
Represents the cube root function.
The reason why one would use Cbrt(x) over cbrt(x) is that the latter is internally rep-
resented as Pow(x, Rational(1, 3)) which may not be what one wants when doing
code-generation.
See also:
Sqrt (page 430)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import Cbrt
>>> Cbrt(x)
Cbrt(x)
(continues on next page)

5.8. Structural Details of Code Generation with SymPy 429

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Cbrt(x).diff(x)
1/(3*x**(2/3))

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.Sqrt
Represents the square root function.
The reason why one would use Sqrt(x) over sqrt(x) is that the latter is internally
represented as Pow(x, S.Half) which may not be what one wants when doing code-
generation.
See also:
Cbrt (page 429)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import Sqrt
>>> Sqrt(x)
Sqrt(x)
>>> Sqrt(x).diff(x)
1/(2*sqrt(x))

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.exp2
Represents the exponential function with base two.
The benefit of using exp2(x) over 2**x is that the latter is not as efficient under finite
precision arithmetic.
See also:
log2 (page 432)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import exp2
>>> exp2(2).evalf() == 4
True
>>> exp2(x).diff(x)
log(2)*exp2(x)

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.expm1
Represents the exponential function minus one.
The benefit of using expm1(x) over exp(x) - 1 is that the latter is prone to cancellation
under finite precision arithmetic when x is close to zero.

430 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
log1p (page 432)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import expm1
>>> '%.0e' % expm1(1e-99).evalf()
'1e-99'
>>> from math import exp
>>> exp(1e-99) - 1
0.0
>>> expm1(x).diff(x)
exp(x)

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.fma
Represents “fused multiply add”.
The benefit of using fma(x, y, z) over x*y + z is that, under finite precision arith-
metic, the former is supported by special instructions on some CPUs.

Examples

>>> from sympy.abc import x, y, z

>>> from sympy.codegen.cfunctions import fma
>>> fma(x, y, z).diff(x)
y

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.hypot
Represents the hypotenuse function.
The hypotenuse function is provided by e.g. the math library in the C99 standard, hence
one may want to represent the function symbolically when doing code-generation.

Examples

>>> from sympy.abc import x, y

>>> from sympy.codegen.cfunctions import hypot
>>> hypot(3, 4).evalf() == 5
True
>>> hypot(x, y)
hypot(x, y)
>>> hypot(x, y).diff(x)
x/hypot(x, y)

fdiff(argindex=1)
Returns the first derivative of this function.

5.8. Structural Details of Code Generation with SymPy 431

SymPy Documentation, Release 1.3

class sympy.codegen.cfunctions.log10
Represents the logarithm function with base ten.
See also:
log2 (page 432)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import log10
>>> log10(100).evalf() == 2
True
>>> log10(x).diff(x)
1/(x*log(10))

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.log1p
Represents the natural logarithm of a number plus one.
The benefit of using log1p(x) over log(x + 1) is that the latter is prone to cancellation
under finite precision arithmetic when x is close to zero.
See also:
expm1 (page 430)

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import log1p
>>> from sympy.core.function import expand_log
>>> '%.0e' % expand_log(log1p(1e-99)).evalf()
'1e-99'
>>> from math import log
>>> log(1 + 1e-99)
0.0
>>> log1p(x).diff(x)
1/(x + 1)

fdiff(argindex=1)
Returns the first derivative of this function.
class sympy.codegen.cfunctions.log2
Represents the logarithm function with base two.
The benefit of using log2(x) over log(x)/log(2) is that the latter is not as efficient
under finite precision arithmetic.
See also:
exp2 (page 430), log10 (page 431)

432 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cfunctions import log2
>>> log2(4).evalf() == 2
True
>>> log2(x).diff(x)
1/(x*log(2))

fdiff(argindex=1)
Returns the first derivative of this function.

5.8.9 C specific AST nodes (sympy.codegen.cnodes)

AST nodes specific to the C family of languages

class sympy.codegen.cnodes.CommaOperator
Represents the comma operator in C
class sympy.codegen.cnodes.Label
Label for use with e.g. goto statement.

Examples

>>> from sympy.codegen.cnodes import Label

>>> from sympy.printing.ccode import ccode
>>> print(ccode(Label('foo')))
foo:

class sympy.codegen.cnodes.PostDecrement
Represents the post-decrement operator
class sympy.codegen.cnodes.PostIncrement
Represents the post-increment operator
class sympy.codegen.cnodes.PreDecrement
Represents the pre-decrement operator

Examples

>>> from sympy.abc import x

>>> from sympy.codegen.cnodes import PreDecrement
>>> from sympy.printing.ccode import ccode
>>> ccode(PreDecrement(x))
'--(x)'

class sympy.codegen.cnodes.PreIncrement
Represents the pre-increment operator
sympy.codegen.cnodes.alignof(arg)
Generate of FunctionCall instance for calling ‘alignof’
class sympy.codegen.cnodes.goto
Represents goto in C

5.8. Structural Details of Code Generation with SymPy 433

SymPy Documentation, Release 1.3

sympy.codegen.cnodes.sizeof(arg)
Generate of FunctionCall instance for calling ‘sizeof’

Examples

>>> from sympy.codegen.ast import real

>>> from sympy.codegen.cnodes import sizeof
>>> from sympy.printing.ccode import ccode
>>> ccode(sizeof(real))
'sizeof(double)'

class sympy.codegen.cnodes.struct
Represents a struct in C
class sympy.codegen.cnodes.union
Represents a union in C

5.8.10 C++ specific AST nodes (sympy.codegen.cxxnodes)

AST nodes specific to C++.

class sympy.codegen.cxxnodes.using
Represents a ‘using’ statement in C++

5.8.11 Fortran specific AST nodes (sympy.codegen.fnodes)

AST nodes specific to Fortran.

The functions defined in this module allows the user to express functions such as dsign as a
SymPy function for symbolic manipulation.
class sympy.codegen.fnodes.ArrayConstructor
Represents an array constructor

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.fnodes import ArrayConstructor
>>> ac = ArrayConstructor([1, 2, 3])
>>> fcode(ac, standard=95, source_format='free')
'(/1, 2, 3/)'
>>> fcode(ac, standard=2003, source_format='free')
'[1, 2, 3]'

class sympy.codegen.fnodes.Do
Represents a Do loop in in Fortran

Examples

434 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import symbols

>>> from sympy.codegen.ast import aug_assign, Print
>>> from sympy.codegen.fnodes import Do
>>> from sympy.printing import fcode
>>> i, n = symbols('i n', integer=True)
>>> r = symbols('r', real=True)
>>> body = [aug_assign(r, '+', 1/i), Print([i, r])]
>>> do1 = Do(body, i, 1, n)
>>> print(fcode(do1, source_format='free'))
do i = 1, n
r = r + 1d0/i
print *, i, r
end do
>>> do2 = Do(body, i, 1, n, 2)
>>> print(fcode(do2, source_format='free'))
do i = 1, n, 2
r = r + 1d0/i
print *, i, r
end do

class sympy.codegen.fnodes.Extent
Represents a dimension extent.

Examples

>>> from sympy.codegen.fnodes import Extent

>>> e = Extent(-3, 3) # -3, -2, -1, 0, 1, 2, 3
>>> from sympy.printing import fcode
>>> fcode(e, source_format='free')
'-3:3'
>>> from sympy.codegen.ast import Variable, real
>>> from sympy.codegen.fnodes import dimension, intent_out
>>> dim = dimension(e, e)
>>> arr = Variable('x', real, attrs=[dim, intent_out])
>>> fcode(arr.as_Declaration(), source_format='free', standard=2003)
'real*8, dimension(-3:3, -3:3), intent(out) :: x'

class sympy.codegen.fnodes.FortranReturn
AST node explicitly mapped to a fortran “return”.
Because a return statement in fortran is different from C, and in order to aid reuse of
our codegen ASTs the ordinary .codegen.ast.Return is interpreted as assignment to
the result variable of the function. If one for some reason needs to generate a fortran
RETURN statement, this node should be used.

Examples

>>> from sympy.codegen.fnodes import FortranReturn

>>> from sympy.printing import fcode
>>> fcode(FortranReturn('x'))
' return x'

class sympy.codegen.fnodes.GoTo
Represents a goto statement in Fortran

5.8. Structural Details of Code Generation with SymPy 435

SymPy Documentation, Release 1.3

Examples

>>> from sympy.codegen.fnodes import GoTo

>>> go = GoTo([10, 20, 30], 'i')
>>> from sympy.printing import fcode
>>> fcode(go, source_format='free')
'go to (10, 20, 30), i'

class sympy.codegen.fnodes.ImpliedDoLoop
Represents an implied do loop in Fortran

Examples

>>> from sympy import Symbol, fcode

>>> from sympy.codegen.fnodes import ImpliedDoLoop, ArrayConstructor
>>> i = Symbol('i', integer=True)
>>> idl = ImpliedDoLoop(i**3, i, -3, 3, 2) # -27, -1, 1, 27
>>> ac = ArrayConstructor([-28, idl, 28]) # -28, -27, -1, 1, 27, 28
>>> fcode(ac, standard=2003, source_format='free')
'[-28, (i**3, i = -3, 3, 2), 28]'

class sympy.codegen.fnodes.Module
Represents a module in Fortran

Examples

>>> from sympy.codegen.fnodes import Module

>>> from sympy.printing import fcode
>>> print(fcode(Module('signallib', ['implicit none'], []), source_format='free'))
module signallib
implicit none
<BLANKLINE>
contains
<BLANKLINE>
<BLANKLINE>
end module

class sympy.codegen.fnodes.Program
Represents a ‘program’ block in Fortran

Examples

>>> from sympy.codegen.ast import Print

>>> from sympy.codegen.fnodes import Program
>>> prog = Program('myprogram', [Print([42])])
>>> from sympy.printing import fcode
>>> print(fcode(prog, source_format='free'))
program myprogram
print *, 42
end program

436 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.codegen.fnodes.Subroutine
Represents a subroutine in Fortran

Examples

>>> from sympy import symbols

>>> from sympy.codegen.ast import Print
>>> from sympy.codegen.fnodes import Subroutine
>>> from sympy.printing import fcode
>>> x, y = symbols('x y', real=True)
>>> sub = Subroutine('mysub', [x, y], [Print([x**2 + y**2, x*y])])
>>> print(fcode(sub, source_format='free', standard=2003))
subroutine mysub(x, y)
real*8 :: x
real*8 :: y
print *, x**2 + y**2, x*y
end subroutine

class sympy.codegen.fnodes.SubroutineCall
Represents a call to a subroutine in Fortran

Examples

>>> from sympy.codegen.fnodes import SubroutineCall

>>> from sympy.printing import fcode
>>> fcode(SubroutineCall('mysub', 'x y'.split()))
' call mysub(x, y)'

sympy.codegen.fnodes.allocated(array)
Creates an AST node for a function call to Fortran’s “allocated(…)”

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.fnodes import allocated
>>> alloc = allocated('x')
>>> fcode(alloc, source_format='free')
'allocated(x)'

sympy.codegen.fnodes.array(symbol, dim, intent=None, **kwargs)

Convenience function for creating a Variable instance for a Fortran array
Parameters symbol : symbol
dim : Attribute or iterable
If dim is an Attribute it need to have the name ‘dimension’. If it is
not an Attribute, then it is passsed to dimension() (page 438) as
*dim
intent : str
One of: ‘in’, ‘out’, ‘inout’ or None
**kwargs:

5.8. Structural Details of Code Generation with SymPy 437

SymPy Documentation, Release 1.3

Keyword arguments for Variable (‘type’ & ‘value’)

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.ast import integer, real
>>> from sympy.codegen.fnodes import array
>>> arr = array('a', '*', 'in', type=integer)
>>> print(fcode(arr.as_Declaration(), source_format='free', standard=2003))
integer*4, dimension(*), intent(in) :: a
>>> x = array('x', [3, ':', ':'], intent='out', type=real)
>>> print(fcode(x.as_Declaration(value=1), source_format='free', standard=2003))
real*8, dimension(3, :, :), intent(out) :: x = 1

sympy.codegen.fnodes.bind_C(name=None)
Creates an Attribute bind_C with a name
Parameters name : str

Examples

>>> from sympy import Symbol

>>> from sympy.printing import fcode
>>> from sympy.codegen.ast import FunctionDefinition, real, Return, Variable
>>> from sympy.codegen.fnodes import array, sum_, size, bind_C
>>> a = Symbol('a', real=True)
>>> s = Symbol('s', integer=True)
>>> arr = array(a, dim=[s], intent='in')
>>> body = [Return((sum_(a**2)/s)**.5)]
>>> fd = FunctionDefinition(real, 'rms', [arr, s], body, attrs=[bind_C('rms')])
>>> print(fcode(fd, source_format='free', standard=2003))
real*8 function rms(a, s) bind(C, name=”rms”)
real*8, dimension(s), intent(in) :: a
integer*4 :: s
rms = sqrt(sum(a**2)/s)
end function

class sympy.codegen.fnodes.cmplx
Fortran complex conversion function.
sympy.codegen.fnodes.dimension(*args)
Creates a ‘dimension’ Attribute with (up to 7) extents.

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.fnodes import dimension, intent_in
>>> dim = dimension('2', ':') # 2 rows, runtime determined number of columns
>>> from sympy.codegen.ast import Variable, integer
>>> arr = Variable('a', integer, attrs=[dim, intent_in])
>>> fcode(arr.as_Declaration(), source_format='free', standard=2003)
'integer*4, dimension(2, :), intent(in) :: a'

438 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.codegen.fnodes.dsign
Fortran sign intrinsic for double precision arguments.
class sympy.codegen.fnodes.isign
Fortran sign intrinsic for integer arguments.
class sympy.codegen.fnodes.kind
Fortran kind function.
sympy.codegen.fnodes.lbound(array, dim=None, kind=None)
Creates an AST node for a function call to Fortran’s “lbound(…)”
Parameters array : Symbol or String
dim : expr
kind : expr

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.fnodes import lbound
>>> lb = lbound('arr', dim=2)
>>> fcode(lb, source_format='free')
'lbound(arr, 2)'

class sympy.codegen.fnodes.literal_dp
Fortran double precision real literal

Attributes

is_irrational
is_rational

class sympy.codegen.fnodes.literal_sp
Fortran single precision real literal

Attributes

is_irrational
is_rational

class sympy.codegen.fnodes.merge
Fortran merge function
sympy.codegen.fnodes.reshape(source, shape, pad=None, order=None)
Creates an AST node for a function call to Fortran’s “reshape(…)”
Parameters source : Symbol or String
shape : ArrayExpr
sympy.codegen.fnodes.shape(source, kind=None)
Creates an AST node for a function call to Fortran’s “shape(…)”

5.8. Structural Details of Code Generation with SymPy 439

SymPy Documentation, Release 1.3

Parameters source : Symbol or String

kind : expr

Examples

>>> from sympy.printing import fcode

>>> from sympy.codegen.fnodes import shape
>>> shp = shape('x')
>>> fcode(shp, source_format='free')
'shape(x)'

sympy.codegen.fnodes.size(array, dim=None, kind=None)

Creates an AST node for a function call to Fortran’s “size(…)”

Examples

>>> from sympy import Symbol

>>> from sympy.printing import fcode
>>> from sympy.codegen.ast import FunctionDefinition, real, Return, Variable
>>> from sympy.codegen.fnodes import array, sum_, size
>>> a = Symbol('a', real=True)
>>> body = [Return((sum_(a**2)/size(a))**.5)]
>>> arr = array(a, dim=[':'], intent='in')
>>> fd = FunctionDefinition(real, 'rms', [arr], body)
>>> print(fcode(fd, source_format='free', standard=2003))
real*8 function rms(a)
real*8, dimension(:), intent(in) :: a
rms = sqrt(sum(a**2)*1d0/size(a))
end function

class sympy.codegen.fnodes.use
Represents a use statement in Fortran

Examples

>>> from sympy.codegen.fnodes import use

>>> from sympy.printing import fcode
>>> fcode(use('signallib'), source_format='free')
'use signallib'
>>> fcode(use('signallib', [('metric', 'snr')]), source_format='free')
'use signallib, metric => snr'
>>> fcode(use('signallib', only=['snr', 'convolution2d']), source_format='free')
'use signallib, only: snr, convolution2d'

class sympy.codegen.fnodes.use_rename
Represents a renaming in a use statement in Fortran

440 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.codegen.fnodes import use_rename, use

>>> from sympy.printing import fcode
>>> ren = use_rename(”thingy”, ”convolution2d”)
>>> print(fcode(ren, source_format='free'))
thingy => convolution2d
>>> full = use('signallib', only=['snr', ren])
>>> print(fcode(full, source_format='free'))
use signallib, only: snr, thingy => convolution2d

5.8.12 Algorithms (sympy.codegen.algorithms)

sympy.codegen.algorithms.newtons_method(expr, wrt, atol=1e-12, delta=None,

debug=False, itermax=None,
counter=None)
Generates an AST for Newton-Raphson method (a root-finding algorithm).
Returns an abstract syntax tree (AST) based on sympy.codegen.ast for Netwon’s
method of root-finding.
Parameters expr : expression
wrt : Symbol
With respect to, i.e. what is the variable.
atol : number or expr
Absolute tolerance (stopping criterion)
delta : Symbol
Will be a Dummy if None.
debug : bool
Whether to print convergence information during iterations
itermax : number or expr
Maximum number of iterations.
counter : Symbol
Will be a Dummy if None.

References

[R26]

Examples

>>> from sympy import symbols, cos

>>> from sympy.codegen.ast import Assignment
>>> from sympy.codegen.algorithms import newtons_method
>>> x, dx, atol = symbols('x dx atol')
(continues on next page)

5.8. Structural Details of Code Generation with SymPy 441

SymPy Documentation, Release 1.3

(continued from previous page)

>>> expr = cos(x) - x**3
>>> algo = newtons_method(expr, x, atol, dx)
>>> algo.has(Assignment(dx, -expr/expr.diff(x)))
True

sympy.codegen.algorithms.newtons_method_function(expr, wrt, params=None,

func_name=’newton’, at-
trs=(), **kwargs)
Generates an AST for a function implementing the Newton-Raphson method.
Parameters expr : expression
wrt : Symbol
With respect to, i.e. what is the variable
params : iterable of symbols
Symbols appearing in expr that are taken as constants during the it-
erations (these will be accepted as parameters to the generated func-
tion).
func_name : str
Name of the generated function.
attrs : Tuple
Attribute instances passed as attrs to FunctionDefinition.
**kwargs :
Keyword arguments passed to sympy.codegen.algorithms.
newtons_method() (page 441).
See also:
-

Examples

>>> from sympy import symbols, cos

>>> from sympy.codegen.algorithms import newtons_method_function
>>> from sympy.codegen.pyutils import render_as_module
>>> from sympy.core.compatibility import exec_
>>> x = symbols('x')
>>> expr = cos(x) - x**3
>>> func = newtons_method_function(expr, x)
>>> py_mod = render_as_module(func) # source code as string
>>> namespace = {}
>>> exec_(py_mod, namespace, namespace)
>>> res = eval('newton(0.5)', namespace)
>>> abs(res - 0.865474033102) < 1e-12
True

442 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.8.13 Python utilities (sympy.codegen.pyutils)

sympy.codegen.pyutils.render_as_module(content)
Renders python code as a module (with the required imports)

5.8.14 C utilities (sympy.codegen.cutils)

sympy.codegen.cutils.render_as_source_file(content, Printer=<class
’sympy.printing.ccode.C99CodePrinter’>,
settings=None)
Renders a C source file (with required #include statements)

5.8.15 Fortran utilities (sympy.codegen.futils)

sympy.codegen.futils.render_as_module(definitions, name, declarations=(),

printer_settings=None)
Creates a Module instance and renders it as a string.
This generates Fortran source code for a module with the correct use statements.
Parameters definitions : iterable
Passed to sympy.codegen.fnodes.Module (page 436).
name : str
Passed to sympy.codegen.fnodes.Module (page 436).
declarations : iterable
Passed to sympy.codegen.fnodes.Module (page 436). It will be ex-
tended with use statements, ‘implicit none’ and public list generated
from definitions.
printer_settings : dict
Passed to FCodePrinter (default: {'standard': 2003,
'source_format': 'free'}).

5.9 Numeric Computation

Symbolic computer algebra systems like SymPy facilitate the construction and manipulation
of mathematical expressions. Unfortunately when it comes time to evaluate these expressions
on numerical data, symbolic systems often have poor performance.
Fortunately SymPy offers a number of easy-to-use hooks into other numeric systems, allowing
you to create mathematical expressions in SymPy and then ship them off to the numeric
system of your choice. This page documents many of the options available including the math
library, the popular array computing package numpy, code generation in Fortran or C, and
the use of the array compiler Theano.

5.9. Numeric Computation 443

SymPy Documentation, Release 1.3

5.9.1 Subs/evalf

Subs is the slowest but simplest option. It runs at SymPy speeds. The .subs(...).evalf()
method can substitute a numeric value for a symbolic one and then evaluate the result within
SymPy.

>>> from sympy import *

>>> from sympy.abc import x
>>> expr = sin(x)/x
>>> expr.evalf(subs={x: 3.14})
0.000507214304613640

This method is slow. You should use this method production only if performance is not an
issue. You can expect .subs to take tens of microseconds. It can be useful while prototyping
or if you just want to see a value once.

5.9.2 Lambdify

The lambdify function translates SymPy expressions into Python functions, leveraging a va-
riety of numerical libraries. It is used as follows:

>>> from sympy import *

>>> from sympy.abc import x
>>> expr = sin(x)/x
>>> f = lambdify(x, expr)
>>> f(3.14)
0.000507214304614

Here lambdify makes a function that computes f(x) = sin(x)/x. By default lambdify relies
on implementations in the math standard library. This numerical evaluation takes on the order
of hundreds of nanoseconds, roughly two orders of magnitude faster than the .subs method.
This is the speed difference between SymPy and raw Python.
Lambdify can leverage a variety of numerical backends. By default it uses the math library.
However it also supports mpmath and most notably, numpy. Using the numpy library gives the
generated function access to powerful vectorized ufuncs that are backed by compiled C code.

>>> from sympy import *

>>> from sympy.abc import x
>>> expr = sin(x)/x
>>> f = lambdify(x, expr, ”numpy”)

>>> import numpy

>>> data = numpy.linspace(1, 10, 10000)
>>> f(data)
[ 0.84147098 0.84119981 0.84092844 ... -0.05426074 -0.05433146
-0.05440211]

If you have array-based data this can confer a considerable speedup, on the order of 10 nano-
seconds per element. Unfortunately numpy incurs some start-up time and introduces an
overhead of a few microseconds.

444 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.9.3 uFuncify

The autowrap module contains methods that help in efficient computation.

• autowrap (page 406) method for compiling code generated by the codegen (page 400)
module, and wrap the binary for use in python.
• binary_function (page 407) method automates the steps needed to autowrap the SymPy
expression and attaching it to a Function object with implemented_function().
• ufuncify (page 407) generates a binary function that supports broadcasting on numpy
arrays using different backends that are faster as compared to subs/evalf and lambd-
ify.
The API reference of all the above is listed here: sympy.utilities.autowrap() (page 1431).

5.9.4 Theano

SymPy has a strong connection with Theano, a mathematical array compiler. SymPy expres-
sions can be easily translated to Theano graphs and then compiled using the Theano compiler
chain.

>>> from sympy import *

>>> from sympy.abc import x
>>> expr = sin(x)/x

>>> from sympy.printing.theanocode import theano_function

>>> f = theano_function([x], [expr])

If array broadcasting or types are desired then Theano requires this extra information

>>> f = theano_function([x], [expr], dims={x: 1}, dtypes={x: 'float64'})

Theano has a more sophisticated code generation system than SymPy’s C/Fortran code print-
ers. Among other things it handles common sub-expressions and compilation onto the GPU.
Theano also supports SymPy Matrix and Matrix Expression objects.

5.9.5 So Which Should I Use?

The options here were listed in order from slowest and least dependencies to fastest and
most dependencies. For example, if you have Theano installed then that will often be the best
choice. If you don’t have Theano but do have f2py then you should use ufuncify.

Tool Speed Qualities Dependencies

subs/evalf 50us Simple None
lambdify 1us Scalar functions math
lambdify-numpy 10ns Vector functions numpy
ufuncify 10ns Complex vector expressions f2py, Cython
Theano 10ns Many outputs, CSE, GPUs Theano

5.9. Numeric Computation 445

SymPy Documentation, Release 1.3

5.10 Functions Module

All functions support the methods documented below, inherited from sympy.core.function.
Function (page 189).
class sympy.core.function.Function
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
...
(continues on next page)

446 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

... 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 im-
plemented. 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.
if my_func can take one or two arguments then,

>>> class my_func(Function):

... nargs = (1, 2)
...
>>>

as_base_exp()
Returns the method as the 2-tuple (base, exponent).
fdiff(argindex=1)
Returns the first derivative of the function.
is_commutative
Returns whether the function is commutative.

5.10.1 Contents

Elementary

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

sympy.functions.elementary.complexes

re

class sympy.functions.elementary.complexes.re
Returns real part of expression. This function performs only elementary analysis and so
it will fail to decompose properly more complicated expressions. If completely simplified
result is needed then use Basic.as_real_imag() or perform complex expansion on instance
of this function.
See also:
im (page 448)

5.10. Functions Module 447

SymPy Documentation, Release 1.3

Examples

>>> from sympy import re, im, I, E

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

as_real_imag(deep=True, **hints)
Returns the real number with a zero imaginary part.

im

class sympy.functions.elementary.complexes.im
Returns imaginary part of expression. This function performs only elementary analysis
and so it will fail to decompose properly more complicated expressions. If completely
simplified result is needed then use Basic.as_real_imag() or perform complex expansion
on instance of this function.
See also:
re (page 447)

Examples

>>> from sympy import re, im, E, I

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

as_real_imag(deep=True, **hints)
Return the imaginary part with a zero real part.

Examples

>>> from sympy.functions import im

>>> from sympy import I
>>> im(2 + 3*I).as_real_imag()
(3, 0)

448 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sign

class sympy.functions.elementary.complexes.sign
Returns the complex sign of an expression:
If the expression is real the sign will be:
• 1 if expression is positive
• 0 if expression is equal to zero
• -1 if expression is negative
If the expression is imaginary the sign will be:
• I if im(expression) is positive
• -I if im(expression) is negative
Otherwise an unevaluated expression will be returned. When evaluated, the result (in
general) will be cos(arg(expr)) + I*sin(arg(expr)).
See also:
Abs (page 449), conjugate (page 451)

Examples

>>> from sympy.functions import sign

>>> from sympy.core.numbers import I

>>> sign(-1)
-1
>>> sign(0)
0
>>> sign(-3*I)
-I
>>> sign(1 + I)
sign(1 + I)
>>> _.evalf()
0.707106781186548 + 0.707106781186548*I

Abs

class sympy.functions.elementary.complexes.Abs
Return the absolute value of the argument.
This is an extension of the built-in function abs() to accept symbolic values. If you pass
a SymPy expression to the built-in abs(), it will pass it automatically to Abs().
See also:
sign (page 449), conjugate (page 451)

5.10. Functions Module 449

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Abs, Symbol, S

>>> Abs(-1)
1
>>> x = Symbol('x', real=True)
>>> Abs(-x)
Abs(x)
>>> Abs(x**2)
x**2
>>> abs(-x) # The Python built-in
Abs(x)

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

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

Abs will always return a sympy object.

fdiff(argindex=1)
Get the first derivative of the argument to Abs().

Examples

>>> from sympy.abc import x

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

arg

class sympy.functions.elementary.complexes.arg
Returns the argument (in radians) of a complex number. For a positive number, the
argument is always 0.

Examples

>>> from sympy.functions import arg

>>> from sympy import I, sqrt
>>> arg(2.0)
0
>>> arg(I)
pi/2
>>> arg(sqrt(2) + I*sqrt(2))
pi/4

450 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

conjugate

class sympy.functions.elementary.complexes.conjugate
Returns the complexconjugate Ref[1] of an argument. In mathematics, the complex conju-
gate of a complex number is given by changing the sign of the imaginary part.
Thus, the conjugate of the complex number a + ib (where a and b are real numbers) is
a − ib
See also:
sign (page 449), Abs (page 449)

References

[R153]

Examples

>>> from sympy import conjugate, I

>>> conjugate(2)
2
>>> conjugate(I)
-I

polar_lift

class sympy.functions.elementary.complexes.polar_lift
Lift argument to the Riemann surface of the logarithm, using the standard branch.

>>> from sympy import Symbol, polar_lift, I

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

>>> polar_lift(4*x)
4*polar_lift(x)
>>> polar_lift(4*p)
4*p

See also:
sympy.functions.elementary.exponential.exp_polar, periodic_argument
(page 452)

5.10. Functions Module 451

SymPy Documentation, Release 1.3

periodic_argument

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

>>> from sympy import exp, exp_polar, periodic_argument, unbranched_argument

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

See also:
sympy.functions.elementary.exponential.exp_polar
polar_lift (page 451) Lift argument to the Riemann surface of the logarithm
principal_branch (page 452)

principal_branch

class sympy.functions.elementary.complexes.principal_branch
Represent a polar number reduced to its principal branch on a quotient of the Riemann
surface of the logarithm.
This is a function of two arguments. The first argument is a polar number z, and the
second one a positive real number of infinity, p. The result is “z mod exp_polar(I*p)”.

>>> from sympy import exp_polar, principal_branch, oo, I, pi

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

See also:
sympy.functions.elementary.exponential.exp_polar
polar_lift (page 451) Lift argument to the Riemann surface of the logarithm
periodic_argument (page 452)

sympy.functions.elementary.trigonometric

Trigonometric Functions

452 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sin

class sympy.functions.elementary.trigonometric.sin
The sine function.
Returns the sine of x (measured in radians).
See also:
csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot (page 455), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

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

References

[R154], [R155], [R156], [R157]

Examples

>>> from sympy import sin, pi

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

Members

cos

class sympy.functions.elementary.trigonometric.cos
The cosine function.
Returns the cosine of x (measured in radians).
See also:
sin (page 453), csc (page 456), sec (page 456), tan (page 454), cot (page 455), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

5.10. Functions Module 453

SymPy Documentation, Release 1.3

Notes

See sin() (page 453) for notes about automatic evaluation.

References

[R158], [R159], [R160]

Examples

>>> from sympy import cos, pi

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

Members

tan

class sympy.functions.elementary.trigonometric.tan
The tangent function.
Returns the tangent of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), cot (page 455), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

See sin() (page 453) for notes about automatic evaluation.

References

[R161], [R162], [R163]

454 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import tan, pi

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

Members

cot

class sympy.functions.elementary.trigonometric.cot
The cotangent function.
Returns the cotangent of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

See sin() (page 453) for notes about automatic evaluation.

References

[R164], [R165], [R166]

Examples

>>> from sympy import cot, pi

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

Members

5.10. Functions Module 455

SymPy Documentation, Release 1.3

sec

class sympy.functions.elementary.trigonometric.sec
The secant function.
Returns the secant of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), tan (page 454), cot (page 455), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

See sin() (page 453) for notes about automatic evaluation.

References

[R167], [R168], [R169]

Examples

>>> from sympy import sec

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

Members

csc

class sympy.functions.elementary.trigonometric.csc
The cosecant function.
Returns the cosecant of x (measured in radians).
See also:
sin (page 453), cos (page 453), sec (page 456), tan (page 454), cot (page 455), asin
(page 458), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

See sin() (page 453) for notes about automatic evaluation.

456 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R170], [R171], [R172]

Examples

>>> from sympy import csc

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

Members

sinc

class sympy.functions.elementary.trigonometric.sinc
Represents unnormalized sinc function

References

[R173]

Examples

>>> from sympy import sinc, oo, jn, Product, Symbol

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

• Automated Evaluation

>>> sinc(0)
1
>>> sinc(oo)
0

• Differentiation

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

• Series Expansion

>>> sinc(x).series()
1 - x**2/6 + x**4/120 + O(x**6)

5.10. Functions Module 457

SymPy Documentation, Release 1.3

• As zero’th order spherical Bessel Function

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

Members

Trigonometric Inverses

asin

class sympy.functions.elementary.trigonometric.asin
The inverse sine function.
Returns the arcsine of x in radians.
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), acsc (page 461), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

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

References

[R174], [R175], [R176]

Examples

>>> from sympy import asin, oo, pi

>>> asin(1)
pi/2
>>> asin(-1)
-pi/2

Members

acos

class sympy.functions.elementary.trigonometric.acos
The inverse cosine function.
Returns the arc cosine of x (measured in radians).
See also:

458 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acsc (page 461), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

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

acos(zoo) evaluates to zoo (see note in :py:class‘sympy.functions.elementary.trigonometric.asec‘)

References

[R177], [R178], [R179]

Examples

>>> from sympy import acos, oo, pi

>>> acos(1)
0
>>> acos(0)
pi/2
>>> acos(oo)
oo*I

Members

atan

class sympy.functions.elementary.trigonometric.atan
The inverse tangent function.
Returns the arc tangent of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acsc (page 461), acos (page 458), asec (page 460), acot
(page 460), atan2 (page 462)

Notes

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

References

[R180], [R181], [R182]

5.10. Functions Module 459

SymPy Documentation, Release 1.3

Examples

>>> from sympy import atan, oo, pi

>>> atan(0)
0
>>> atan(1)
pi/4
>>> atan(oo)
pi/2

Members

acot

class sympy.functions.elementary.trigonometric.acot
The inverse cotangent function.
Returns the arc cotangent of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acsc (page 461), acos (page 458), asec (page 460), atan
(page 459), atan2 (page 462)

References

[R183], [R184], [R185]

Members

asec

class sympy.functions.elementary.trigonometric.asec
The inverse secant function.
Returns the arc secant of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acsc (page 461), acos (page 458), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

asec(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1.

asec(x) has branch cut in the interval [-1, 1]. For complex arguments, it can be defined
[R189] as
√
sec−1 (z) = −i ∗ (log( 1 − z 2 + 1)/z)

460 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

At x = 0, for positive branch cut, the limit evaluates to zoo. For negative branch cut,
the limit
√
lim −i ∗ (log(− 1 − z 2 + 1)/z)
z→0

simplifies to −i ∗ log(z/2 + O(z 3 )) which ultimately evaluates to zoo.

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

References

[R186], [R187], [R188], [R189]

Examples

>>> from sympy import asec, oo, pi

>>> asec(1)
0
>>> asec(-1)
pi

Members

acsc

class sympy.functions.elementary.trigonometric.acsc
The inverse cosecant function.
Returns the arc cosecant of x (measured in radians).
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acos (page 458), asec (page 460), atan (page 459), acot
(page 460), atan2 (page 462)

Notes

acsc(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1.

References

[R190], [R191], [R192]

Examples

5.10. Functions Module 461

SymPy Documentation, Release 1.3

>>> from sympy import acsc, oo, pi

>>> acsc(1)
pi/2
>>> acsc(-1)
-pi/2

Members

atan2

class sympy.functions.elementary.trigonometric.atan2
The function atan2(y, x) computes atan(y/x) taking two arguments y and x. Signs of
both y and x are considered to determine the appropriate quadrant of atan(y/x). The
range is (−π, π]. The complete definition reads as follows:
 ( )

 arctan xy x>0

 (y)

 arctan + π y ≥ 0, x < 0

arctan ( y ) − π
 x

x y < 0, x < 0
atan2(y, x) =


π
+ 2

y > 0, x = 0

 − π
 2

y < 0, x = 0

undefined y = 0, x = 0

Attention: Note the role reversal of both arguments. The y-coordinate is the first argu-
ment and the x-coordinate the second.
See also:
sin (page 453), csc (page 456), cos (page 453), sec (page 456), tan (page 454), cot
(page 455), asin (page 458), acsc (page 461), acos (page 458), asec (page 460), atan
(page 459), acot (page 460)

References

[R193], [R194], [R195]

Examples

Going counter-clock wise around the origin we find the following angles:
>>> from sympy import atan2
>>> atan2(0, 1)
0
>>> atan2(1, 1)
pi/4
>>> atan2(1, 0)
pi/2
>>> atan2(1, -1)
3*pi/4
>>> atan2(0, -1)
pi
>>> atan2(-1, -1)
(continues on next page)

462 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

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

which are all correct. Compare this to the results of the ordinary atan function for the
point (x, y) = (−1, 1)

>>> from sympy import atan, S

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

where only the atan2 function reurns what we expect. We can differentiate the function
with respect to both arguments:

>>> from sympy import diff

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

>>> diff(atan2(y, x), y)

x/(x**2 + y**2)

We can express the atan2 function in terms of complex logarithms:

>>> from sympy import log

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

and in terms of ( atan):

>>> from sympy import atan

>>> atan2(y, x).rewrite(atan)
2*atan(y/(x + sqrt(x**2 + y**2)))

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

sympy.functions.elementary.hyperbolic

Hyperbolic Functions

HyperbolicFunction

class sympy.functions.elementary.hyperbolic.HyperbolicFunction
Base class for hyperbolic functions.
See also:
sinh (page 464), cosh (page 464), tanh (page 464), coth (page 464)

5.10. Functions Module 463

SymPy Documentation, Release 1.3

Members

sinh

class sympy.functions.elementary.hyperbolic.sinh
−x
The hyperbolic sine function, e −e
x

2 .
• sinh(x) -> Returns the hyperbolic sine of x
See also:
cosh (page 464), tanh (page 464), asinh (page 465)

Members

cosh

class sympy.functions.elementary.hyperbolic.cosh
x −x
The hyperbolic cosine function, e +e
2 .
• cosh(x) -> Returns the hyperbolic cosine of x
See also:
sinh (page 464), tanh (page 464), acosh (page 465)

Members

tanh

class sympy.functions.elementary.hyperbolic.tanh
sinh(x)
The hyperbolic tangent function, cosh(x) .
• tanh(x) -> Returns the hyperbolic tangent of x
See also:
sinh (page 464), cosh (page 464), atanh (page 466)

Members

coth

class sympy.functions.elementary.hyperbolic.coth
The hyperbolic cotangent function, cosh(x)
sinh(x) .

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

Members

464 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sech

class sympy.functions.elementary.hyperbolic.sech
2
The hyperbolic secant function, ex +e −x

• sech(x) -> Returns the hyperbolic secant of x

See also:
sinh (page 464), cosh (page 464), tanh (page 464), coth (page 464), csch (page 465),
asinh (page 465), acosh (page 465)

Members

csch

class sympy.functions.elementary.hyperbolic.csch
2
The hyperbolic cosecant function, ex −e −x

• csch(x) -> Returns the hyperbolic cosecant of x

See also:
sinh (page 464), cosh (page 464), tanh (page 464), sech (page 465), asinh (page 465),
acosh (page 465)

Members

Hyperbolic Inverses

asinh

class sympy.functions.elementary.hyperbolic.asinh
The inverse hyperbolic sine function.
• asinh(x) -> Returns the inverse hyperbolic sine of x
See also:
acosh (page 465), atanh (page 466), sinh (page 464)

Members

acosh

class sympy.functions.elementary.hyperbolic.acosh
The inverse hyperbolic cosine function.
• acosh(x) -> Returns the inverse hyperbolic cosine of x
See also:
asinh (page 465), atanh (page 466), cosh (page 464)

Members

5.10. Functions Module 465

SymPy Documentation, Release 1.3

atanh

class sympy.functions.elementary.hyperbolic.atanh
The inverse hyperbolic tangent function.
• atanh(x) -> Returns the inverse hyperbolic tangent of x
See also:
asinh (page 465), acosh (page 465), tanh (page 464)

Members

acoth

class sympy.functions.elementary.hyperbolic.acoth
The inverse hyperbolic cotangent function.
• acoth(x) -> Returns the inverse hyperbolic cotangent of x

Members

asech

class sympy.functions.elementary.hyperbolic.asech
The inverse hyperbolic secant function.
• asech(x) -> Returns the inverse hyperbolic secant of x
See also:
asinh (page 465), atanh (page 466), cosh (page 464), acoth (page 466)

References

[R196], [R197], [R198]

Examples

>>> from sympy import asech, sqrt, S

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

466 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Members

acsch

class sympy.functions.elementary.hyperbolic.acsch
The inverse hyperbolic cosecant function.
• acsch(x) -> Returns the inverse hyperbolic cosecant of x

References

[R199], [R200], [R201]

Examples

>>> from sympy import acsch, sqrt, S

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

Members

sympy.functions.elementary.integers

ceiling

class sympy.functions.elementary.integers.ceiling
Ceiling is a univariate function which returns the smallest integer value not less than its
argument. This implementation generalizes ceiling to complex numbers by taking the
ceiling of the real and imaginary parts separately.
See also:
sympy.functions.elementary.integers.floor (page 468)

References

[R202], [R203]

5.10. Functions Module 467

SymPy Documentation, Release 1.3

Examples

>>> from sympy import ceiling, E, I, S, Float, Rational

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

Members

floor

class sympy.functions.elementary.integers.floor
Floor is a univariate function which returns the largest integer value not greater than
its argument. This implementation generalizes floor to complex numbers by taking the
floor of the real and imaginary parts separately.
See also:
sympy.functions.elementary.integers.ceiling (page 467)

References

[R204], [R205]

Examples

>>> from sympy import floor, E, I, S, Float, Rational

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

Members

468 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

RoundFunction

class sympy.functions.elementary.integers.RoundFunction
The base class for rounding functions.

frac

class sympy.functions.elementary.integers.frac
Represents the fractional part of x
For real numbers it is defined [R206] as

x − ⌊x⌋

See also:
sympy.functions.elementary.integers.floor (page 468), sympy.functions.
elementary.integers.ceiling (page 467)

References

[R206], [R207]

Examples

>>> from sympy import Symbol, frac, Rational, floor, ceiling, I

>>> frac(Rational(4, 3))
1/3
>>> frac(-Rational(4, 3))
2/3

returns zero for integer arguments

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

>>> frac(n)
0

rewrite as floor

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

for complex arguments

>>> r = Symbol('r', real=True)

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

5.10. Functions Module 469

SymPy Documentation, Release 1.3

sympy.functions.elementary.exponential

exp

class sympy.functions.elementary.exponential.exp
The exponential function, ex .
See also:
log (page 470)

Members

LambertW

class sympy.functions.elementary.exponential.LambertW
The Lambert W function W (z) is defined as the inverse function of w exp(w) [R208].
In other words, the value of W (z) is such that z = W (z) exp(W (z)) for any complex number
z. The Lambert W function is a multivalued function with infinitely many branches Wk (z),
indexed by k ∈ Z. Each branch gives a different solution w of the equation z = w exp(w).
The Lambert W function has two partially real branches: the principal branch (k = 0) is
real for real z > −1/e, and the k = −1 branch is real for −1/e < z < 0. All branches except
k = 0 have a logarithmic singularity at z = 0.

References

[R208]

Examples

>>> from sympy import LambertW

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

Members

log

class sympy.functions.elementary.exponential.log
The natural logarithm function ln(x) or log(x). Logarithms are taken with the natural
base, e. To get a logarithm of a different base b, use log(x, b), which is essentially
short-hand for log(x)/log(b).
See also:
exp (page 470)

470 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Members

sympy.functions.elementary.piecewise

ExprCondPair

class sympy.functions.elementary.piecewise.ExprCondPair
Represents an expression, condition pair.
Members

Piecewise

class sympy.functions.elementary.piecewise.Piecewise
Represents a piecewise function.
Usage:
Piecewise( (expr,cond), (expr,cond), … )
• Each argument is a 2-tuple defining an expression and condition
• The conds are evaluated in turn returning the first that is True. If any of
the evaluated conds are not determined explicitly False, e.g. x < 1, the
function is returned in symbolic form.
• If the function is evaluated at a place where all conditions are False, nan
will be returned.
• Pairs where the cond is explicitly False, will be removed.
See also:
piecewise_fold (page 472), ITE

Examples

>>> from sympy import Piecewise, log, ITE, piecewise_fold

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

Booleans can contain Piecewise elements:

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

The folded version of this results in a Piecewise whose expressions are Booleans:
>>> folded_cond = piecewise_fold(cond); folded_cond
Piecewise((2 < y, x < 0), (3 < y, True))

5.10. Functions Module 471

SymPy Documentation, Release 1.3

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

>>> Piecewise((1, folded_cond))

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

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

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

Members

sympy.functions.elementary.piecewise.piecewise_fold(expr)
Takes an expression containing a piecewise function and returns the expression in piece-
wise form. In addition, any ITE conditions are rewritten in negation normal form and
simplified.
See also:
Piecewise (page 471)

Examples

>>> from sympy import Piecewise, piecewise_fold, sympify as S

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

sympy.functions.elementary.miscellaneous

IdentityFunction

class sympy.functions.elementary.miscellaneous.IdentityFunction
The identity function

Examples

>>> from sympy import Id, Symbol

>>> x = Symbol('x')
>>> Id(x)
x

Members

472 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Min

class sympy.functions.elementary.miscellaneous.Min
Return, if possible, the minimum value of the list. It is named Min and not min to avoid
conflicts with the built-in function min.
See also:

Max (page 473) find maximum values

Examples

>>> from sympy import Min, Symbol, oo

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

>>> Min(x, -2) #doctest: +SKIP

Min(x, -2)
>>> Min(x, -2).subs(x, 3)
-2
>>> Min(p, -3)
-3
>>> Min(x, y) #doctest: +SKIP
Min(x, y)
>>> Min(n, 8, p, -7, p, oo) #doctest: +SKIP
Min(n, -7)

Members

Max

class sympy.functions.elementary.miscellaneous.Max
Return, if possible, the maximum value of the list.
When number of arguments is equal one, then return this argument.
When number of arguments is equal two, then return, if possible, the value from (a, b)
that is >= the other.
In common case, when the length of list greater than 2, the task is more complicated.
Return only the arguments, which are greater than others, if it is possible to determine
directional relation.
If is not possible to determine such a relation, return a partially evaluated result.
Assumptions are used to make the decision too.
Also, only comparable arguments are permitted.
It is named Max and not max to avoid conflicts with the built-in function max.
See also:

Min (page 473) find minimum values

5.10. Functions Module 473

SymPy Documentation, Release 1.3

References

[R209], [R210]

Examples

>>> from sympy import Max, Symbol, oo

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

>>> Max(x, -2) #doctest: +SKIP

Max(x, -2)
>>> Max(x, -2).subs(x, 3)
3
>>> Max(p, -2)
p
>>> Max(x, y)
Max(x, y)
>>> Max(x, y) == Max(y, x)
True
>>> Max(x, Max(y, z)) #doctest: +SKIP
Max(x, y, z)
>>> Max(n, 8, p, 7, -oo) #doctest: +SKIP
Max(8, p)
>>> Max (1, x, oo)
oo

• Algorithm

The task can be considered as searching of supremums in the directed complete partial
orders [R209].
The source values are sequentially allocated by the isolated subsets in which supremums
are searched and result as Max arguments.
If the resulted supremum is single, then it is returned.
The isolated subsets are the sets of values which are only the comparable with each
other in the current set. E.g. natural numbers are comparable with each other, but not
comparable with the x symbol. Another example: the symbol x with negative assumption
is comparable with a natural number.
Also there are “least” elements, which are comparable with all others, and have a zero
property (maximum or minimum for all elements). E.g. oo. In case of it the allocation
operation is terminated and only this value is returned.
Assumption:
• if A > B > C then A > C
• if A == B then B can be removed

Members

474 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

root

sympy.functions.elementary.miscellaneous.root(x, n, k) → Returns the k-th n-th

root of x, defaulting to the
principal root (k=0).
The parameter evaluate determines if the expression should be evaluated. If None, its
value is taken from global_evaluate.
See also:
sympy.polys.rootoftools.rootof (page 895), sympy.core.power.integer_nthroot
(page 160), sqrt (page 476), real_root (page 478)

References

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

Examples

>>> from sympy import root, Rational

>>> from sympy.abc import x, n

>>> root(x, 2)
sqrt(x)

>>> root(x, 3)
x**(1/3)

>>> root(x, n)
x**(1/n)

>>> root(x, -Rational(2, 3))

x**(-3/2)

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

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

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

>>> [rootof(x**2 - 1, i) for i in range(2)]

[-1, 1]

5.10. Functions Module 475

SymPy Documentation, Release 1.3

>>> [rootof(x**3 - 1,i) for i in range(3)]

[1, -1/2 - sqrt(3)*I/2, -1/2 + sqrt(3)*I/2]

>>> [rootof(x**4 - 1,i) for i in range(4)]

[-1, 1, -I, I]

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

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

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

>>> from sympy import real_root

>>> real_root(_)
-2
>>> real_root(-32, 5)
-2

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

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

-2

sqrt

sympy.functions.elementary.miscellaneous.sqrt(arg, evaluate=None)
The square root function
sqrt(x) -> Returns the principal square root of x.
The parameter evaluate determines if the expression should be evaluated. If None, its
value is taken from global_evaluate
See also:
sympy.polys.rootoftools.rootof (page 895), root (page 475), real_root (page 478)

References

[R211], [R212]

Examples

>>> from sympy import sqrt, Symbol

>>> x = Symbol('x')

>>> sqrt(x)
sqrt(x)

476 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> sqrt(x)**2
x

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

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

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

>>> from sympy import Eq

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

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

>>> y = Symbol('y', positive=True)

>>> sqrt(y**2)
y

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

>>> from sympy import powdenest

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

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

>>> from sympy import rootof

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

[-sqrt(3), sqrt(3)]

cbrt

sympy.functions.elementary.miscellaneous.cbrt(arg, evaluate=None)
This function computes the principal cube root of arg, so it’s just a shortcut for arg ∗
∗Rational(1, 3).
The parameter evaluate determines if the expression should be evaluated. If None, its
value is taken from global_evaluate.
See also:
sympy.polys.rootoftools.rootof (page 895), root (page 475), real_root (page 478)

References

• http://en.wikipedia.org/wiki/Cube_root

5.10. Functions Module 477

SymPy Documentation, Release 1.3

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

Examples

>>> from sympy import cbrt, Symbol

>>> x = Symbol('x')

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

>>> cbrt(x)**3
x

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

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

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

>>> from sympy import Eq

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

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

>>> y = Symbol('y', positive=True)

>>> cbrt(y**3)
y

real_root

sympy.functions.elementary.miscellaneous.real_root(arg, n=None, evalu-

ate=None)
Return the real nth-root of arg if possible. If n is omitted then all instances of (-n)**(1/odd)
will be changed to -n**(1/odd); this will only create a real root of a principal root – the
presence of other factors may cause the result to not be real.
The parameter evaluate determines if the expression should be evaluated. If None, its
value is taken from global_evaluate.
See also:
sympy.polys.rootoftools.rootof (page 895), sympy.core.power.integer_nthroot
(page 160), root (page 475), sqrt (page 476)

Examples

>>> from sympy import root, real_root, Rational

>>> from sympy.abc import x, n

478 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

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

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

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

Combinatorial

This module implements various combinatorial functions.

bell

class sympy.functions.combinatorial.numbers.bell
Bell numbers / Bell polynomials
The Bell numbers satisfy B0 = 1 and

∑(
n−1
n−1
)
Bn = Bk .
k
k=0

They are also given by:

∞
1 ∑ kn
Bn = .
e k!
k=0

The Bell polynomials are given by B0 (x) = 1 and

∑(
n−1
n−1
)
Bn (x) = x Bk−1 (x).
k−1
k=1

The second kind of Bell polynomials (are sometimes called “partial” Bell polynomials or
incomplete Bell polynomials) are defined as

∑ ( x )j 1 ( x )j 2 ( )jn−k+1
n! 1 2 xn−k+1
Bn,k (x1 , x2 , . . . xn−k+1 ) = ··· .
j1 +j2 +j2 +···=k
j1 !j2 ! · · · jn−k+1 ! 1! 2! (n − k + 1)!
j1 +2j2 +3j2 +···=n

• bell(n) gives the nth Bell number, Bn .

• bell(n, x) gives the nth Bell polynomial, Bn (x).
• bell(n, k, (x1, x2, ...)) gives Bell polynomials of the second kind,
Bn,k (x1 , x2 , . . . , xn−k+1 ).

5.10. Functions Module 479

SymPy Documentation, Release 1.3

See also:
bernoulli (page 480), catalan (page 483), euler (page 484), fibonacci (page 488),
harmonic (page 490), lucas (page 492), genocchi (page 493), partition (page 493),
tribonacci (page 489)

Notes

Not to be confused with Bernoulli numbers and Bernoulli polynomials, which use the
same notation.

References

[R115], [R116], [R117]

Examples

>>> from sympy import bell, Symbol, symbols

>>> [bell(n) for n in range(11)]

[1, 1, 2, 5, 15, 52, 203, 877, 4140, 21147, 115975]
>>> bell(30)
846749014511809332450147
>>> bell(4, Symbol('t'))
t**4 + 6*t**3 + 7*t**2 + t
>>> bell(6, 2, symbols('x:6')[1:])
6*x1*x5 + 15*x2*x4 + 10*x3**2

bernoulli

class sympy.functions.combinatorial.numbers.bernoulli
Bernoulli numbers / Bernoulli polynomials
The Bernoulli numbers are a sequence of rational numbers defined by B0 = 1 and the
recursive relation (n > 0):
n (
∑ )
n+1
0= Bk
k
k=0
x
They are also commonly defined by their exponential generating function, which is ex −1 .
For odd indices > 1, the Bernoulli numbers are zero.
The Bernoulli polynomials satisfy the analogous formula:
n ( )
∑ n
Bn (x) = Bk xn−k
k
k=0

Bernoulli numbers and Bernoulli polynomials are related as Bn (0) = Bn .

We compute Bernoulli numbers using Ramanujan’s formula:
A(n) − S(n)
Bn = (n+3 )
n

480 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

where:
{
n+3
3 n ≡ 0 or 2 (mod 6)
A(n) =
− n+3
6 n ≡ 4 (mod 6)

and:
[n/6] ( )
∑ n+3
S(n) = Bn−6k
n − 6k
k=1

This formula is similar to the sum given in the definition, but cuts 2/3 of the terms. For
Bernoulli polynomials, we use the formula in the definition.
• bernoulli(n) gives the nth Bernoulli number, Bn
• bernoulli(n, x) gives the nth Bernoulli polynomial in x, Bn (x)
See also:
bell (page 479), catalan (page 483), euler (page 484), fibonacci (page 488), harmonic
(page 490), lucas (page 492), genocchi (page 493), partition (page 493), tribonacci
(page 489)

References

[R118], [R119], [R120], [R121]

Examples

>>> from sympy import bernoulli

>>> [bernoulli(n) for n in range(11)]

[1, -1/2, 1/6, 0, -1/30, 0, 1/42, 0, -1/30, 0, 5/66]
>>> bernoulli(1000001)
0

binomial

class sympy.functions.combinatorial.factorials.binomial
Implementation of the binomial coefficient. It can be defined in two ways depending on
its desired interpretation:
( ) ( )
n n! n f f (n, k)
= or =
k k!(n − k)! k k!

First, in a strict combinatorial sense it defines the number of ways we can choose k
elements from a set of n elements. In this case both arguments are nonnegative integers
and binomial is computed using an efficient algorithm based on prime factorization.
The other definition is generalization for arbitrary n, however k must also be nonnegative.
This case is very useful when evaluating summations.
For the sake of convenience for negative integer k this function will return zero no matter
what valued is the other argument.

5.10. Functions Module 481

SymPy Documentation, Release 1.3

To expand the binomial when n is a symbol, use either expand_func() or ex-

pand(func=True). The former will keep the polynomial in factored form while the latter
will expand the polynomial itself. See examples for details.

References

[R122]

Examples

>>> from sympy import Symbol, Rational, binomial, expand_func

>>> n = Symbol('n', integer=True, positive=True)

>>> binomial(15, 8)
6435

>>> binomial(n, -1)

0

Rows of Pascal’s triangle can be generated with the binomial function:

>>> for N in range(8):

... print([binomial(N, i) for i in range(N + 1)])
...
[1]
[1, 1]
[1, 2, 1]
[1, 3, 3, 1]
[1, 4, 6, 4, 1]
[1, 5, 10, 10, 5, 1]
[1, 6, 15, 20, 15, 6, 1]
[1, 7, 21, 35, 35, 21, 7, 1]

As can a given diagonal, e.g. the 4th diagonal:

>>> N = -4
>>> [binomial(N, i) for i in range(1 - N)]
[1, -4, 10, -20, 35]

>>> binomial(Rational(5, 4), 3)

-5/128
>>> binomial(Rational(-5, 4), 3)
-195/128

>>> binomial(n, 3)
binomial(n, 3)

>>> binomial(n, 3).expand(func=True)

n**3/6 - n**2/2 + n/3

>>> expand_func(binomial(n, 3))

n*(n - 2)*(n - 1)/6

482 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

catalan

class sympy.functions.combinatorial.numbers.catalan
Catalan numbers
The nth catalan number is given by:
( )
1 2n
Cn =
n+1 n

• catalan(n) gives the nth Catalan number, Cn

See also:
bell (page 479), bernoulli (page 480), euler (page 484), fibonacci (page 488),
harmonic (page 490), lucas (page 492), genocchi (page 493), partition (page 493),
tribonacci (page 489), sympy.functions.combinatorial.factorials.binomial
(page 481)

References

[R123], [R124], [R125], [R126]

Examples

>>> from sympy import (Symbol, binomial, gamma, hyper, polygamma,

... catalan, diff, combsimp, Rational, I)

>>> [catalan(i) for i in range(1,10)]

[1, 2, 5, 14, 42, 132, 429, 1430, 4862]

>>> n = Symbol(”n”, integer=True)

>>> catalan(n)
catalan(n)

Catalan numbers can be transformed into several other, identical expressions involving
other mathematical functions

>>> catalan(n).rewrite(binomial)
binomial(2*n, n)/(n + 1)

>>> catalan(n).rewrite(gamma)
4**n*gamma(n + 1/2)/(sqrt(pi)*gamma(n + 2))

>>> catalan(n).rewrite(hyper)
hyper((-n + 1, -n), (2,), 1)

For some non-integer values of n we can get closed form expressions by rewriting in
terms of gamma functions:

>>> catalan(Rational(1,2)).rewrite(gamma)
8/(3*pi)

5.10. Functions Module 483

SymPy Documentation, Release 1.3

We can differentiate the Catalan numbers C(n) interpreted as a continuous real function
in n:

>>> diff(catalan(n), n)
(polygamma(0, n + 1/2) - polygamma(0, n + 2) + log(4))*catalan(n)

As a more advanced example consider the following ratio between consecutive numbers:

>>> combsimp((catalan(n + 1)/catalan(n)).rewrite(binomial))

2*(2*n + 1)/(n + 2)

The Catalan numbers can be generalized to complex numbers:

>>> catalan(I).rewrite(gamma)
4**I*gamma(1/2 + I)/(sqrt(pi)*gamma(2 + I))

and evaluated with arbitrary precision:

>>> catalan(I).evalf(20)
0.39764993382373624267 - 0.020884341620842555705*I

euler

class sympy.functions.combinatorial.numbers.euler
Euler numbers / Euler polynomials
The Euler numbers are given by:

∑∑
2n+1 k ( )
k (−1)j (k − 2j)2n+1
E2n = I
j 2k I k k
k=1 j=0

E2n+1 = 0
Euler numbers and Euler polynomials are related by
( )
1
En = 2 n En .
2

We compute symbolic Euler polynomials using [R131]

n ( )
∑ ( )n−k
n Ek 1
En (x) = x− .
k 2k 2
k=0

However, numerical evaluation of the Euler polynomial is computed more efficiently (and
more accurately) using the mpmath library.
• euler(n) gives the nth Euler number, En .
• euler(n, x) gives the nth Euler polynomial, En (x).
See also:
bell (page 479), bernoulli (page 480), catalan (page 483), fibonacci (page 488),
harmonic (page 490), lucas (page 492), genocchi (page 493), partition (page 493),
tribonacci (page 489)

484 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R127], [R128], [R129], [R130], [R131]

Examples

>>> from sympy import Symbol, S

>>> from sympy.functions import euler
>>> [euler(n) for n in range(10)]
[1, 0, -1, 0, 5, 0, -61, 0, 1385, 0]
>>> n = Symbol(”n”)
>>> euler(n + 2*n)
euler(3*n)

>>> x = Symbol(”x”)
>>> euler(n, x)
euler(n, x)

>>> euler(0, x)
1
>>> euler(1, x)
x - 1/2
>>> euler(2, x)
x**2 - x
>>> euler(3, x)
x**3 - 3*x**2/2 + 1/4
>>> euler(4, x)
x**4 - 2*x**3 + x

>>> euler(12, S.Half)

2702765/4096
>>> euler(12)
2702765

factorial

class sympy.functions.combinatorial.factorials.factorial
Implementation of factorial function over nonnegative integers. By convention (con-
sistent with the gamma function and the binomial coefficients), factorial of a negative
integer is complex infinity.
The factorial is very important in combinatorics where it gives the number of ways in
which n objects can be permuted. It also arises in calculus, probability, number theory,
etc.
There is strict relation of factorial with gamma function. In fact n! = gamma(n + 1) for
nonnegative integers. Rewrite of this kind is very useful in case of combinatorial simpli-
fication.
Computation of the factorial is done using two algorithms. For small arguments a pre-
computed look up table is used. However for bigger input algorithm Prime-Swing is used.
It is the fastest algorithm known and computes n! via prime factorization of special class
of numbers, called here the ‘Swing Numbers’.

5.10. Functions Module 485

SymPy Documentation, Release 1.3

See also:
factorial2 (page 487), RisingFactorial (page 494), FallingFactorial (page 488)

Examples

>>> from sympy import Symbol, factorial, S

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

>>> factorial(0)
1

>>> factorial(7)
5040

>>> factorial(-2)
zoo

>>> factorial(n)
factorial(n)

>>> factorial(2*n)
factorial(2*n)

>>> factorial(S(1)/2)
factorial(1/2)

subfactorial

class sympy.functions.combinatorial.factorials.subfactorial
The subfactorial counts the derangements of n items and is defined for non-negative
integers as:


1 n=0
!n = 0 n=1


(n − 1)(!(n − 1)+!(n − 2)) n > 1

It can also be written as int(round(n!/exp(1))) but the recursive definition with

caching is implemented for this function.
An interesting analytic expression is the following [R133]

!x = Γ(x + 1, −1)/e

which is valid for non-negative integers x. The above formula is not very useful incase
of non-integers. Γ(x + 1, −1) is single-valued only for integral arguments x, elsewhere on
the positive real axis it has an infinite number of branches none of which are real.
See also:
sympy.functions.combinatorial.factorials.factorial (page 485), sympy.
utilities.iterables.generate_derangements (page 1461), sympy.functions.
special.gamma_functions.uppergamma (page 510)

486 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R132], [R133]

Examples

>>> from sympy import subfactorial

>>> from sympy.abc import n
>>> subfactorial(n + 1)
subfactorial(n + 1)
>>> subfactorial(5)
44

factorial2 / double factorial

class sympy.functions.combinatorial.factorials.factorial2
The double factorial n!!, not to be confused with (n!)!
The double factorial is defined for nonnegative integers and for odd negative integers
as:


 1 n=0

n(n − 2)(n − 4) · · · 1 n positive odd
n!! =
n(n − 2)(n − 4) · · · 2
 n positive even


(n + 2)!!/(n + 2) n negative odd

See also:
factorial (page 485), RisingFactorial (page 494), FallingFactorial (page 488)

References

[R134]

Examples

>>> from sympy import factorial2, var

>>> var('n')
n
>>> factorial2(n + 1)
factorial2(n + 1)
>>> factorial2(5)
15
>>> factorial2(-1)
1
>>> factorial2(-5)
1/3

5.10. Functions Module 487

SymPy Documentation, Release 1.3

FallingFactorial

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

f f (x, k) = x · (x − 1) · · · (x − k + 1)

where x can be arbitrary expression and k is an integer. For more information check
“Concrete mathematics” by Graham, pp. 66 or visit http://mathworld.wolfram.com/
FallingFactorial.html page.
When x is a Poly instance of degree >= 1 with single variable, f f (x, k) = x(y) · x(y −
1) · · · x(y −k +1), where y is the variable of x. This is as described in Peter Paule, “Greatest
Factorial Factorization and Symbolic Summation”, Journal of Symbolic Computation, vol.
20, pp. 235-268, 1995.

>>> from sympy import ff, factorial, rf, gamma, polygamma, binomial, symbols, Poly
>>> from sympy.abc import x, k
>>> n, m = symbols('n m', integer=True)
>>> ff(x, 0)
1
>>> ff(5, 5)
120
>>> ff(x, 5) == x*(x-1)*(x-2)*(x-3)*(x-4)
True
>>> ff(Poly(x**2, x), 2)
Poly(x**4 - 2*x**3 + x**2, x, domain='ZZ')
>>> ff(n, n)
factorial(n)

Rewrite

>>> ff(x, k).rewrite(gamma)

(-1)**k*gamma(k - x)/gamma(-x)
>>> ff(x, k).rewrite(rf)
RisingFactorial(-k + x + 1, k)
>>> ff(x, m).rewrite(binomial)
binomial(x, m)*factorial(m)
>>> ff(n, m).rewrite(factorial)
factorial(n)/factorial(-m + n)

See also:
factorial (page 485), factorial2 (page 487), RisingFactorial (page 494)

References

[R135]

fibonacci

class sympy.functions.combinatorial.numbers.fibonacci
Fibonacci numbers / Fibonacci polynomials

488 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The Fibonacci numbers are the integer sequence defined by the initial terms F0 = 0,
F1 = 1 and the two-term recurrence relation Fn = Fn−1 + Fn−2 . This definition extended
to arbitrary real and complex arguments using the formula

ϕz − cos(πz)ϕ−z
Fz = √
5
The Fibonacci polynomials are defined by F1 (x) = 1, F2 (x) = x, and Fn (x) = x ∗ Fn−1 (x) +
Fn−2 (x) for n > 2. For all positive integers n, Fn (1) = Fn .
• fibonacci(n) gives the nth Fibonacci number, Fn
• fibonacci(n, x) gives the nth Fibonacci polynomial in x, Fn (x)
See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), harmonic
(page 490), lucas (page 492), genocchi (page 493), partition (page 493), tribonacci
(page 489)

References

[R136], [R137]

Examples

>>> from sympy import fibonacci, Symbol

>>> [fibonacci(x) for x in range(11)]

[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
>>> fibonacci(5, Symbol('t'))
t**4 + 3*t**2 + 1

tribonacci

class sympy.functions.combinatorial.numbers.tribonacci
Tribonacci numbers / Tribonacci polynomials
The Fibonacci numbers are the integer sequence defined by the initial terms T0 = 0,
T1 = 1, T2 = 1 and the three-term recurrence relation Tn = Tn−1 + Tn−2 + Tn−3 .
The Tribonacci polynomials are defined by T0 (x) = 0, T1 (x) = 1, T2 (x) = x2 , and Tn (x) =
x2 Tn−1 (x) + xTn−2 (x) + Tn−3 (x) for n > 2. For all positive integers n, Tn (1) = Tn .
• tribonacci(n) gives the nth Tribonacci number, Tn
• tribonacci(n, x) gives the nth Tribonacci polynomial in x, Tn (x)
See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), fi-
bonacci (page 488), harmonic (page 490), lucas (page 492), genocchi (page 493), par-
tition (page 493)

5.10. Functions Module 489

SymPy Documentation, Release 1.3

References

[R138], [R139], [R140]

Examples

>>> from sympy import tribonacci, Symbol

>>> [tribonacci(x) for x in range(11)]

[0, 1, 1, 2, 4, 7, 13, 24, 44, 81, 149]
>>> tribonacci(5, Symbol('t'))
t**8 + 3*t**5 + 3*t**2

harmonic

class sympy.functions.combinatorial.numbers.harmonic
Harmonic numbers
1 1
The nth harmonic number is given by Hn = 1 + 2 + 3 + . . . + n1 .
More generally:
∑
n
1
Hn,m =
km
k=1

As n → ∞, Hn,m → ζ(m), the Riemann zeta function.

• harmonic(n) gives the nth harmonic number, Hn
• harmonic(n, m) gives the nth generalized harmonic number of order m, Hn,m , where
harmonic(n) == harmonic(n, 1)
See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), fi-
bonacci (page 488), lucas (page 492), genocchi (page 493), partition (page 493),
tribonacci (page 489)

References

[R141], [R142], [R143]

Examples

>>> from sympy import harmonic, oo

>>> [harmonic(n) for n in range(6)]

[0, 1, 3/2, 11/6, 25/12, 137/60]
>>> [harmonic(n, 2) for n in range(6)]
[0, 1, 5/4, 49/36, 205/144, 5269/3600]
>>> harmonic(oo, 2)
pi**2/6

490 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Symbol, Sum

>>> n = Symbol(”n”)

>>> harmonic(n).rewrite(Sum)
Sum(1/_k, (_k, 1, n))

We can evaluate harmonic numbers for all integral and positive rational arguments:

>>> from sympy import S, expand_func, simplify

>>> harmonic(8)
761/280
>>> harmonic(11)
83711/27720

>>> H = harmonic(1/S(3))
>>> H
harmonic(1/3)
>>> He = expand_func(H)
>>> He
-log(6) - sqrt(3)*pi/6 + 2*Sum(log(sin(_k*pi/3))*cos(2*_k*pi/3), (_k, 1, 1))
+ 3*Sum(1/(3*_k + 1), (_k, 0, 0))
>>> He.doit()
-log(6) - sqrt(3)*pi/6 - log(sqrt(3)/2) + 3
>>> H = harmonic(25/S(7))
>>> He = simplify(expand_func(H).doit())
>>> He
log(sin(pi/7)**(-2*cos(pi/7))*sin(2*pi/7)**(2*cos(16*pi/7))*cos(pi/14)**(-
,→2*sin(pi/14))/14)

+ pi*tan(pi/14)/2 + 30247/9900
>>> He.n(40)
1.983697455232980674869851942390639915940
>>> harmonic(25/S(7)).n(40)
1.983697455232980674869851942390639915940

We can rewrite harmonic numbers in terms of polygamma functions:

>>> from sympy import digamma, polygamma

>>> m = Symbol(”m”)

>>> harmonic(n).rewrite(digamma)
polygamma(0, n + 1) + EulerGamma

>>> harmonic(n).rewrite(polygamma)
polygamma(0, n + 1) + EulerGamma

>>> harmonic(n,3).rewrite(polygamma)
polygamma(2, n + 1)/2 - polygamma(2, 1)/2

>>> harmonic(n,m).rewrite(polygamma)
(-1)**m*(polygamma(m - 1, 1) - polygamma(m - 1, n + 1))/factorial(m - 1)

Integer offsets in the argument can be pulled out:

>>> from sympy import expand_func

5.10. Functions Module 491

SymPy Documentation, Release 1.3

>>> expand_func(harmonic(n+4))
harmonic(n) + 1/(n + 4) + 1/(n + 3) + 1/(n + 2) + 1/(n + 1)

>>> expand_func(harmonic(n-4))
harmonic(n) - 1/(n - 1) - 1/(n - 2) - 1/(n - 3) - 1/n

Some limits can be computed as well:

>>> from sympy import limit, oo

>>> limit(harmonic(n), n, oo)

oo

>>> limit(harmonic(n, 2), n, oo)

pi**2/6

>>> limit(harmonic(n, 3), n, oo)

-polygamma(2, 1)/2

However we can not compute the general relation yet:

>>> limit(harmonic(n, m), n, oo)

harmonic(oo, m)

which equals zeta(m) for m > 1.

lucas

class sympy.functions.combinatorial.numbers.lucas
Lucas numbers
Lucas numbers satisfy a recurrence relation similar to that of the Fibonacci sequence,
in which each term is the sum of the preceding two. They are generated by choosing the
initial values L0 = 2 and L1 = 1.
• lucas(n) gives the nth Lucas number
See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), fi-
bonacci (page 488), harmonic (page 490), genocchi (page 493), partition (page 493),
tribonacci (page 489)

References

[R144], [R145]

Examples

>>> from sympy import lucas

492 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> [lucas(x) for x in range(11)]

[2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123]

genocchi

class sympy.functions.combinatorial.numbers.genocchi
Genocchi numbers
The Genocchi numbers are a sequence of integers Gn that satisfy the relation:
∞
∑
2t Gn tn
=
et + 1 n=1 n!

See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), fi-
bonacci (page 488), harmonic (page 490), lucas (page 492), partition (page 493),
tribonacci (page 489)

References

[R146], [R147]

Examples

>>> from sympy import Symbol

>>> from sympy.functions import genocchi
>>> [genocchi(n) for n in range(1, 9)]
[1, -1, 0, 1, 0, -3, 0, 17]
>>> n = Symbol('n', integer=True, positive=True)
>>> genocchi(2*n + 1)
0

partition

class sympy.functions.combinatorial.numbers.partition
Partition numbers
The Partition numbers are a sequence of integers pn that represent the number of dis-
tinct ways of representing n as a sum of natural numbers (with order irrelevant). The
generating function for pn is given by:
∞
∑ ∞
∏
pn xn = (1 − xk )−1
n=0 k=1

See also:
bell (page 479), bernoulli (page 480), catalan (page 483), euler (page 484), fi-
bonacci (page 488), harmonic (page 490), lucas (page 492), genocchi (page 493), tri-
bonacci (page 489)

5.10. Functions Module 493

SymPy Documentation, Release 1.3

References

[R148], [R149]

Examples

>>> from sympy import Symbol

>>> from sympy.functions import partition
>>> [partition(n) for n in range(9)]
[1, 1, 2, 3, 5, 7, 11, 15, 22]
>>> n = Symbol('n', integer=True, negative=True)
>>> partition(n)
0

MultiFactorial

class sympy.functions.combinatorial.factorials.MultiFactorial

RisingFactorial

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

rf (x, k) = x · (x + 1) · · · (x + k − 1)

where x can be arbitrary expression and k is an integer. For more information check
“Concrete mathematics” by Graham, pp. 66 or visit http://mathworld.wolfram.com/
RisingFactorial.html page.
When x is a Poly instance of degree >= 1 with a single variable, rf (x, k) = x(y) · x(y +
1) · · · x(y +k −1), where y is the variable of x. This is as described in Peter Paule, “Greatest
Factorial Factorization and Symbolic Summation”, Journal of Symbolic Computation, vol.
20, pp. 235-268, 1995.
See also:
factorial (page 485), factorial2 (page 487), FallingFactorial (page 488)

References

[R150]

Examples

>>> from sympy import rf, symbols, factorial, ff, binomial, Poly
>>> from sympy.abc import x
>>> n, k = symbols('n k', integer=True)
>>> rf(x, 0)
(continues on next page)

494 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

1
>>> rf(1, 5)
120
>>> rf(x, 5) == x*(1 + x)*(2 + x)*(3 + x)*(4 + x)
True
>>> rf(Poly(x**3, x), 2)
Poly(x**6 + 3*x**5 + 3*x**4 + x**3, x, domain='ZZ')

Rewrite

>>> rf(x, k).rewrite(ff)

FallingFactorial(k + x - 1, k)
>>> rf(x, k).rewrite(binomial)
binomial(k + x - 1, k)*factorial(k)
>>> rf(n, k).rewrite(factorial)
factorial(k + n - 1)/factorial(n - 1)

stirling

sympy.functions.combinatorial.numbers.stirling(n, k, d=None, kind=2,

signed=False)
Return Stirling number S(n, k) of the first or second (default) kind.
The sum of all Stirling numbers of the second kind for k = 1 through n is bell(n). The
recurrence relationship for these numbers is:
{ } { } { }
0 n 0
= 1; = = 0;
0 0 k
{ } { } { }
n+1 n n
=j +
k k k−1
where j is: n for Stirling numbers of the first kind −n for signed Stirling numbers of the
first kind k for Stirling numbers of the second kind
The first kind of Stirling number counts the number of permutations of n distinct items
that have k cycles; the second kind counts the ways in which n distinct items can be
partitioned into k parts. If d is given, the “reduced Stirling number of the second kind” is
returned: S^{d}(n, k) = S(n - d + 1, k - d + 1) with n >= k >= d. (This counts
the ways to partition n consecutive integers into k groups with no pairwise difference
less than d. See example below.)
To obtain the signed Stirling numbers of the first kind, use keyword signed=True. Using
this keyword automatically sets kind to 1.
See also:
sympy.utilities.iterables.multiset_partitions (page 1466)

References

[R151], [R152]

5.10. Functions Module 495

SymPy Documentation, Release 1.3

Examples

>>> from sympy.functions.combinatorial.numbers import stirling, bell

>>> from sympy.combinatorics import Permutation
>>> from sympy.utilities.iterables import multiset_partitions, permutations

First kind (unsigned by default):

>>> [stirling(6, i, kind=1) for i in range(7)]

[0, 120, 274, 225, 85, 15, 1]
>>> perms = list(permutations(range(4)))
>>> [sum(Permutation(p).cycles == i for p in perms) for i in range(5)]
[0, 6, 11, 6, 1]
>>> [stirling(4, i, kind=1) for i in range(5)]
[0, 6, 11, 6, 1]

First kind (signed):

>>> [stirling(4, i, signed=True) for i in range(5)]

[0, -6, 11, -6, 1]

Second kind:

>>> [stirling(10, i) for i in range(12)]

[0, 1, 511, 9330, 34105, 42525, 22827, 5880, 750, 45, 1, 0]
>>> sum(_) == bell(10)
True
>>> len(list(multiset_partitions(range(4), 2))) == stirling(4, 2)
True

Reduced second kind:

>>> from sympy import subsets, oo

>>> def delta(p):
... if len(p) == 1:
... return oo
... return min(abs(i[0] - i[1]) for i in subsets(p, 2))
>>> parts = multiset_partitions(range(5), 3)
>>> d = 2
>>> sum(1 for p in parts if all(delta(i) >= d for i in p))
7
>>> stirling(5, 3, 2)
7

Enumeration

Three functions are available. Each of them attempts to efficiently compute a given combi-
natorial quantity for a given set or multiset which can be entered as an integer, sequence or
multiset (dictionary with elements as keys and multiplicities as values). The k parameter indi-
cates the number of elements to pick (or the number of partitions to make). When k is None,
the sum of the enumeration for all k (from 0 through the number of items represented by n)
is returned. A replacement parameter is recognized for combinations and permutations; this
indicates that any item may appear with multiplicity as high as the number of items in the
original set.

496 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.functions.combinatorial.numbers import nC, nP, nT

>>> items = 'baby'

nC

Calculate the number of combinations of length k.

>>> [nC(items, k) for k in range(len(items) + 1)], nC(items)

([1, 3, 4, 3, 1], 12)
>>> nC('aaa', 2)
1
>>> nC('abc', 2)
3
>>> nC(3, 2)
3

nP

Calculate the number of permutations of length k.

>>> [nP(items, k) for k in range(len(items) + 1)], nP(items)

([1, 3, 7, 12, 12], 35)
>>> nC('aaa', 2)
1
>>> nC('abc', 2)
3
>>> nC(3, 2)
3

nT

Calculate the number of partitions that have k parts.

>>> [nT(items, k) for k in range(len(items) + 1)], nT(items)

([0, 1, 5, 4, 1], 11)
>>> nT('aaa', 2)
1
>>> nT('abc', 2)
3
>>> nT(3, 2)
1

Note that the integer for n indicates identical items for nT but indicates n different items for
nC and nP.

Special

5.10. Functions Module 497

SymPy Documentation, Release 1.3

DiracDelta

class sympy.functions.special.delta_functions.DiracDelta
The DiracDelta function and its derivatives.
DiracDelta is not an ordinary function. It can be rigorously defined either as a distribu-
tion or as a measure.
DiracDelta only makes sense in definite integrals, and in particular, integrals of the form
Integral(f(x)*DiracDelta(x - x0), (x, a, b)), where it equals f(x0) if a <= x0
<= b and 0 otherwise. Formally, DiracDelta acts in some ways like a function that is 0
everywhere except at 0, but in many ways it also does not. It can often be useful to
treat DiracDelta in formal ways, building up and manipulating expressions with delta
functions (which may eventually be integrated), but care must be taken to not treat it
as a real function. SymPy’s oo is similar. It only truly makes sense formally in certain
contexts (such as integration limits), but SymPy allows its use everywhere, and it tries
to be consistent with operations on it (like 1/oo), but it is easy to get into trouble and get
wrong results if oo is treated too much like a number. Similarly, if DiracDelta is treated
too much like a function, it is easy to get wrong or nonsensical results.
DiracDelta function has the following properties:
1) diff(Heaviside(x), x) = DiracDelta(x)
2) integrate(DiracDelta(x - a)*f(x),(x, -oo, oo)) = f(a) and inte-
grate(DiracDelta(x - a)*f(x),(x, a - e, a + e)) = f(a)
3) DiracDelta(x) = 0 for all x != 0
4) DiracDelta(g(x)) = Sum_i(DiracDelta(x - x_i)/abs(g'(x_i))) Where x_i-s
are the roots of g
5) DiracDelta(-x) = DiracDelta(x)
Derivatives of k-th order of DiracDelta have the following property:
6) DiracDelta(x, k) = 0, for all x != 0
7) DiracDelta(-x, k) = -DiracDelta(x, k) for odd k
8) DiracDelta(-x, k) = DiracDelta(x, k) for even k
See also:
Heaviside (page 501), simplify, is_simple (page 500), sympy.functions.special.
tensor_functions.KroneckerDelta (page 576)

References

[R213]

Examples

>>> from sympy import DiracDelta, diff, pi, Piecewise

>>> from sympy.abc import x, y

498 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> DiracDelta(x)
DiracDelta(x)
>>> DiracDelta(1)
0
>>> DiracDelta(-1)
0
>>> DiracDelta(pi)
0
>>> DiracDelta(x - 4).subs(x, 4)
DiracDelta(0)
>>> diff(DiracDelta(x))
DiracDelta(x, 1)
>>> diff(DiracDelta(x - 1),x,2)
DiracDelta(x - 1, 2)
>>> diff(DiracDelta(x**2 - 1),x,2)
2*(2*x**2*DiracDelta(x**2 - 1, 2) + DiracDelta(x**2 - 1, 1))
>>> DiracDelta(3*x).is_simple(x)
True
>>> DiracDelta(x**2).is_simple(x)
False
>>> DiracDelta((x**2 - 1)*y).expand(diracdelta=True, wrt=x)
DiracDelta(x - 1)/(2*Abs(y)) + DiracDelta(x + 1)/(2*Abs(y))

classmethod eval(arg, k=0)

Returns a simplified form or a value of DiracDelta depending on the argument passed
by the DiracDelta object.
The eval() method is automatically called when the DiracDelta class is about to
be instantiated and it returns either some simplified instance or the unevaluated
instance depending on the argument passed. In other words, eval() method is not
needed to be called explicitly, it is being called and evaluated once the object is
called.

Examples

>>> from sympy import DiracDelta, S, Subs

>>> from sympy.abc import x

>>> DiracDelta(x)
DiracDelta(x)

>>> DiracDelta(-x, 1)
-DiracDelta(x, 1)

>>> DiracDelta(1)
0

>>> DiracDelta(5, 1)
0

>>> DiracDelta(0)
DiracDelta(0)

5.10. Functions Module 499

SymPy Documentation, Release 1.3

>>> DiracDelta(-1)
0

>>> DiracDelta(S.NaN)
nan

>>> DiracDelta(x).eval(1)
0

>>> DiracDelta(x - 100).subs(x, 5)

0

>>> DiracDelta(x - 100).subs(x, 100)

DiracDelta(0)

fdiff(argindex=1)
Returns the first derivative of a DiracDelta Function.
The difference between diff() and fdiff() is:- diff() is the user-level function
and fdiff() is an object method. fdiff() is just a convenience method available in
the Function class. It returns the derivative of the function without considering the
chain rule. diff(function, x) calls Function._eval_derivative which in turn
calls fdiff() internally to compute the derivative of the function.

Examples

>>> from sympy import DiracDelta, diff

>>> from sympy.abc import x

>>> DiracDelta(x).fdiff()
DiracDelta(x, 1)

>>> DiracDelta(x, 1).fdiff()

DiracDelta(x, 2)

>>> DiracDelta(x**2 - 1).fdiff()

DiracDelta(x**2 - 1, 1)

>>> diff(DiracDelta(x, 1)).fdiff()

DiracDelta(x, 3)

is_simple(self, x)
Tells whether the argument(args[0]) of DiracDelta is a linear expression in x.
x can be:
• a symbol
See also:
simplify, Diracdelta

500 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import DiracDelta, cos

>>> from sympy.abc import x, y

>>> DiracDelta(x*y).is_simple(x)
True
>>> DiracDelta(x*y).is_simple(y)
True

>>> DiracDelta(x**2 + x - 2).is_simple(x)

False

>>> DiracDelta(cos(x)).is_simple(x)
False

Heaviside

class sympy.functions.special.delta_functions.Heaviside
Heaviside Piecewise function
Heaviside function has the following properties [R214]:
1) diff(Heaviside(x),x) = DiracDelta(x) ( 0, if x < 0
2) Heaviside(x) = < ( undefined if x==0 [1] ( 1, if x > 0
3) Max(0,x).diff(x) = Heaviside(x)
To specify the value of Heaviside at x=0, a second argument can be given. Omit this 2nd
argument or pass None to recover the default behavior.
>>> from sympy import Heaviside, S
>>> from sympy.abc import x
>>> Heaviside(9)
1
>>> Heaviside(-9)
0
>>> Heaviside(0)
Heaviside(0)
>>> Heaviside(0, S.Half)
1/2
>>> (Heaviside(x) + 1).replace(Heaviside(x), Heaviside(x, 1))
Heaviside(x, 1) + 1

See also:
DiracDelta (page 498)

References

[R215], [R216]
classmethod eval(arg, H0=None)
Returns a simplified form or a value of Heaviside depending on the argument passed
by the Heaviside object.

5.10. Functions Module 501

SymPy Documentation, Release 1.3

The eval() method is automatically called when the Heaviside class is about to
be instantiated and it returns either some simplified instance or the unevaluated
instance depending on the argument passed. In other words, eval() method is not
needed to be called explicitly, it is being called and evaluated once the object is
called.

Examples

>>> from sympy import Heaviside, S

>>> from sympy.abc import x

>>> Heaviside(x)
Heaviside(x)

>>> Heaviside(19)
1

>>> Heaviside(0)
Heaviside(0)

>>> Heaviside(0, 1)
1

>>> Heaviside(-5)
0

>>> Heaviside(S.NaN)
nan

>>> Heaviside(x).eval(100)
1

>>> Heaviside(x - 100).subs(x, 5)

0

>>> Heaviside(x - 100).subs(x, 105)

1

fdiff(argindex=1)
Returns the first derivative of a Heaviside Function.

Examples

>>> from sympy import Heaviside, diff

>>> from sympy.abc import x

>>> Heaviside(x).fdiff()
DiracDelta(x)

502 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Heaviside(x**2 - 1).fdiff()

DiracDelta(x**2 - 1)

>>> diff(Heaviside(x)).fdiff()
DiracDelta(x, 1)

Singularity Function

class sympy.functions.special.singularity_functions.SingularityFunction
The Singularity functions are a class of discontinuous functions. They take a variable, an
offset and an exponent as arguments. These functions are represented using Macaulay
brackets as :
SingularityFunction(x, a, n) := <x - a>^n
The singularity function will automatically evaluate to Derivative(DiracDelta(x - a),
x, -n - 1) if n < 0 and (x - a)**n*Heaviside(x - a) if n >= 0.
See also:
DiracDelta, Heaviside

Examples

>>> from sympy import SingularityFunction, diff, Piecewise, DiracDelta, Heaviside,

,→ Symbol

>>> from sympy.abc import x, a, n

>>> SingularityFunction(x, a, n)
SingularityFunction(x, a, n)
>>> y = Symbol('y', positive=True)
>>> n = Symbol('n', nonnegative=True)
>>> SingularityFunction(y, -10, n)
(y + 10)**n
>>> y = Symbol('y', negative=True)
>>> SingularityFunction(y, 10, n)
0
>>> SingularityFunction(x, 4, -1).subs(x, 4)
oo
>>> SingularityFunction(x, 10, -2).subs(x, 10)
oo
>>> SingularityFunction(4, 1, 5)
243
>>> diff(SingularityFunction(x, 1, 5) + SingularityFunction(x, 1, 4), x)
4*SingularityFunction(x, 1, 3) + 5*SingularityFunction(x, 1, 4)
>>> diff(SingularityFunction(x, 4, 0), x, 2)
SingularityFunction(x, 4, -2)
>>> SingularityFunction(x, 4, 5).rewrite(Piecewise)
Piecewise(((x - 4)**5, x - 4 > 0), (0, True))
>>> expr = SingularityFunction(x, a, n)
>>> y = Symbol('y', positive=True)
>>> n = Symbol('n', nonnegative=True)
>>> expr.subs({x: y, a: -10, n: n})
(y + 10)**n

5.10. Functions Module 503

SymPy Documentation, Release 1.3

The methods rewrite(DiracDelta), rewrite(Heaviside) and

rewrite('HeavisideDiracDelta') returns the same output. One can use any of
these methods according to their choice.

>>> expr = SingularityFunction(x, 4, 5) + SingularityFunction(x, -3, -1) -␣

,→SingularityFunction(x, 0, -2)

>>> expr.rewrite(Heaviside)
(x - 4)**5*Heaviside(x - 4) + DiracDelta(x + 3) - DiracDelta(x, 1)
>>> expr.rewrite(DiracDelta)
(x - 4)**5*Heaviside(x - 4) + DiracDelta(x + 3) - DiracDelta(x, 1)
>>> expr.rewrite('HeavisideDiracDelta')
(x - 4)**5*Heaviside(x - 4) + DiracDelta(x + 3) - DiracDelta(x, 1)

Reference

classmethod eval(variable, offset, exponent)

Returns a simplified form or a value of Singularity Function depending on the argu-
ment passed by the object.
The eval() method is automatically called when the SingularityFunction class is
about to be instantiated and it returns either some simplified instance or the uneval-
uated instance depending on the argument passed. In other words, eval() method
is not needed to be called explicitly, it is being called and evaluated once the object
is called.

Examples

>>> from sympy import SingularityFunction, Symbol, nan

>>> from sympy.abc import x, a, n
>>> SingularityFunction(x, a, n)
SingularityFunction(x, a, n)
>>> SingularityFunction(5, 3, 2)
4
>>> SingularityFunction(x, a, nan)
nan
>>> SingularityFunction(x, 3, 0).subs(x, 3)
1
>>> SingularityFunction(x, a, n).eval(3, 5, 1)
0
>>> SingularityFunction(x, a, n).eval(4, 1, 5)
243
>>> x = Symbol('x', positive = True)
>>> a = Symbol('a', negative = True)
>>> n = Symbol('n', nonnegative = True)
>>> SingularityFunction(x, a, n)
(-a + x)**n
>>> x = Symbol('x', negative = True)
>>> a = Symbol('a', positive = True)
>>> SingularityFunction(x, a, n)
0

fdiff(argindex=1)
Returns the first derivative of a DiracDelta Function.

504 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The difference between diff() and fdiff() is:- diff() is the user-level function
and fdiff() is an object method. fdiff() is just a convenience method available in
the Function class. It returns the derivative of the function without considering the
chain rule. diff(function, x) calls Function._eval_derivative which in turn
calls fdiff() internally to compute the derivative of the function.

Gamma, Beta and related Functions

class sympy.functions.special.gamma_functions.gamma
The gamma function
∫ ∞
Γ(x) := tx−1 e−t dt.
0

The gamma function implements the function which passes through the values of the
factorial function, i.e. Γ(n) = (n − 1)! when n is an integer. More general, Γ(z) is defined
in the whole complex plane except at the negative integers where there are simple poles.
See also:

lowergamma (page 511) Lower incomplete gamma function.

uppergamma (page 510) Upper incomplete gamma function.
polygamma (page 508) Polygamma function.
loggamma (page 506) Log Gamma function.
digamma (page 509) Digamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R218], [R219], [R220], [R221]

Examples

>>> from sympy import S, I, pi, oo, gamma

>>> from sympy.abc import x

Several special values are known:

>>> gamma(1)
1
>>> gamma(4)
6
>>> gamma(S(3)/2)
sqrt(pi)/2

The Gamma function obeys the mirror symmetry:

5.10. Functions Module 505

SymPy Documentation, Release 1.3

>>> from sympy import conjugate

>>> conjugate(gamma(x))
gamma(conjugate(x))

Differentiation with respect to x is supported:

>>> from sympy import diff

>>> diff(gamma(x), x)
gamma(x)*polygamma(0, x)

Series expansion is also supported:

>>> from sympy import series

>>> series(gamma(x), x, 0, 3)
1/x - EulerGamma + x*(EulerGamma**2/2 + pi**2/12) + x**2*(-EulerGamma*pi**2/12 +␣
,→polygamma(2, 1)/6 - EulerGamma**3/6) + O(x**3)

We can numerically evaluate the gamma function to arbitrary precision on the whole
complex plane:

>>> gamma(pi).evalf(40)
2.288037795340032417959588909060233922890
>>> gamma(1+I).evalf(20)
0.49801566811835604271 - 0.15494982830181068512*I

class sympy.functions.special.gamma_functions.loggamma
The loggamma function implements the logarithm of the gamma function i.e, log Γ(x).
See also:

gamma (page 505) Gamma function.

lowergamma (page 511) Lower incomplete gamma function.
uppergamma (page 510) Upper incomplete gamma function.
polygamma (page 508) Polygamma function.
digamma (page 509) Digamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R222], [R223], [R224], [R225]

Examples

Several special values are known. For numerical integral arguments we have:

>>> from sympy import loggamma

>>> loggamma(-2)
oo
>>> loggamma(0)
(continues on next page)

506 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

oo
>>> loggamma(1)
0
>>> loggamma(2)
0
>>> loggamma(3)
log(2)

and for symbolic values:

>>> from sympy import Symbol

>>> n = Symbol(”n”, integer=True, positive=True)
>>> loggamma(n)
log(gamma(n))
>>> loggamma(-n)
oo

for half-integral values:

>>> from sympy import S, pi

>>> loggamma(S(5)/2)
log(3*sqrt(pi)/4)
>>> loggamma(n/2)
log(2**(-n + 1)*sqrt(pi)*gamma(n)/gamma(n/2 + 1/2))

and general rational arguments:

>>> from sympy import expand_func

>>> L = loggamma(S(16)/3)
>>> expand_func(L).doit()
-5*log(3) + loggamma(1/3) + log(4) + log(7) + log(10) + log(13)
>>> L = loggamma(S(19)/4)
>>> expand_func(L).doit()
-4*log(4) + loggamma(3/4) + log(3) + log(7) + log(11) + log(15)
>>> L = loggamma(S(23)/7)
>>> expand_func(L).doit()
-3*log(7) + log(2) + loggamma(2/7) + log(9) + log(16)

The loggamma function has the following limits towards infinity:

>>> from sympy import oo

>>> loggamma(oo)
oo
>>> loggamma(-oo)
zoo

The loggamma function obeys the mirror symmetry if x ∈ C \ {−∞, 0}:

>>> from sympy.abc import x

>>> from sympy import conjugate
>>> conjugate(loggamma(x))
loggamma(conjugate(x))

Differentiation with respect to x is supported:

5.10. Functions Module 507

SymPy Documentation, Release 1.3

>>> from sympy import diff

>>> diff(loggamma(x), x)
polygamma(0, x)

Series expansion is also supported:

>>> from sympy import series
>>> series(loggamma(x), x, 0, 4)
-log(x) - EulerGamma*x + pi**2*x**2/12 + x**3*polygamma(2, 1)/6 + O(x**4)

We can numerically evaluate the gamma function to arbitrary precision on the whole
complex plane:
>>> from sympy import I
>>> loggamma(5).evalf(30)
3.17805383034794561964694160130
>>> loggamma(I).evalf(20)
-0.65092319930185633889 - 1.8724366472624298171*I

class sympy.functions.special.gamma_functions.polygamma
The function polygamma(n, z) returns log(gamma(z)).diff(n + 1).
It is a meromorphic function on C and defined as the (n+1)-th derivative of the logarithm
of the gamma function:
n+1
d
ψ (n) (z) := log Γ(z).
dz n+1

See also:

gamma (page 505) Gamma function.

lowergamma (page 511) Lower incomplete gamma function.
uppergamma (page 510) Upper incomplete gamma function.
loggamma (page 506) Log Gamma function.
digamma (page 509) Digamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R226], [R227], [R228], [R229]

Examples

Several special values are known:

>>> from sympy import S, polygamma
>>> polygamma(0, 1)
-EulerGamma
>>> polygamma(0, 1/S(2))
(continues on next page)

508 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

-2*log(2) - EulerGamma
>>> polygamma(0, 1/S(3))
-log(3) - sqrt(3)*pi/6 - EulerGamma - log(sqrt(3))
>>> polygamma(0, 1/S(4))
-pi/2 - log(4) - log(2) - EulerGamma
>>> polygamma(0, 2)
-EulerGamma + 1
>>> polygamma(0, 23)
-EulerGamma + 19093197/5173168

>>> from sympy import oo, I

>>> polygamma(0, oo)
oo
>>> polygamma(0, -oo)
oo
>>> polygamma(0, I*oo)
oo
>>> polygamma(0, -I*oo)
oo

Differentiation with respect to x is supported:

>>> from sympy import Symbol, diff
>>> x = Symbol(”x”)
>>> diff(polygamma(0, x), x)
polygamma(1, x)
>>> diff(polygamma(0, x), x, 2)
polygamma(2, x)
>>> diff(polygamma(0, x), x, 3)
polygamma(3, x)
>>> diff(polygamma(1, x), x)
polygamma(2, x)
>>> diff(polygamma(1, x), x, 2)
polygamma(3, x)
>>> diff(polygamma(2, x), x)
polygamma(3, x)
>>> diff(polygamma(2, x), x, 2)
polygamma(4, x)

>>> n = Symbol(”n”)
>>> diff(polygamma(n, x), x)
polygamma(n + 1, x)
>>> diff(polygamma(n, x), x, 2)
polygamma(n + 2, x)

We can rewrite polygamma functions in terms of harmonic numbers:

>>> from sympy import harmonic
>>> polygamma(0, x).rewrite(harmonic)
harmonic(x - 1) - EulerGamma
>>> polygamma(2, x).rewrite(harmonic)
2*harmonic(x - 1, 3) - 2*zeta(3)
>>> ni = Symbol(”n”, integer=True)
>>> polygamma(ni, x).rewrite(harmonic)
(-1)**(n + 1)*(-harmonic(x - 1, n + 1) + zeta(n + 1))*factorial(n)

sympy.functions.special.gamma_functions.digamma(x)

5.10. Functions Module 509

SymPy Documentation, Release 1.3

The digamma function is the first derivative of the loggamma function i.e,

d Γ′ (z)
ψ(x) := log Γ(z) =
dz Γ(z)

In this case, digamma(z) = polygamma(0, z).

See also:

gamma (page 505) Gamma function.

lowergamma (page 511) Lower incomplete gamma function.
uppergamma (page 510) Upper incomplete gamma function.
polygamma (page 508) Polygamma function.
loggamma (page 506) Log Gamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R230], [R231], [R232]

sympy.functions.special.gamma_functions.trigamma(x)
The trigamma function is the second derivative of the loggamma function i.e,
2
d
ψ (1) (z) := log Γ(z).
dz 2
In this case, trigamma(z) = polygamma(1, z).
See also:

gamma (page 505) Gamma function.

lowergamma (page 511) Lower incomplete gamma function.
uppergamma (page 510) Upper incomplete gamma function.
polygamma (page 508) Polygamma function.
loggamma (page 506) Log Gamma function.
digamma (page 509) Digamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R233], [R234], [R235]

class sympy.functions.special.gamma_functions.uppergamma
The upper incomplete gamma function.
It can be defined as the meromorphic continuation of
∫ ∞
Γ(s, x) := ts−1 e−t dt = Γ(s) − γ(s, x).
x

510 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

where γ(s, x) is the lower incomplete gamma function, lowergamma (page 511). This can
be shown to be the same as
( )
xs s
Γ(s, x) = Γ(s) − 1 F1 −x ,
s s+1
where 1 F1 is the (confluent) hypergeometric function.
The upper incomplete gamma function is also essentially equivalent to the generalized
exponential integral:
∫ ∞ −xt
e
En (x) = dt = xn−1 Γ(1 − n, x).
1 tn

See also:

gamma (page 505) Gamma function.

lowergamma (page 511) Lower incomplete gamma function.
polygamma (page 508) Polygamma function.
loggamma (page 506) Log Gamma function.
digamma (page 509) Digamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R236], [R237], [R238], [R239], [R240], [R241]

Examples

>>> from sympy import uppergamma, S

>>> from sympy.abc import s, x
>>> uppergamma(s, x)
uppergamma(s, x)
>>> uppergamma(3, x)
2*(x**2/2 + x + 1)*exp(-x)
>>> uppergamma(-S(1)/2, x)
-2*sqrt(pi)*erfc(sqrt(x)) + 2*exp(-x)/sqrt(x)
>>> uppergamma(-2, x)
expint(3, x)/x**2

class sympy.functions.special.gamma_functions.lowergamma
The lower incomplete gamma function.
It can be defined as the meromorphic continuation of
∫ x
γ(s, x) := ts−1 e−t dt = Γ(s) − Γ(s, x).
0

This can be shown to be the same as

( )
xs s
γ(s, x) = 1 F1 −x ,
s s+1

5.10. Functions Module 511

SymPy Documentation, Release 1.3

where 1 F1 is the (confluent) hypergeometric function.

See also:

gamma (page 505) Gamma function.

uppergamma (page 510) Upper incomplete gamma function.
polygamma (page 508) Polygamma function.
loggamma (page 506) Log Gamma function.
digamma (page 509) Digamma function.
trigamma (page 510) Trigamma function.
sympy.functions.special.beta_functions.beta (page 512) Euler Beta function.

References

[R242], [R243], [R244], [R245], [R246]

Examples

>>> from sympy import lowergamma, S

>>> from sympy.abc import s, x
>>> lowergamma(s, x)
lowergamma(s, x)
>>> lowergamma(3, x)
-2*(x**2/2 + x + 1)*exp(-x) + 2
>>> lowergamma(-S(1)/2, x)
-2*sqrt(pi)*erf(sqrt(x)) - 2*exp(-x)/sqrt(x)

class sympy.functions.special.beta_functions.beta
The beta integral is called the Eulerian integral of the first kind by Legendre:
∫ 1
B(x, y) := tx−1 (1 − t)y−1 dt.
0

Beta function or Euler’s first integral is closely associated with gamma function. The
Beta function often used in probability theory and mathematical statistics. It satisfies
properties like:
1
B(a, 1) =
a
B(a, b) = B(b, a)
Γ(a)Γ(b)
B(a, b) =
Γ(a + b)
Therefore for integral values of a and b:
(a − 1)!(b − 1)!
B=
(a + b − 1)!

See also:

sympy.functions.special.gamma_functions.gamma (page 505) Gamma function.

512 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.functions.special.gamma_functions.uppergamma (page 510) Upper incom-

plete gamma function.
sympy.functions.special.gamma_functions.lowergamma (page 511) Lower incom-
plete gamma function.
sympy.functions.special.gamma_functions.polygamma (page 508) Polygamma
function.
sympy.functions.special.gamma_functions.loggamma (page 506) Log Gamma
function.
sympy.functions.special.gamma_functions.digamma (page 509) Digamma func-
tion.
sympy.functions.special.gamma_functions.trigamma (page 510) Trigamma func-
tion.

References

[R247], [R248], [R249]

Examples

>>> from sympy import I, pi

>>> from sympy.abc import x,y

The Beta function obeys the mirror symmetry:

>>> from sympy import beta

>>> from sympy import conjugate
>>> conjugate(beta(x,y))
beta(conjugate(x), conjugate(y))

Differentiation with respect to both x and y is supported:

>>> from sympy import beta

>>> from sympy import diff
>>> diff(beta(x,y), x)
(polygamma(0, x) - polygamma(0, x + y))*beta(x, y)

>>> from sympy import beta

>>> from sympy import diff
>>> diff(beta(x,y), y)
(polygamma(0, y) - polygamma(0, x + y))*beta(x, y)

We can numerically evaluate the gamma function to arbitrary precision on the whole
complex plane:

>>> from sympy import beta

>>> beta(pi,pi).evalf(40)
0.02671848900111377452242355235388489324562

>>> beta(1+I,1+I).evalf(20)
-0.2112723729365330143 - 0.7655283165378005676*I

5.10. Functions Module 513

SymPy Documentation, Release 1.3

Error Functions and Fresnel Integrals

class sympy.functions.special.error_functions.erf
The Gauss error function. This function is defined as:
∫ x
2
e−t dt.
2
erf(x) = √
π 0

See also:

erfc (page 515) Complementary error function.

erfi (page 516) Imaginary error function.
erf2 (page 517) Two-argument error function.
erfinv (page 518) Inverse error function.
erfcinv (page 519) Inverse Complementary error function.
erf2inv (page 520) Inverse two-argument error function.

References

[R250], [R251], [R252], [R253]

Examples

>>> from sympy import I, oo, erf

>>> from sympy.abc import z

Several special values are known:

>>> erf(0)
0
>>> erf(oo)
1
>>> erf(-oo)
-1
>>> erf(I*oo)
oo*I
>>> erf(-I*oo)
-oo*I

In general one can pull out factors of -1 and I from the argument:

>>> erf(-z)
-erf(z)

The error function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(erf(z))
erf(conjugate(z))

Differentiation with respect to z is supported:

514 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import diff

>>> diff(erf(z), z)
2*exp(-z**2)/sqrt(pi)

We can numerically evaluate the error function to arbitrary precision on the whole com-
plex plane:

>>> erf(4).evalf(30)
0.999999984582742099719981147840

>>> erf(-4*I).evalf(30)
-1296959.73071763923152794095062*I

class sympy.functions.special.error_functions.erfc
Complementary Error Function. The function is defined as:
∫ ∞
2
e−t dt
2
erfc(x) = √
π x

See also:

erf (page 514) Gaussian error function.

erfi (page 516) Imaginary error function.
erf2 (page 517) Two-argument error function.
erfinv (page 518) Inverse error function.
erfcinv (page 519) Inverse Complementary error function.
erf2inv (page 520) Inverse two-argument error function.

References

[R254], [R255], [R256], [R257]

Examples

>>> from sympy import I, oo, erfc

>>> from sympy.abc import z

Several special values are known:

>>> erfc(0)
1
>>> erfc(oo)
0
>>> erfc(-oo)
2
>>> erfc(I*oo)
-oo*I
>>> erfc(-I*oo)
oo*I

5.10. Functions Module 515

SymPy Documentation, Release 1.3

The error function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(erfc(z))
erfc(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(erfc(z), z)
-2*exp(-z**2)/sqrt(pi)

It also follows

>>> erfc(-z)
-erfc(z) + 2

We can numerically evaluate the complementary error function to arbitrary precision on

the whole complex plane:

>>> erfc(4).evalf(30)
0.0000000154172579002800188521596734869

>>> erfc(4*I).evalf(30)
1.0 - 1296959.73071763923152794095062*I

class sympy.functions.special.error_functions.erfi
Imaginary error function. The function erfi is defined as:
∫ x
2 2
erfi(x) = √ et dt
π 0

See also:

erf (page 514) Gaussian error function.

erfc (page 515) Complementary error function.
erf2 (page 517) Two-argument error function.
erfinv (page 518) Inverse error function.
erfcinv (page 519) Inverse Complementary error function.
erf2inv (page 520) Inverse two-argument error function.

References

[R258], [R259], [R260]

Examples

>>> from sympy import I, oo, erfi

>>> from sympy.abc import z

Several special values are known:

516 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> erfi(0)
0
>>> erfi(oo)
oo
>>> erfi(-oo)
-oo
>>> erfi(I*oo)
I
>>> erfi(-I*oo)
-I

In general one can pull out factors of -1 and I from the argument:
>>> erfi(-z)
-erfi(z)

>>> from sympy import conjugate

>>> conjugate(erfi(z))
erfi(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff
>>> diff(erfi(z), z)
2*exp(z**2)/sqrt(pi)

We can numerically evaluate the imaginary error function to arbitrary precision on the
whole complex plane:
>>> erfi(2).evalf(30)
18.5648024145755525987042919132

>>> erfi(-2*I).evalf(30)
-0.995322265018952734162069256367*I

class sympy.functions.special.error_functions.erf2
Two-argument error function. This function is defined as:
∫ y
2
e−t dt
2
erf2(x, y) = √
π x

See also:

erf (page 514) Gaussian error function.

erfc (page 515) Complementary error function.
erfi (page 516) Imaginary error function.
erfinv (page 518) Inverse error function.
erfcinv (page 519) Inverse Complementary error function.
erf2inv (page 520) Inverse two-argument error function.

References

[R261]

5.10. Functions Module 517

SymPy Documentation, Release 1.3

Examples

>>> from sympy import I, oo, erf2

>>> from sympy.abc import x, y

Several special values are known:

>>> erf2(0, 0)
0
>>> erf2(x, x)
0
>>> erf2(x, oo)
-erf(x) + 1
>>> erf2(x, -oo)
-erf(x) - 1
>>> erf2(oo, y)
erf(y) - 1
>>> erf2(-oo, y)
erf(y) + 1

In general one can pull out factors of -1:

>>> erf2(-x, -y)

-erf2(x, y)

The error function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(erf2(x, y))
erf2(conjugate(x), conjugate(y))

Differentiation with respect to x, y is supported:

>>> from sympy import diff

>>> diff(erf2(x, y), x)
-2*exp(-x**2)/sqrt(pi)
>>> diff(erf2(x, y), y)
2*exp(-y**2)/sqrt(pi)

class sympy.functions.special.error_functions.erfinv
Inverse Error Function. The erfinv function is defined as:

erf(x) = y ⇒ erfinv(y) = x

See also:

erf (page 514) Gaussian error function.

erfc (page 515) Complementary error function.
erfi (page 516) Imaginary error function.
erf2 (page 517) Two-argument error function.
erfcinv (page 519) Inverse Complementary error function.
erf2inv (page 520) Inverse two-argument error function.

518 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R262], [R263]

Examples

>>> from sympy import I, oo, erfinv

>>> from sympy.abc import x

Several special values are known:

>>> erfinv(0)
0
>>> erfinv(1)
oo

Differentiation with respect to x is supported:

>>> from sympy import diff
>>> diff(erfinv(x), x)
sqrt(pi)*exp(erfinv(x)**2)/2

We can numerically evaluate the inverse error function to arbitrary precision on [-1, 1]:
>>> erfinv(0.2).evalf(30)
0.179143454621291692285822705344

class sympy.functions.special.error_functions.erfcinv
Inverse Complementary Error Function. The erfcinv function is defined as:

erfc(x) = y ⇒ erfcinv(y) = x

See also:

erf (page 514) Gaussian error function.

erfc (page 515) Complementary error function.
erfi (page 516) Imaginary error function.
erf2 (page 517) Two-argument error function.
erfinv (page 518) Inverse error function.
erf2inv (page 520) Inverse two-argument error function.

References

[R264], [R265]

Examples

>>> from sympy import I, oo, erfcinv

>>> from sympy.abc import x

5.10. Functions Module 519

SymPy Documentation, Release 1.3

Several special values are known:

>>> erfcinv(1)
0
>>> erfcinv(0)
oo

Differentiation with respect to x is supported:

>>> from sympy import diff

>>> diff(erfcinv(x), x)
-sqrt(pi)*exp(erfcinv(x)**2)/2

class sympy.functions.special.error_functions.erf2inv
Two-argument Inverse error function. The erf2inv function is defined as:

erf2(x, w) = y ⇒ erf2inv(x, y) = w

See also:

erf (page 514) Gaussian error function.

erfc (page 515) Complementary error function.
erfi (page 516) Imaginary error function.
erf2 (page 517) Two-argument error function.
erfinv (page 518) Inverse error function.
erfcinv (page 519) Inverse complementary error function.

References

[R266]

Examples

>>> from sympy import I, oo, erf2inv, erfinv, erfcinv

>>> from sympy.abc import x, y

Several special values are known:

>>> erf2inv(0, 0)
0
>>> erf2inv(1, 0)
1
>>> erf2inv(0, 1)
oo
>>> erf2inv(0, y)
erfinv(y)
>>> erf2inv(oo, y)
erfcinv(-y)

Differentiation with respect to x and y is supported:

520 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import diff

>>> diff(erf2inv(x, y), x)
exp(-x**2 + erf2inv(x, y)**2)
>>> diff(erf2inv(x, y), y)
sqrt(pi)*exp(erf2inv(x, y)**2)/2

class sympy.functions.special.error_functions.FresnelIntegral
Base class for the Fresnel integrals.
class sympy.functions.special.error_functions.fresnels
Fresnel integral S.
This function is defined by
∫ z
π 2
S(z) = sin t dt.
0 2

It is an entire function.
See also:

fresnelc (page 522) Fresnel cosine integral.

References

[R267], [R268], [R269], [R270], [R271]

Examples

>>> from sympy import I, oo, fresnels

>>> from sympy.abc import z

Several special values are known:

>>> fresnels(0)
0
>>> fresnels(oo)
1/2
>>> fresnels(-oo)
-1/2
>>> fresnels(I*oo)
-I/2
>>> fresnels(-I*oo)
I/2

In general one can pull out factors of -1 and i from the argument:

>>> fresnels(-z)
-fresnels(z)
>>> fresnels(I*z)
-I*fresnels(z)

The Fresnel S integral obeys the mirror symmetry S(z) = S(z̄):

5.10. Functions Module 521

SymPy Documentation, Release 1.3

>>> from sympy import conjugate

>>> conjugate(fresnels(z))
fresnels(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(fresnels(z), z)
sin(pi*z**2/2)

Defining the Fresnel functions via an integral

>>> from sympy import integrate, pi, sin, gamma, expand_func

>>> integrate(sin(pi*z**2/2), z)
3*fresnels(z)*gamma(3/4)/(4*gamma(7/4))
>>> expand_func(integrate(sin(pi*z**2/2), z))
fresnels(z)

We can numerically evaluate the Fresnel integral to arbitrary precision on the whole
complex plane:

>>> fresnels(2).evalf(30)
0.343415678363698242195300815958

>>> fresnels(-2*I).evalf(30)
0.343415678363698242195300815958*I

class sympy.functions.special.error_functions.fresnelc
Fresnel integral C.
This function is defined by
∫ z
π 2
C(z) = cos t dt.
0 2

It is an entire function.
See also:

fresnels (page 521) Fresnel sine integral.

References

[R272], [R273], [R274], [R275], [R276]

Examples

>>> from sympy import I, oo, fresnelc

>>> from sympy.abc import z

Several special values are known:

522 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> fresnelc(0)
0
>>> fresnelc(oo)
1/2
>>> fresnelc(-oo)
-1/2
>>> fresnelc(I*oo)
I/2
>>> fresnelc(-I*oo)
-I/2

In general one can pull out factors of -1 and i from the argument:
>>> fresnelc(-z)
-fresnelc(z)
>>> fresnelc(I*z)
I*fresnelc(z)

The Fresnel C integral obeys the mirror symmetry C(z) = C(z̄):

>>> from sympy import conjugate
>>> conjugate(fresnelc(z))
fresnelc(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff
>>> diff(fresnelc(z), z)
cos(pi*z**2/2)

Defining the Fresnel functions via an integral

>>> from sympy import integrate, pi, cos, gamma, expand_func
>>> integrate(cos(pi*z**2/2), z)
fresnelc(z)*gamma(1/4)/(4*gamma(5/4))
>>> expand_func(integrate(cos(pi*z**2/2), z))
fresnelc(z)

We can numerically evaluate the Fresnel integral to arbitrary precision on the whole
complex plane:
>>> fresnelc(2).evalf(30)
0.488253406075340754500223503357

>>> fresnelc(-2*I).evalf(30)
-0.488253406075340754500223503357*I

Exponential, Logarithmic and Trigonometric Integrals

class sympy.functions.special.error_functions.Ei
The classical exponential integral.
For use in SymPy, this function is defined as
∑∞
xn
Ei(x) = + log(x) + γ,
n=1
n n!

5.10. Functions Module 523

SymPy Documentation, Release 1.3

where γ is the Euler-Mascheroni constant.

If x is a polar number, this defines an analytic function on the Riemann surface of the
logarithm. Otherwise this defines an analytic function in the cut plane C \ (−∞, 0].
Background
The name exponential integral comes from the following statement:
∫ x t
e
Ei(x) = dt
−∞ t

If the integral is interpreted as a Cauchy principal value, this statement holds for x > 0
and Ei(x) as defined above.
See also:

expint (page 525) Generalised exponential integral.

E1 (page 526) Special case of the generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.
Si (page 529) Sine integral.
Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.
sympy.functions.special.gamma_functions.uppergamma (page 510) Upper incom-
plete gamma function.

References

[R277], [R278], [R279]

Examples

>>> from sympy import Ei, polar_lift, exp_polar, I, pi

>>> from sympy.abc import x

>>> Ei(-1)
Ei(-1)

This yields a real value:

>>> Ei(-1).n(chop=True)
-0.219383934395520

On the other hand the analytic continuation is not real:

>>> Ei(polar_lift(-1)).n(chop=True)
-0.21938393439552 + 3.14159265358979*I

The exponential integral has a logarithmic branch point at the origin:

524 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Ei(x*exp_polar(2*I*pi))
Ei(x) + 2*I*pi

Differentiation is supported:

>>> Ei(x).diff(x)
exp(x)/x

The exponential integral is related to many other special functions. For example:

>>> from sympy import uppergamma, expint, Shi

>>> Ei(x).rewrite(expint)
-expint(1, x*exp_polar(I*pi)) - I*pi
>>> Ei(x).rewrite(Shi)
Chi(x) + Shi(x)

class sympy.functions.special.error_functions.expint
Generalized exponential integral.
This function is defined as

Eν (z) = z ν−1 Γ(1 − ν, z),

where Γ(1 − ν, z) is the upper incomplete gamma function (uppergamma).

Hence for z with positive real part we have
∫ ∞
e−zt
Eν (z) = dt,
1 zν

which explains the name.

The representation as an incomplete gamma function provides an analytic continuation
for Eν (z). If ν is a non-positive integer the exponential integral is thus an unbranched
function of z, otherwise there is a branch point at the origin. Refer to the incomplete
gamma function documentation for details of the branching behavior.
See also:

Ei (page 523) Another related function called exponential integral.

E1 (page 526) The classical case, returns expint(1, z).
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.
Si (page 529) Sine integral.
Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.

sympy.functions.special.gamma_functions.uppergamma (page 510)

References

[R280], [R281], [R282]

5.10. Functions Module 525

SymPy Documentation, Release 1.3

Examples

>>> from sympy import expint, S

>>> from sympy.abc import nu, z

Differentiation is supported. Differentiation with respect to z explains further the name:

for integral orders, the exponential integral is an iterated integral of the exponential
function.

>>> expint(nu, z).diff(z)

-expint(nu - 1, z)

Differentiation with respect to nu has no classical expression:

>>> expint(nu, z).diff(nu)

-z**(nu - 1)*meijerg(((), (1, 1)), ((0, 0, -nu + 1), ()), z)

At non-postive integer orders, the exponential integral reduces to the exponential func-
tion:

>>> expint(0, z)
exp(-z)/z
>>> expint(-1, z)
exp(-z)/z + exp(-z)/z**2

At half-integers it reduces to error functions:

>>> expint(S(1)/2, z)
sqrt(pi)*erfc(sqrt(z))/sqrt(z)

At positive integer orders it can be rewritten in terms of exponentials and expint(1, z).
Use expand_func() to do this:

>>> from sympy import expand_func

>>> expand_func(expint(5, z))
z**4*expint(1, z)/24 + (-z**3 + z**2 - 2*z + 6)*exp(-z)/24

The generalised exponential integral is essentially equivalent to the incomplete gamma

function:

>>> from sympy import uppergamma

>>> expint(nu, z).rewrite(uppergamma)
z**(nu - 1)*uppergamma(-nu + 1, z)

As such it is branched at the origin:

>>> from sympy import exp_polar, pi, I

>>> expint(4, z*exp_polar(2*pi*I))
I*pi*z**3/3 + expint(4, z)
>>> expint(nu, z*exp_polar(2*pi*I))
z**(nu - 1)*(exp(2*I*pi*nu) - 1)*gamma(-nu + 1) + expint(nu, z)

sympy.functions.special.error_functions.E1(z)
Classical case of the generalized exponential integral.
This is equivalent to expint(1, z).
See also:

526 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Ei (page 523) Exponential integral.

expint (page 525) Generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.
Si (page 529) Sine integral.
Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.

class sympy.functions.special.error_functions.li
The classical logarithmic integral.
For the use in SymPy, this function is defined as
∫ x
1
li(x) = dt .
0 log(t)

See also:

Li (page 528) Offset logarithmic integral.

Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.
E1 (page 526) Special case of the generalised exponential integral.
Si (page 529) Sine integral.
Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.

References

[R283], [R284], [R285], [R286]

Examples

>>> from sympy import I, oo, li

>>> from sympy.abc import z

Several special values are known:

>>> li(0)
0
>>> li(1)
-oo
>>> li(oo)
oo

5.10. Functions Module 527

SymPy Documentation, Release 1.3

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(li(z), z)
1/log(z)

Defining the li function via an integral:

The logarithmic integral can also be defined in terms of Ei:

>>> from sympy import Ei

>>> li(z).rewrite(Ei)
Ei(log(z))
>>> diff(li(z).rewrite(Ei), z)
1/log(z)

We can numerically evaluate the logarithmic integral to arbitrary precision on the whole
complex plane (except the singular points):

>>> li(2).evalf(30)
1.04516378011749278484458888919

>>> li(2*I).evalf(30)
1.0652795784357498247001125598 + 3.08346052231061726610939702133*I

We can even compute Soldner’s constant by the help of mpmath:

>>> from mpmath import findroot

>>> findroot(li, 2)
1.45136923488338

Further transformations include rewriting li in terms of the trigonometric integrals Si,

Ci, Shi and Chi:

>>> from sympy import Si, Ci, Shi, Chi

>>> li(z).rewrite(Si)
-log(I*log(z)) - log(1/log(z))/2 + log(log(z))/2 + Ci(I*log(z)) + Shi(log(z))
>>> li(z).rewrite(Ci)
-log(I*log(z)) - log(1/log(z))/2 + log(log(z))/2 + Ci(I*log(z)) + Shi(log(z))
>>> li(z).rewrite(Shi)
-log(1/log(z))/2 + log(log(z))/2 + Chi(log(z)) - Shi(log(z))
>>> li(z).rewrite(Chi)
-log(1/log(z))/2 + log(log(z))/2 + Chi(log(z)) - Shi(log(z))

class sympy.functions.special.error_functions.Li
The offset logarithmic integral.
For the use in SymPy, this function is defined as

Li(x) = li(x) − li(2)

See also:

li (page 527) Logarithmic integral.

Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.

528 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

E1 (page 526) Special case of the generalised exponential integral.

Si (page 529) Sine integral.
Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.

References

[R287], [R288], [R289]

Examples

>>> from sympy import I, oo, Li

>>> from sympy.abc import z

The following special value is known:

>>> Li(2)
0

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(Li(z), z)
1/log(z)

The shifted logarithmic integral can be written in terms of li(z):

>>> from sympy import li

>>> Li(z).rewrite(li)
li(z) - li(2)

We can numerically evaluate the logarithmic integral to arbitrary precision on the whole
complex plane (except the singular points):

>>> Li(2).evalf(30)
0

>>> Li(4).evalf(30)
1.92242131492155809316615998938

class sympy.functions.special.error_functions.Si
Sine integral.
This function is defined by
∫ z
sin t
Si(z) = dt.
0 t

It is an entire function.
See also:

5.10. Functions Module 529

SymPy Documentation, Release 1.3

Ci (page 530) Cosine integral.

Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.
Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.
sinc unnormalized sinc function
E1 (page 526) Special case of the generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.

References

[R290]

Examples

>>> from sympy import Si

>>> from sympy.abc import z

The sine integral is an antiderivative of sin(z)/z:

>>> Si(z).diff(z)
sin(z)/z

It is unbranched:
>>> from sympy import exp_polar, I, pi
>>> Si(z*exp_polar(2*I*pi))
Si(z)

Sine integral behaves much like ordinary sine under multiplication by I:

>>> Si(I*z)
I*Shi(z)
>>> Si(-z)
-Si(z)

It can also be expressed in terms of exponential integrals, but beware that the latter is
branched:
>>> from sympy import expint
>>> Si(z).rewrite(expint)
-I*(-expint(1, z*exp_polar(-I*pi/2))/2 +
expint(1, z*exp_polar(I*pi/2))/2) + pi/2

It can be rewritten in the form of sinc function (By definition)

>>> from sympy import sinc
>>> Si(z).rewrite(sinc)
Integral(sinc(t), (t, 0, z))

530 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.functions.special.error_functions.Ci
Cosine integral.
This function is defined for positive x by
∫ x ∫ ∞
cos t − 1 cos t
Ci(x) = γ + log x + dt = − dt,
0 t x t

where γ is the Euler-Mascheroni constant.

We have
( ) ( )
E1 eiπ/2 z + E1 e−iπ/2 z
Ci(z) = −
2
which holds for all polar z and thus provides an analytic continuation to the Riemann
surface of the logarithm.
The formula also holds as stated for z ∈ C with ℜ(z) > 0. By lifting to the principal branch
we obtain an analytic function on the cut complex plane.
See also:

Si (page 529) Sine integral.

Shi (page 532) Hyperbolic sine integral.
Chi (page 533) Hyperbolic cosine integral.
Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.
E1 (page 526) Special case of the generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.

References

[R291]

Examples

>>> from sympy import Ci

>>> from sympy.abc import z

The cosine integral is a primitive of cos(z)/z:

>>> Ci(z).diff(z)
cos(z)/z

It has a logarithmic branch point at the origin:

>>> from sympy import exp_polar, I, pi

>>> Ci(z*exp_polar(2*I*pi))
Ci(z) + 2*I*pi

5.10. Functions Module 531

SymPy Documentation, Release 1.3

The cosine integral behaves somewhat like ordinary cos under multiplication by i:

>>> from sympy import polar_lift

>>> Ci(polar_lift(I)*z)
Chi(z) + I*pi/2
>>> Ci(polar_lift(-1)*z)
Ci(z) + I*pi

It can also be expressed in terms of exponential integrals:

>>> from sympy import expint

>>> Ci(z).rewrite(expint)
-expint(1, z*exp_polar(-I*pi/2))/2 - expint(1, z*exp_polar(I*pi/2))/2

class sympy.functions.special.error_functions.Shi
Sinh integral.
This function is defined by
∫ z
sinh t
Shi(z) = dt.
0 t

It is an entire function.
See also:

Si (page 529) Sine integral.

Ci (page 530) Cosine integral.
Chi (page 533) Hyperbolic cosine integral.
Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.
E1 (page 526) Special case of the generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.

References

[R292]

Examples

>>> from sympy import Shi

>>> from sympy.abc import z

The Sinh integral is a primitive of sinh(z)/z:

>>> Shi(z).diff(z)
sinh(z)/z

It is unbranched:

532 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import exp_polar, I, pi

>>> Shi(z*exp_polar(2*I*pi))
Shi(z)

The sinh integral behaves much like ordinary sinh under multiplication by i:

>>> Shi(I*z)
I*Si(z)
>>> Shi(-z)
-Shi(z)

It can also be expressed in terms of exponential integrals, but beware that the latter is
branched:

>>> from sympy import expint

>>> Shi(z).rewrite(expint)
expint(1, z)/2 - expint(1, z*exp_polar(I*pi))/2 - I*pi/2

class sympy.functions.special.error_functions.Chi
Cosh integral.
This function is defined for positive x by
∫ x
cosh t − 1
Chi(x) = γ + log x + dt,
0 t

where γ is the Euler-Mascheroni constant.

We have
( ) π
Chi(z) = Ci eiπ/2 z − i ,
2
which holds for all polar z and thus provides an analytic continuation to the Riemann
surface of the logarithm. By lifting to the principal branch we obtain an analytic function
on the cut complex plane.
See also:

Si (page 529) Sine integral.

Ci (page 530) Cosine integral.
Shi (page 532) Hyperbolic sine integral.
Ei (page 523) Exponential integral.
expint (page 525) Generalised exponential integral.
E1 (page 526) Special case of the generalised exponential integral.
li (page 527) Logarithmic integral.
Li (page 528) Offset logarithmic integral.

References

[R293]

5.10. Functions Module 533

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Chi

>>> from sympy.abc import z

The cosh integral is a primitive of cosh(z)/z:

>>> Chi(z).diff(z)
cosh(z)/z

It has a logarithmic branch point at the origin:

>>> from sympy import exp_polar, I, pi

>>> Chi(z*exp_polar(2*I*pi))
Chi(z) + 2*I*pi

The cosh integral behaves somewhat like ordinary cosh under multiplication by i:

>>> from sympy import polar_lift

>>> Chi(polar_lift(I)*z)
Ci(z) + I*pi/2
>>> Chi(polar_lift(-1)*z)
Chi(z) + I*pi

It can also be expressed in terms of exponential integrals:

>>> from sympy import expint

>>> Chi(z).rewrite(expint)
-expint(1, z)/2 - expint(1, z*exp_polar(I*pi))/2 - I*pi/2

Bessel Type Functions

class sympy.functions.special.bessel.BesselBase
Abstract base class for bessel-type functions.
This class is meant to reduce code duplication. All Bessel type functions can 1) be differ-
entiated, and the derivatives expressed in terms of similar functions and 2) be rewritten
in terms of other bessel-type functions.
Here “bessel-type functions” are assumed to have one complex parameter.
To use this base class, define class attributes _a and _b such that 2*F_n' = -_a*F_{n+1}
+ b*F_{n-1}.
argument
The argument of the bessel-type function.
order
The order of the bessel-type function.
class sympy.functions.special.bessel.besselj
Bessel function of the first kind.
The Bessel J function of order ν is defined to be the function satisfying Bessel’s differ-
ential equation
2
d w dw
z2 2
+z + (z 2 − ν 2 )w = 0,
dz dz

534 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

with Laurent expansion

( )
ν 1 2
Jν (z) = z + O(z ) ,
Γ(ν + 1)2ν

if ν is not a negative integer. If ν = −n ∈ Z<0 is a negative integer, then the definition is

J−n (z) = (−1)n Jn (z).

See also:
bessely (page 535), besseli (page 536), besselk (page 536)

References

[R294], [R295], [R296], [R297]

Examples

Create a Bessel function object:

>>> from sympy import besselj, jn

>>> from sympy.abc import z, n
>>> b = besselj(n, z)

Differentiate it:

>>> b.diff(z)
besselj(n - 1, z)/2 - besselj(n + 1, z)/2

Rewrite in terms of spherical Bessel functions:

>>> b.rewrite(jn)
sqrt(2)*sqrt(z)*jn(n - 1/2, z)/sqrt(pi)

Access the parameter and argument:

>>> b.order
n
>>> b.argument
z

class sympy.functions.special.bessel.bessely
Bessel function of the second kind.
The Bessel Y function of order ν is defined as
Jµ (z) cos(πµ) − J−µ (z)
Yν (z) = lim ,
µ→ν sin(πµ)

where Jµ (z) is the Bessel function of the first kind.

It is a solution to Bessel’s equation, and linearly independent from Jν .
See also:
besselj (page 534), besseli (page 536), besselk (page 536)

5.10. Functions Module 535

SymPy Documentation, Release 1.3

References

[R298]

Examples

>>> from sympy import bessely, yn

>>> from sympy.abc import z, n
>>> b = bessely(n, z)
>>> b.diff(z)
bessely(n - 1, z)/2 - bessely(n + 1, z)/2
>>> b.rewrite(yn)
sqrt(2)*sqrt(z)*yn(n - 1/2, z)/sqrt(pi)

class sympy.functions.special.bessel.besseli
Modified Bessel function of the first kind.
The Bessel I function is a solution to the modified Bessel equation
2
d w dw
z2 +z + (z 2 + ν 2 )2 w = 0.
dz 2 dz
It can be defined as
Iν (z) = i−ν Jν (iz),
where Jν (z) is the Bessel function of the first kind.
See also:
besselj (page 534), bessely (page 535), besselk (page 536)

References

[R299]

Examples

>>> from sympy import besseli

>>> from sympy.abc import z, n
>>> besseli(n, z).diff(z)
besseli(n - 1, z)/2 + besseli(n + 1, z)/2

class sympy.functions.special.bessel.besselk
Modified Bessel function of the second kind.
The Bessel K function of order ν is defined as
π I−µ (z) − Iµ (z)
Kν (z) = lim ,
µ→ν 2 sin(πµ)
where Iµ (z) is the modified Bessel function of the first kind.
It is a solution of the modified Bessel equation, and linearly independent from Yν .
See also:
besselj (page 534), besseli (page 536), bessely (page 535)

536 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R300]

Examples

>>> from sympy import besselk

>>> from sympy.abc import z, n
>>> besselk(n, z).diff(z)
-besselk(n - 1, z)/2 - besselk(n + 1, z)/2

class sympy.functions.special.bessel.hankel1
Hankel function of the first kind.
This function is defined as

Hν(1) = Jν (z) + iYν (z),

where Jν (z) is the Bessel function of the first kind, and Yν (z) is the Bessel function of the
second kind.
It is a solution to Bessel’s equation.
See also:
hankel2 (page 537), besselj (page 534), bessely (page 535)

References

[R301]

Examples

>>> from sympy import hankel1

>>> from sympy.abc import z, n
>>> hankel1(n, z).diff(z)
hankel1(n - 1, z)/2 - hankel1(n + 1, z)/2

class sympy.functions.special.bessel.hankel2
Hankel function of the second kind.
This function is defined as

Hν(2) = Jν (z) − iYν (z),

where Jν (z) is the Bessel function of the first kind, and Yν (z) is the Bessel function of the
second kind.
(1)
It is a solution to Bessel’s equation, and linearly independent from Hν .
See also:
hankel1 (page 537), besselj (page 534), bessely (page 535)

5.10. Functions Module 537

SymPy Documentation, Release 1.3

References

[R302]

Examples

>>> from sympy import hankel2

>>> from sympy.abc import z, n
>>> hankel2(n, z).diff(z)
hankel2(n - 1, z)/2 - hankel2(n + 1, z)/2

class sympy.functions.special.bessel.jn
Spherical Bessel function of the first kind.
This function is a solution to the spherical Bessel equation
2
d w dw
z2 2
+ 2z + (z 2 − ν(ν + 1))w = 0.
dz dz
It can be defined as
√
π
jν (z) = J 1 (z),
2z ν+ 2
where Jν (z) is the Bessel function of the first kind.
The spherical Bessel functions of integral order are calculated using the formula:

jn (z) = fn (z) sin z + (−1)n+1 f−n−1 (z) cos z,

where the coefficients fn (z) are available as polys.orthopolys.

spherical_bessel_fn().
See also:
besselj (page 534), bessely (page 535), besselk (page 536), yn (page 539)

References

[R303]

Examples

>>> from sympy import Symbol, jn, sin, cos, expand_func, besselj, bessely
>>> from sympy import simplify
>>> z = Symbol(”z”)
>>> nu = Symbol(”nu”, integer=True)
>>> print(expand_func(jn(0, z)))
sin(z)/z
>>> expand_func(jn(1, z)) == sin(z)/z**2 - cos(z)/z
True
>>> expand_func(jn(3, z))
(-6/z**2 + 15/z**4)*sin(z) + (1/z - 15/z**3)*cos(z)
>>> jn(nu, z).rewrite(besselj)
(continues on next page)

538 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

sqrt(2)*sqrt(pi)*sqrt(1/z)*besselj(nu + 1/2, z)/2
>>> jn(nu, z).rewrite(bessely)
(-1)**nu*sqrt(2)*sqrt(pi)*sqrt(1/z)*bessely(-nu - 1/2, z)/2
>>> jn(2, 5.2+0.3j).evalf(20)
0.099419756723640344491 - 0.054525080242173562897*I

class sympy.functions.special.bessel.yn
Spherical Bessel function of the second kind.
This function is another solution to the spherical Bessel equation, and linearly indepen-
dent from jn . It can be defined as
√
π
yν (z) = Y 1 (z),
2z ν+ 2

where Yν (z) is the Bessel function of the second kind.

For integral orders n, yn is calculated using the formula:

yn (z) = (−1)n+1 j−n−1 (z)

See also:
besselj (page 534), bessely (page 535), besselk (page 536), jn (page 538)

References

[R304]

Examples

>>> from sympy import Symbol, yn, sin, cos, expand_func, besselj, bessely
>>> z = Symbol(”z”)
>>> nu = Symbol(”nu”, integer=True)
>>> print(expand_func(yn(0, z)))
-cos(z)/z
>>> expand_func(yn(1, z)) == -cos(z)/z**2-sin(z)/z
True
>>> yn(nu, z).rewrite(besselj)
(-1)**(nu + 1)*sqrt(2)*sqrt(pi)*sqrt(1/z)*besselj(-nu - 1/2, z)/2
>>> yn(nu, z).rewrite(bessely)
sqrt(2)*sqrt(pi)*sqrt(1/z)*bessely(nu + 1/2, z)/2
>>> yn(2, 5.2+0.3j).evalf(20)
0.18525034196069722536 + 0.014895573969924817587*I

sympy.functions.special.bessel.jn_zeros(n, k, method=’sympy’, dps=15)

Zeros of the spherical Bessel function of the first kind.
This returns an array of zeros of jn up to the k-th zero.
• method = “sympy”: uses mpmath.besseljzero()
• method = “scipy”: uses the SciPy’s sph_jn and newton to find all roots, which is
faster than computing the zeros using a general numerical solver, but it requires
SciPy and only works with low precision floating point numbers. [The function used

5.10. Functions Module 539

SymPy Documentation, Release 1.3

with method=”sympy” is a recent addition to mpmath, before that a general solver

was used.]
See also:
jn (page 538), yn (page 539), besselj (page 534), besselk (page 536), bessely
(page 535)

Examples

>>> from sympy import jn_zeros

>>> jn_zeros(2, 4, dps=5)
[5.7635, 9.095, 12.323, 15.515]

Airy Functions

class sympy.functions.special.bessel.AiryBase
Abstract base class for Airy functions.
This class is meant to reduce code duplication.
class sympy.functions.special.bessel.airyai
The Airy function Ai of the first kind.
The Airy function Ai(z) is defined to be the function satisfying Airy’s differential equation
2
d w(z)
− zw(z) = 0.
dz 2
Equivalently, for real z
∫ ∞ ( )
1 t3
Ai(z) := cos + zt dt.
π 0 3

See also:

airybi (page 541) Airy function of the second kind.

airyaiprime (page 543) Derivative of the Airy function of the first kind.
airybiprime (page 544) Derivative of the Airy function of the second kind.

References

[R305], [R306], [R307], [R308]

Examples

Create an Airy function object:

>>> from sympy import airyai

>>> from sympy.abc import z

540 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> airyai(z)
airyai(z)

Several special values are known:

>>> airyai(0)
3**(1/3)/(3*gamma(2/3))
>>> from sympy import oo
>>> airyai(oo)
0
>>> airyai(-oo)
0

The Airy function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(airyai(z))
airyai(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(airyai(z), z)
airyaiprime(z)
>>> diff(airyai(z), z, 2)
z*airyai(z)

Series expansion is also supported:

>>> from sympy import series

>>> series(airyai(z), z, 0, 3)
3**(5/6)*gamma(1/3)/(6*pi) - 3**(1/6)*z*gamma(2/3)/(2*pi) + O(z**3)

We can numerically evaluate the Airy function to arbitrary precision on the whole com-
plex plane:

>>> airyai(-2).evalf(50)
0.22740742820168557599192443603787379946077222541710

Rewrite Ai(z) in terms of hypergeometric functions:

>>> from sympy import hyper

>>> airyai(z).rewrite(hyper)
-3**(2/3)*z*hyper((), (4/3,), z**3/9)/(3*gamma(1/3)) + 3**(1/3)*hyper((), (2/3,),␣
,→z**3/9)/(3*gamma(2/3))

class sympy.functions.special.bessel.airybi
The Airy function Bi of the second kind.
The Airy function Bi(z) is defined to be the function satisfying Airy’s differential equation
2
d w(z)
− zw(z) = 0.
dz 2
Equivalently, for real z
∫ ∞ ( 3 ) ( 3 )
1 t t
Bi(z) := exp − + zt + sin + zt dt.
π 0 3 3

5.10. Functions Module 541

SymPy Documentation, Release 1.3

See also:

airyai (page 540) Airy function of the first kind.

airyaiprime (page 543) Derivative of the Airy function of the first kind.
airybiprime (page 544) Derivative of the Airy function of the second kind.

References

[R309], [R310], [R311], [R312]

Examples

Create an Airy function object:

>>> from sympy import airybi

>>> from sympy.abc import z

>>> airybi(z)
airybi(z)

Several special values are known:

>>> airybi(0)
3**(5/6)/(3*gamma(2/3))
>>> from sympy import oo
>>> airybi(oo)
oo
>>> airybi(-oo)
0

The Airy function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(airybi(z))
airybi(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(airybi(z), z)
airybiprime(z)
>>> diff(airybi(z), z, 2)
z*airybi(z)

Series expansion is also supported:

>>> from sympy import series

>>> series(airybi(z), z, 0, 3)
3**(1/3)*gamma(1/3)/(2*pi) + 3**(2/3)*z*gamma(2/3)/(2*pi) + O(z**3)

We can numerically evaluate the Airy function to arbitrary precision on the whole com-
plex plane:

542 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> airybi(-2).evalf(50)
-0.41230258795639848808323405461146104203453483447240

Rewrite Bi(z) in terms of hypergeometric functions:

>>> from sympy import hyper
>>> airybi(z).rewrite(hyper)
3**(1/6)*z*hyper((), (4/3,), z**3/9)/gamma(1/3) + 3**(5/6)*hyper((), (2/3,), z**3/
,→9)/(3*gamma(2/3))

class sympy.functions.special.bessel.airyaiprime
′
The derivative Ai of the Airy function of the first kind.
′
The Airy function Ai (z) is defined to be the function
′ d Ai(z)
Ai (z) := .
dz

See also:

airyai (page 540) Airy function of the first kind.

airybi (page 541) Airy function of the second kind.
airybiprime (page 544) Derivative of the Airy function of the second kind.

References

[R313], [R314], [R315], [R316]

Examples

Create an Airy function object:

>>> from sympy import airyaiprime
>>> from sympy.abc import z

>>> airyaiprime(z)
airyaiprime(z)

Several special values are known:

>>> airyaiprime(0)
-3**(2/3)/(3*gamma(1/3))
>>> from sympy import oo
>>> airyaiprime(oo)
0

The Airy function obeys the mirror symmetry:

>>> from sympy import conjugate
>>> conjugate(airyaiprime(z))
airyaiprime(conjugate(z))

Differentiation with respect to z is supported:

5.10. Functions Module 543

SymPy Documentation, Release 1.3

>>> from sympy import diff

>>> diff(airyaiprime(z), z)
z*airyai(z)
>>> diff(airyaiprime(z), z, 2)
z*airyaiprime(z) + airyai(z)

Series expansion is also supported:

>>> from sympy import series

>>> series(airyaiprime(z), z, 0, 3)
-3**(2/3)/(3*gamma(1/3)) + 3**(1/3)*z**2/(6*gamma(2/3)) + O(z**3)

We can numerically evaluate the Airy function to arbitrary precision on the whole com-
plex plane:

>>> airyaiprime(-2).evalf(50)
0.61825902074169104140626429133247528291577794512415

Rewrite Ai’(z) in terms of hypergeometric functions:

>>> from sympy import hyper

>>> airyaiprime(z).rewrite(hyper)
3**(1/3)*z**2*hyper((), (5/3,), z**3/9)/(6*gamma(2/3)) - 3**(2/3)*hyper((), (1/3,
,→), z**3/9)/(3*gamma(1/3))

class sympy.functions.special.bessel.airybiprime
′
The derivative Bi of the Airy function of the first kind.
′
The Airy function Bi (z) is defined to be the function

′ d Bi(z)
Bi (z) := .
dz

See also:

airyai (page 540) Airy function of the first kind.

airybi (page 541) Airy function of the second kind.
airyaiprime (page 543) Derivative of the Airy function of the first kind.

References

[R317], [R318], [R319], [R320]

Examples

Create an Airy function object:

>>> from sympy import airybiprime

>>> from sympy.abc import z

>>> airybiprime(z)
airybiprime(z)

544 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Several special values are known:

>>> airybiprime(0)
3**(1/6)/gamma(1/3)
>>> from sympy import oo
>>> airybiprime(oo)
oo
>>> airybiprime(-oo)
0

The Airy function obeys the mirror symmetry:

>>> from sympy import conjugate

>>> conjugate(airybiprime(z))
airybiprime(conjugate(z))

Differentiation with respect to z is supported:

>>> from sympy import diff

>>> diff(airybiprime(z), z)
z*airybi(z)
>>> diff(airybiprime(z), z, 2)
z*airybiprime(z) + airybi(z)

Series expansion is also supported:

>>> from sympy import series

>>> series(airybiprime(z), z, 0, 3)
3**(1/6)/gamma(1/3) + 3**(5/6)*z**2/(6*gamma(2/3)) + O(z**3)

We can numerically evaluate the Airy function to arbitrary precision on the whole com-
plex plane:

>>> airybiprime(-2).evalf(50)
0.27879516692116952268509756941098324140300059345163

Rewrite Bi’(z) in terms of hypergeometric functions:

>>> from sympy import hyper

>>> airybiprime(z).rewrite(hyper)
3**(5/6)*z**2*hyper((), (5/3,), z**3/9)/(6*gamma(2/3)) + 3**(1/6)*hyper((), (1/3,
,→), z**3/9)/gamma(1/3)

B-Splines

sympy.functions.special.bsplines.bspline_basis(d, knots, n, x)
The n-th B-spline at x of degree d with knots.
B-Splines are piecewise polynomials of degree d [R321]. They are defined on a set of
knots, which is a sequence of integers or floats.
The 0th degree splines have a value of one on a single interval:

>>> from sympy import bspline_basis

>>> from sympy.abc import x
>>> d = 0
(continues on next page)

5.10. Functions Module 545

SymPy Documentation, Release 1.3

(continued from previous page)

>>> knots = range(5)
>>> bspline_basis(d, knots, 0, x)
Piecewise((1, (x >= 0) & (x <= 1)), (0, True))

For a given (d, knots) there are len(knots)-d-1 B-splines defined, that are indexed
by n (starting at 0).
Here is an example of a cubic B-spline:

>>> bspline_basis(3, range(5), 0, x)

Piecewise((x**3/6, (x >= 0) & (x <= 1)),
(-x**3/2 + 2*x**2 - 2*x + 2/3,
(x >= 1) & (x <= 2)),
(x**3/2 - 4*x**2 + 10*x - 22/3,
(x >= 2) & (x <= 3)),
(-x**3/6 + 2*x**2 - 8*x + 32/3,
(x >= 3) & (x <= 4)),
(0, True))

By repeating knot points, you can introduce discontinuities in the B-splines and their
derivatives:

>>> d = 1
>>> knots = [0, 0, 2, 3, 4]
>>> bspline_basis(d, knots, 0, x)
Piecewise((-x/2 + 1, (x >= 0) & (x <= 2)), (0, True))

It is quite time consuming to construct and evaluate B-splines. If you need to evaluate a
B-splines many times, it is best to lambdify them first:

>>> from sympy import lambdify

>>> d = 3
>>> knots = range(10)
>>> b0 = bspline_basis(d, knots, 0, x)
>>> f = lambdify(x, b0)
>>> y = f(0.5)

See also:
bsplines_basis_set

References

[R321]
sympy.functions.special.bsplines.bspline_basis_set(d, knots, x)
Return the len(knots)-d-1 B-splines at x of degree d with knots.
This function returns a list of Piecewise polynomials that are the len(knots)-d-1 B-
splines of degree d for the given knots. This function calls bspline_basis(d, knots,
n, x) for different values of n.
See also:
bsplines_basis

546 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import bspline_basis_set

>>> from sympy.abc import x
>>> d = 2
>>> knots = range(5)
>>> splines = bspline_basis_set(d, knots, x)
>>> splines
[Piecewise((x**2/2, (x >= 0) & (x <= 1)),
(-x**2 + 3*x - 3/2, (x >= 1) & (x <= 2)),
(x**2/2 - 3*x + 9/2, (x >= 2) & (x <= 3)),
(0, True)),
Piecewise((x**2/2 - x + 1/2, (x >= 1) & (x <= 2)),
(-x**2 + 5*x - 11/2, (x >= 2) & (x <= 3)),
(x**2/2 - 4*x + 8, (x >= 3) & (x <= 4)),
(0, True))]

Riemann Zeta and Related Functions

class sympy.functions.special.zeta_functions.zeta
Hurwitz zeta function (or Riemann zeta function).
For Re(a) > 0 and Re(s) > 1, this function is defined as
∞
∑ 1
ζ(s, a) = ,
n=0
(n + a)s

where the standard choice of argument for n + a is used. For fixed a with Re(a) > 0 the
Hurwitz zeta function admits a meromorphic continuation to all of C, it is an unbranched
function with a simple pole at s = 1.
Analytic continuation to other a is possible under some circumstances, but this is not
typically done.
The Hurwitz zeta function is a special case of the Lerch transcendent:

ζ(s, a) = Φ(1, s, a).

This formula defines an analytic continuation for all possible values of s and a (also
Re(a) < 0), see the documentation of lerchphi (page 550) for a description of the branch-
ing behavior.
If no value is passed for a, by this function assumes a default value of a = 1, yielding the
Riemann zeta function.
See also:
dirichlet_eta (page 549), lerchphi (page 550), polylog (page 549)

References

[R322], [R323]

5.10. Functions Module 547

SymPy Documentation, Release 1.3

Examples

For a = 1 the Hurwitz zeta function reduces to the famous Riemann zeta function:
∑∞
1
ζ(s, 1) = ζ(s) = s
.
n=1
n

>>> from sympy import zeta

>>> from sympy.abc import s
>>> zeta(s, 1)
zeta(s)
>>> zeta(s)
zeta(s)

The Riemann zeta function can also be expressed using the Dirichlet eta function:

>>> from sympy import dirichlet_eta

>>> zeta(s).rewrite(dirichlet_eta)
dirichlet_eta(s)/(-2**(-s + 1) + 1)

The Riemann zeta function at positive even integer and negative odd integer values is
related to the Bernoulli numbers:

>>> zeta(2)
pi**2/6
>>> zeta(4)
pi**4/90
>>> zeta(-1)
-1/12

The specific formulae are:

B2n (2π)2n
ζ(2n) = (−1)n+1
2(2n)!

Bn+1
ζ(−n) = −
n+1
At negative even integers the Riemann zeta function is zero:

>>> zeta(-4)
0

No closed-form expressions are known at positive odd integers, but numerical evaluation
is possible:

>>> zeta(3).n()
1.20205690315959

The derivative of ζ(s, a) with respect to a is easily computed:

>>> from sympy.abc import a

>>> zeta(s, a).diff(a)
-s*zeta(s + 1, a)

However the derivative with respect to s has no useful closed form expression:

548 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> zeta(s, a).diff(s)

Derivative(zeta(s, a), s)

The Hurwitz zeta function can be expressed in terms of the Lerch transcendent, sympy.
functions.special.lerchphi:

>>> from sympy import lerchphi

>>> zeta(s, a).rewrite(lerchphi)
lerchphi(1, s, a)

class sympy.functions.special.zeta_functions.dirichlet_eta
Dirichlet eta function.
For Re(s) > 0, this function is defined as

∑∞
(−1)n
η(s) = .
n=1
ns

It admits a unique analytic continuation to all of C. It is an entire, unbranched function.

See also:
zeta (page 547)

References

[R324]

Examples

The Dirichlet eta function is closely related to the Riemann zeta function:

>>> from sympy import dirichlet_eta, zeta

>>> from sympy.abc import s
>>> dirichlet_eta(s).rewrite(zeta)
(-2**(-s + 1) + 1)*zeta(s)

class sympy.functions.special.zeta_functions.polylog
Polylogarithm function.
For |z| < 1 and s ∈ C, the polylogarithm is defined by

∑∞
zn
Lis (z) = ,
n=1
ns

where the standard branch of the argument is used for n. It admits an analytic continu-
ation which is branched at z = 1 (notably not on the sheet of initial definition), z = 0 and
z = ∞.
The name polylogarithm comes from the fact that for s = 1, the polylogarithm is related
to the ordinary logarithm (see examples), and that
∫ z
Lis (t)
Lis+1 (z) = dt.
0 t

5.10. Functions Module 549

SymPy Documentation, Release 1.3

The polylogarithm is a special case of the Lerch transcendent:

Lis (z) = zΦ(z, s, 1)

See also:
zeta (page 547), lerchphi (page 550)

Examples

For z ∈ {0, 1, −1}, the polylogarithm is automatically expressed using other functions:

>>> from sympy import polylog

>>> from sympy.abc import s
>>> polylog(s, 0)
0
>>> polylog(s, 1)
zeta(s)
>>> polylog(s, -1)
-dirichlet_eta(s)

If s is a negative integer, 0 or 1, the polylogarithm can be expressed using elementary

functions. This can be done using expand_func():

>>> from sympy import expand_func

>>> from sympy.abc import z
>>> expand_func(polylog(1, z))
-log(-z + 1)
>>> expand_func(polylog(0, z))
z/(-z + 1)

The derivative with respect to z can be computed in closed form:

>>> polylog(s, z).diff(z)

polylog(s - 1, z)/z

The polylogarithm can be expressed in terms of the lerch transcendent:

>>> from sympy import lerchphi

>>> polylog(s, z).rewrite(lerchphi)
z*lerchphi(z, s, 1)

class sympy.functions.special.zeta_functions.lerchphi
Lerch transcendent (Lerch phi function).
For Re(a) > 0, |z| < 1 and s ∈ C, the Lerch transcendent is defined as
∞
∑ zn
Φ(z, s, a) = ,
n=0
(n + a)s

where the standard branch of the argument is used for n+a, and by analytic continuation
for other values of the parameters.
A commonly used related function is the Lerch zeta function, defined by

L(q, s, a) = Φ(e2πiq , s, a).

550 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Analytic Continuation and Branching Behavior

It can be shown that

Φ(z, s, a) = zΦ(z, s, a + 1) + a−s .

This provides the analytic continuation to Re(a) ≤ 0.

Assume now Re(a) > 0. The integral representation
∫ ∞ s−1 −at
t e dt
Φ0 (z, s, a) =
0 1 − ze−t Γ(s)

provides an analytic continuation to C − [1, ∞). Finally, for x ∈ (1, ∞) we find

s−1
2πi log x
lim Φ0 (x + iϵ, s, a) − lim Φ0 (x − iϵ, s, a) = a
,
ϵ→0 + ϵ→0 + x Γ(s)

using the standard branch for both log x and log log x (a branch of log log x is needed to
evaluate log xs−1 ). This concludes the analytic continuation. The Lerch transcendent is
thus branched at z ∈ {0, 1, ∞} and a ∈ Z≤0 . For fixed z, a outside these branch points, it is
an entire function of s.
See also:
polylog (page 549), zeta (page 547)

References

[R325], [R326], [R327]

Examples

The Lerch transcendent is a fairly general function, for this reason it does not automat-
ically evaluate to simpler functions. Use expand_func() to achieve this.
If z = 1, the Lerch transcendent reduces to the Hurwitz zeta function:
>>> from sympy import lerchphi, expand_func
>>> from sympy.abc import z, s, a
>>> expand_func(lerchphi(1, s, a))
zeta(s, a)

More generally, if z is a root of unity, the Lerch transcendent reduces to a sum of Hurwitz
zeta functions:
>>> expand_func(lerchphi(-1, s, a))
2**(-s)*zeta(s, a/2) - 2**(-s)*zeta(s, a/2 + 1/2)

If a = 1, the Lerch transcendent reduces to the polylogarithm:

>>> expand_func(lerchphi(z, s, 1))
polylog(s, z)/z

More generally, if a is rational, the Lerch transcendent reduces to a sum of polyloga-

rithms:

5.10. Functions Module 551

SymPy Documentation, Release 1.3

>>> from sympy import S

>>> expand_func(lerchphi(z, s, S(1)/2))
2**(s - 1)*(polylog(s, sqrt(z))/sqrt(z) -
polylog(s, sqrt(z)*exp_polar(I*pi))/sqrt(z))
>>> expand_func(lerchphi(z, s, S(3)/2))
-2**s/z + 2**(s - 1)*(polylog(s, sqrt(z))/sqrt(z) -
polylog(s, sqrt(z)*exp_polar(I*pi))/sqrt(z))/z

The derivatives with respect to z and a can be computed in closed form:

>>> lerchphi(z, s, a).diff(z)

(-a*lerchphi(z, s, a) + lerchphi(z, s - 1, a))/z
>>> lerchphi(z, s, a).diff(a)
-s*lerchphi(z, s + 1, a)

class sympy.functions.special.zeta_functions.stieltjes
Represents Stieltjes constants, γk that occur in Laurent Series expansion of the Riemann
zeta function.

References

[R328]

Examples

>>> from sympy import stieltjes

>>> from sympy.abc import n, m
>>> stieltjes(n)
stieltjes(n)

zero’th stieltjes constant

>>> stieltjes(0)
EulerGamma
>>> stieltjes(0, 1)
EulerGamma

For generalized stieltjes constants

>>> stieltjes(n, m)
stieltjes(n, m)

Constants are only defined for integers >= 0

>>> stieltjes(-1)
zoo

Hypergeometric Functions

class sympy.functions.special.hyper.hyper
The (generalized) hypergeometric function is defined by a series where the ratios of

552 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

successive terms are a rational function of the summation index. When convergent, it is
continued analytically to the largest possible domain.
The hypergeometric function depends on two vectors of parameters, called the numer-
ator parameters ap , and the denominator parameters bq . It also has an argument z. The
series definition is
( ) ∑ ∞
a1 , · · · , ap (a1 )n · · · (ap )n z n
F z = ,
p q
b1 , · · · , b q (b1 )n · · · (bq )n n!
n=0

where (a)n = (a)(a + 1) · · · (a + n − 1) denotes the rising factorial.

If one of the bq is a non-positive integer then the series is undefined unless one of the
ap is a larger (i.e. smaller in magnitude) non-positive integer. If none of the bq is a non-
positive integer and one of the ap is a non-positive integer, then the series reduces to a
polynomial. To simplify the following discussion, we assume that none of the ap or bq is
a non-positive integer. For more details, see the references.
The series converges for all z if p ≤ q, and thus defines an entire single-valued function
in this case. If p = q + 1 the series converges for |z| < 1, and can be continued analytically
into a half-plane. If p > q + 1 the series is divergent for all z.
Note: The hypergeometric function constructor currently does not check if the parame-
ters actually yield a well-defined function.
See also:
sympy.simplify.hyperexpand (page 1207), sympy.functions.special.
gamma_functions.gamma (page 505), meijerg (page 555)

References

[R329], [R330]

Examples

The parameters ap and bq can be passed as arbitrary iterables, for example:

>>> from sympy.functions import hyper

>>> from sympy.abc import x, n, a
>>> hyper((1, 2, 3), [3, 4], x)
hyper((1, 2, 3), (3, 4), x)

There is also pretty printing (it looks better using unicode):

>>> from sympy import pprint

>>> pprint(hyper((1, 2, 3), [3, 4], x), use_unicode=False)
_
|_ /1, 2, 3 | \
| | | x|
3 2 \ 3, 4 | /

The parameters must always be iterables, even if they are vectors of length one or zero:

>>> hyper((1, ), [], x)

hyper((1,), (), x)

5.10. Functions Module 553

SymPy Documentation, Release 1.3

But of course they may be variables (but if they depend on x then you should not expect
much implemented functionality):
>>> hyper((n, a), (n**2,), x)
hyper((n, a), (n**2,), x)

The hypergeometric function generalizes many named special functions. The function
hyperexpand() tries to express a hypergeometric function using named special functions.
For example:
>>> from sympy import hyperexpand
>>> hyperexpand(hyper([], [], x))
exp(x)

You can also use expand_func:

>>> from sympy import expand_func
>>> expand_func(x*hyper([1, 1], [2], -x))
log(x + 1)

More examples:
>>> from sympy import S
>>> hyperexpand(hyper([], [S(1)/2], -x**2/4))
cos(x)
>>> hyperexpand(x*hyper([S(1)/2, S(1)/2], [S(3)/2], x**2))
asin(x)

We can also sometimes hyperexpand parametric functions:

>>> from sympy.abc import a
>>> hyperexpand(hyper([-a], [], x))
(-x + 1)**a

ap
Numerator parameters of the hypergeometric function.
argument
Argument of the hypergeometric function.
bq
Denominator parameters of the hypergeometric function.
convergence_statement
Return a condition on z under which the series converges.
eta
A quantity related to the convergence of the series.
radius_of_convergence
Compute the radius of convergence of the defining series.
Note that even if this is not oo, the function may still be evaluated outside of the
radius of convergence by analytic continuation. But if this is zero, then the function
is not actually defined anywhere else.
>>> from sympy.functions import hyper
>>> from sympy.abc import z
>>> hyper((1, 2), [3], z).radius_of_convergence
(continues on next page)

554 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

1
>>> hyper((1, 2, 3), [4], z).radius_of_convergence
0
>>> hyper((1, 2), (3, 4), z).radius_of_convergence
oo

class sympy.functions.special.hyper.meijerg
The Meijer G-function is defined by a Mellin-Barnes type integral that resembles an in-
verse Mellin transform. It generalizes the hypergeometric functions.
The Meijer G-function depends on four sets of parameters. There are “numerator pa-
rameters” a1 , . . . , an and an+1 , . . . , ap , and there are “denominator parameters” b1 , . . . , bm
and bm+1 , . . . , bq . Confusingly, it is traditionally denoted as follows (note the position of
m, n, p, q, and how they relate to the lengths of the four parameter vectors):
( )
m,n a1 , · · · , an an+1 , · · · , ap
Gp,q z .
b1 , · · · , bm bm+1 , · · · , bq

However, in sympy the four parameter vectors are always available separately (see ex-
amples), so that there is no need to keep track of the decorating sub- and super-scripts
on the G symbol.
The G function is defined as the following integral:
∫ ∏m ∏n
1 j=1 Γ(bj − s) j=1 Γ(1 − aj + s)
∏ ∏ z s ds,
2πi L qj=m+1 Γ(1 − bj + s) pj=n+1 Γ(aj − s)

where Γ(z) is the gamma function. There are three possible contours which we will not
describe in detail here (see the references). If the integral converges along more than
one of them the definitions agree. The contours all separate the poles of Γ(1 − aj + s) from
the poles of Γ(bk − s), so in particular the G function is undefined if aj − bk ∈ Z>0 for some
j ≤ n and k ≤ m.
The conditions under which one of the contours yields a convergent integral are compli-
cated and we do not state them here, see the references.
Note: Currently the Meijer G-function constructor does not check any convergence con-
ditions.
See also:
hyper (page 552), sympy.simplify.hyperexpand (page 1207)

References

[R331], [R332]

Examples

You can pass the parameters either as four separate vectors:

>>> from sympy.functions import meijerg

>>> from sympy.abc import x, a
>>> from sympy.core.containers import Tuple
(continues on next page)

5.10. Functions Module 555

SymPy Documentation, Release 1.3

(continued from previous page)

>>> from sympy import pprint
>>> pprint(meijerg((1, 2), (a, 4), (5,), [], x), use_unicode=False)
__1, 2 /1, 2 a, 4 | \
/__ | | x|
\_|4, 1 \ 5 | /

or as two nested vectors:

>>> pprint(meijerg([(1, 2), (3, 4)], ([5], Tuple()), x), use_unicode=False)
__1, 2 /1, 2 3, 4 | \
/__ | | x|
\_|4, 1 \ 5 | /

As with the hypergeometric function, the parameters may be passed as arbitrary iter-
ables. Vectors of length zero and one also have to be passed as iterables. The parameters
need not be constants, but if they depend on the argument then not much implemented
functionality should be expected.
All the subvectors of parameters are available:
>>> from sympy import pprint
>>> g = meijerg([1], [2], [3], [4], x)
>>> pprint(g, use_unicode=False)
__1, 1 /1 2 | \
/__ | | x|
\_|2, 2 \3 4 | /
>>> g.an
(1,)
>>> g.ap
(1, 2)
>>> g.aother
(2,)
>>> g.bm
(3,)
>>> g.bq
(3, 4)
>>> g.bother
(4,)

The Meijer G-function generalizes the hypergeometric functions. In some cases it can be
expressed in terms of hypergeometric functions, using Slater’s theorem. For example:
>>> from sympy import hyperexpand
>>> from sympy.abc import a, b, c
>>> hyperexpand(meijerg([a], [], [c], [b], x), allow_hyper=True)
x**c*gamma(-a + c + 1)*hyper((-a + c + 1,),
(-b + c + 1,), -x)/gamma(-b + c + 1)

Thus the Meijer G-function also subsumes many named functions as special cases. You
can use expand_func or hyperexpand to (try to) rewrite a Meijer G-function in terms of
named special functions. For example:
>>> from sympy import expand_func, S
>>> expand_func(meijerg([[],[]], [[0],[]], -x))
exp(x)
>>> hyperexpand(meijerg([[],[]], [[S(1)/2],[0]], (x/2)**2))
sin(x)/sqrt(pi)

556 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

an
First set of numerator parameters.
aother
Second set of numerator parameters.
ap
Combined numerator parameters.
argument
Argument of the Meijer G-function.
bm
First set of denominator parameters.
bother
Second set of denominator parameters.
bq
Combined denominator parameters.
delta
A quantity related to the convergence region of the integral, c.f. references.
get_period()
Return a number P such that G(x*exp(I*P)) == G(x).
>>> from sympy.functions.special.hyper import meijerg
>>> from sympy.abc import z
>>> from sympy import pi, S

>>> meijerg([1], [], [], [], z).get_period()

2*pi
>>> meijerg([pi], [], [], [], z).get_period()
oo
>>> meijerg([1, 2], [], [], [], z).get_period()
oo
>>> meijerg([1,1], [2], [1, S(1)/2, S(1)/3], [1], z).get_period()
12*pi

integrand(s)
Get the defining integrand D(s).
is_number
Returns true if expression has numeric data only.
nu
A quantity related to the convergence region of the integral, c.f. references.

Elliptic integrals

class sympy.functions.special.elliptic_integrals.elliptic_k
The complete elliptic integral of the first kind, defined by
( )
K(m) = F π2 m

where F (z|m) is the Legendre incomplete elliptic integral of the first kind.
The function K(m) is a single-valued function on the complex plane with branch cut along
the interval (1, ∞).

5.10. Functions Module 557

SymPy Documentation, Release 1.3

Note that our notation defines the incomplete elliptic integral in terms of the parameter
m instead of the elliptic modulus (eccentricity) k. In this case, the parameter m is defined
as m = k 2 .
See also:
elliptic_f (page 558)

References

[R333], [R334]

Examples

>>> from sympy import elliptic_k, I, pi

>>> from sympy.abc import m
>>> elliptic_k(0)
pi/2
>>> elliptic_k(1.0 + I)
1.50923695405127 + 0.625146415202697*I
>>> elliptic_k(m).series(n=3)
pi/2 + pi*m/8 + 9*pi*m**2/128 + O(m**3)

class sympy.functions.special.elliptic_integrals.elliptic_f
The Legendre incomplete elliptic integral of the first kind, defined by
∫ z
dt
F (z|m) = √
0 2
1 − m sin t

This function reduces to a complete elliptic integral of the first kind, K(m), when z = π/2.
Note that our notation defines the incomplete elliptic integral in terms of the parameter
m instead of the elliptic modulus (eccentricity) k. In this case, the parameter m is defined
as m = k 2 .
See also:
elliptic_k (page 557)

References

[R335], [R336]

Examples

>>> from sympy import elliptic_f, I, O

>>> from sympy.abc import z, m
>>> elliptic_f(z, m).series(z)
z + z**5*(3*m**2/40 - m/30) + m*z**3/6 + O(z**6)
>>> elliptic_f(3.0 + I/2, 1.0 + I)
2.909449841483 + 1.74720545502474*I

558 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.functions.special.elliptic_integrals.elliptic_e
Called with two arguments z and m, evaluates the incomplete elliptic integral of the
second kind, defined by
∫ z√
2
E (z|m) = 1 − m sin tdt
0

Called with a single argument m, evaluates the Legendre complete elliptic integral of
the second kind
(π )
E(m) = E 2 m

The function E(m) is a single-valued function on the complex plane with branch cut along
the interval (1, ∞).
Note that our notation defines the incomplete elliptic integral in terms of the parameter
m instead of the elliptic modulus (eccentricity) k. In this case, the parameter m is defined
as m = k 2 .

References

[R337], [R338], [R339]

Examples

>>> from sympy import elliptic_e, I, pi, O

>>> from sympy.abc import z, m
>>> elliptic_e(z, m).series(z)
z + z**5*(-m**2/40 + m/30) - m*z**3/6 + O(z**6)
>>> elliptic_e(m).series(n=4)
pi/2 - pi*m/8 - 3*pi*m**2/128 - 5*pi*m**3/512 + O(m**4)
>>> elliptic_e(1 + I, 2 - I/2).n()
1.55203744279187 + 0.290764986058437*I
>>> elliptic_e(0)
pi/2
>>> elliptic_e(2.0 - I)
0.991052601328069 + 0.81879421395609*I

class sympy.functions.special.elliptic_integrals.elliptic_pi
Called with three arguments n, z and m, evaluates the Legendre incomplete elliptic in-
tegral of the third kind, defined by
∫ z
dt
Π (n; z|m) = ( ) √
0 2 2
1 − n sin t 1 − m sin t

Called with two arguments n and m, evaluates the complete elliptic integral of the third
kind:
( )
Π (n|m) = Π n; π2 m

Note that our notation defines the incomplete elliptic integral in terms of the parameter
m instead of the elliptic modulus (eccentricity) k. In this case, the parameter m is defined
as m = k 2 .

5.10. Functions Module 559

SymPy Documentation, Release 1.3

References

[R340], [R341], [R342]

Examples

>>> from sympy import elliptic_pi, I, pi, O, S

>>> from sympy.abc import z, n, m
>>> elliptic_pi(n, z, m).series(z, n=4)
z + z**3*(m/6 + n/3) + O(z**4)
>>> elliptic_pi(0.5 + I, 1.0 - I, 1.2)
2.50232379629182 - 0.760939574180767*I
>>> elliptic_pi(0, 0)
pi/2
>>> elliptic_pi(1.0 - I/3, 2.0 + I)
3.29136443417283 + 0.32555634906645*I

Mathieu Functions

class sympy.functions.special.mathieu_functions.MathieuBase
Abstract base class for Mathieu functions.
This class is meant to reduce code duplication.
class sympy.functions.special.mathieu_functions.mathieus
The Mathieu Sine function S(a, q, z). This function is one solution of the Mathieu differ-
ential equation:

y(x)′′ + (a − 2q cos(2x))y(x) = 0

The other solution is the Mathieu Cosine function.

See also:

mathieuc (page 561) Mathieu cosine function.

mathieusprime (page 561) Derivative of Mathieu sine function.
mathieucprime (page 562) Derivative of Mathieu cosine function.

References

[R343], [R344], [R345], [R346]

Examples

>>> from sympy import diff, mathieus

>>> from sympy.abc import a, q, z

>>> mathieus(a, q, z)
mathieus(a, q, z)

560 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> mathieus(a, 0, z)
sin(sqrt(a)*z)

>>> diff(mathieus(a, q, z), z)

mathieusprime(a, q, z)

class sympy.functions.special.mathieu_functions.mathieuc
The Mathieu Cosine function C(a, q, z). This function is one solution of the Mathieu dif-
ferential equation:

y(x)′′ + (a − 2q cos(2x))y(x) = 0

The other solution is the Mathieu Sine function.

See also:

mathieus (page 560) Mathieu sine function

mathieusprime (page 561) Derivative of Mathieu sine function
mathieucprime (page 562) Derivative of Mathieu cosine function

References

[R347], [R348], [R349], [R350]

Examples

>>> from sympy import diff, mathieuc

>>> from sympy.abc import a, q, z

>>> mathieuc(a, q, z)
mathieuc(a, q, z)

>>> mathieuc(a, 0, z)
cos(sqrt(a)*z)

>>> diff(mathieuc(a, q, z), z)

mathieucprime(a, q, z)

class sympy.functions.special.mathieu_functions.mathieusprime
The derivative S ′ (a, q, z) of the Mathieu Sine function. This function is one solution of the
Mathieu differential equation:

y(x)′′ + (a − 2q cos(2x))y(x) = 0

The other solution is the Mathieu Cosine function.

See also:

mathieus (page 560) Mathieu sine function

mathieuc (page 561) Mathieu cosine function
mathieucprime (page 562) Derivative of Mathieu cosine function

5.10. Functions Module 561

SymPy Documentation, Release 1.3

References

[R351], [R352], [R353], [R354]

Examples

>>> from sympy import diff, mathieusprime

>>> from sympy.abc import a, q, z

>>> mathieusprime(a, q, z)
mathieusprime(a, q, z)

>>> mathieusprime(a, 0, z)
sqrt(a)*cos(sqrt(a)*z)

>>> diff(mathieusprime(a, q, z), z)

(-a + 2*q*cos(2*z))*mathieus(a, q, z)

class sympy.functions.special.mathieu_functions.mathieucprime
The derivative C ′ (a, q, z) of the Mathieu Cosine function. This function is one solution of
the Mathieu differential equation:

y(x)′′ + (a − 2q cos(2x))y(x) = 0

The other solution is the Mathieu Sine function.

See also:

mathieus (page 560) Mathieu sine function

mathieuc (page 561) Mathieu cosine function
mathieusprime (page 561) Derivative of Mathieu sine function

References

[R355], [R356], [R357], [R358]

Examples

>>> from sympy import diff, mathieucprime

>>> from sympy.abc import a, q, z

>>> mathieucprime(a, q, z)
mathieucprime(a, q, z)

>>> mathieucprime(a, 0, z)
-sqrt(a)*sin(sqrt(a)*z)

>>> diff(mathieucprime(a, q, z), z)

(-a + 2*q*cos(2*z))*mathieuc(a, q, z)

562 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Orthogonal Polynomials

This module mainly implements special orthogonal polynomials.

See also functions.combinatorial.numbers which contains some combinatorial polynomials.

Jacobi Polynomials

class sympy.functions.special.polynomials.jacobi
(α,β)
Jacobi polynomial Pn (x)
(α,β)
jacobi(n, alpha, beta, x) gives the nth Jacobi polynomial in x, Pn (x).
The Jacobi polynomials are orthogonal on [−1, 1] with respect to the weight
α β
(1 − x) (1 + x) .
See also:
gegenbauer (page 565), chebyshevt_root (page 568), chebyshevu (page 567), cheby-
shevu_root (page 568), legendre (page 569), assoc_legendre (page 569), her-
mite (page 570), laguerre (page 571), assoc_laguerre (page 572), sympy.polys.
orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.gegenbauer_poly
(page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899), sympy.polys.
orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.hermite_poly
(page 900), sympy.polys.orthopolys.legendre_poly (page 900), sympy.polys.
orthopolys.laguerre_poly (page 900)

References

[R359], [R360], [R361]

Examples

>>> from sympy import jacobi, S, conjugate, diff

>>> from sympy.abc import n,a,b,x

>>> jacobi(0, a, b, x)
1
>>> jacobi(1, a, b, x)
a/2 - b/2 + x*(a/2 + b/2 + 1)
>>> jacobi(2, a, b, x) # doctest:+SKIP
(a**2/8 - a*b/4 - a/8 + b**2/8 - b/8 + x**2*(a**2/8 + a*b/4 + 7*a/8 +
b**2/8 + 7*b/8 + 3/2) + x*(a**2/4 + 3*a/4 - b**2/4 - 3*b/4) - 1/2)

>>> jacobi(n, a, b, x)
jacobi(n, a, b, x)

>>> jacobi(n, a, a, x)
RisingFactorial(a + 1, n)*gegenbauer(n,
a + 1/2, x)/RisingFactorial(2*a + 1, n)

5.10. Functions Module 563

SymPy Documentation, Release 1.3

>>> jacobi(n, 0, 0, x)
legendre(n, x)

>>> jacobi(n, S(1)/2, S(1)/2, x)

RisingFactorial(3/2, n)*chebyshevu(n, x)/factorial(n + 1)

>>> jacobi(n, -S(1)/2, -S(1)/2, x)

RisingFactorial(1/2, n)*chebyshevt(n, x)/factorial(n)

>>> jacobi(n, a, b, -x)

(-1)**n*jacobi(n, b, a, x)

>>> jacobi(n, a, b, 0)
2**(-n)*gamma(a + n + 1)*hyper((-b - n, -n), (a + 1,), -1)/(factorial(n)*gamma(a␣
,→+ 1))

>>> jacobi(n, a, b, 1)
RisingFactorial(a + 1, n)/factorial(n)

>>> conjugate(jacobi(n, a, b, x))

jacobi(n, conjugate(a), conjugate(b), conjugate(x))

>>> diff(jacobi(n,a,b,x), x)
(a/2 + b/2 + n/2 + 1/2)*jacobi(n - 1, a + 1, b + 1, x)

sympy.functions.special.polynomials.jacobi_normalized(n, a, b, x)
(α,β)
Jacobi polynomial Pn (x)
(α,β)
jacobi_normalized(n, alpha, beta, x) gives the nth Jacobi polynomial in x, Pn (x).
The Jacobi polynomials are orthogonal on [−1, 1] with respect to the weight
α β
(1 − x) (1 + x) .
This functions returns the polynomials normilzed:
∫ 1
(α,β)
Pm (x)Pn(α,β) (x)(1 − x)α (1 + x)β dx = δm,n
−1

See also:
gegenbauer (page 565), chebyshevt_root (page 568), chebyshevu (page 567), cheby-
shevu_root (page 568), legendre (page 569), assoc_legendre (page 569), her-
mite (page 570), laguerre (page 571), assoc_laguerre (page 572), sympy.polys.
orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.gegenbauer_poly
(page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899), sympy.polys.
orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.hermite_poly
(page 900), sympy.polys.orthopolys.legendre_poly (page 900), sympy.polys.
orthopolys.laguerre_poly (page 900)

References

[R362], [R363], [R364]

564 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import jacobi_normalized

>>> from sympy.abc import n,a,b,x

>>> jacobi_normalized(n, a, b, x)
jacobi(n, a, b, x)/sqrt(2**(a + b + 1)*gamma(a + n + 1)*gamma(b + n + 1)/((a + b␣
,→+ 2*n + 1)*factorial(n)*gamma(a + b + n + 1)))

Gegenbauer Polynomials

class sympy.functions.special.polynomials.gegenbauer
(α)
Gegenbauer polynomial Cn (x)
(α)
gegenbauer(n, alpha, x) gives the nth Gegenbauer polynomial in x, Cn (x).
The Gegenbauer polynomials are orthogonal on [−1, 1] with respect to the weight
( )α− 21
1 − x2 .
See also:
jacobi (page 563), chebyshevt_root (page 568), chebyshevu (page 567), cheby-
shevu_root (page 568), legendre (page 569), assoc_legendre (page 569), her-
mite (page 570), laguerre (page 571), assoc_laguerre (page 572), sympy.polys.
orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.gegenbauer_poly
(page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899), sympy.polys.
orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.hermite_poly
(page 900), sympy.polys.orthopolys.legendre_poly (page 900), sympy.polys.
orthopolys.laguerre_poly (page 900)

References

[R365], [R366], [R367]

Examples

>>> from sympy import gegenbauer, conjugate, diff

>>> from sympy.abc import n,a,x
>>> gegenbauer(0, a, x)
1
>>> gegenbauer(1, a, x)
2*a*x
>>> gegenbauer(2, a, x)
-a + x**2*(2*a**2 + 2*a)
>>> gegenbauer(3, a, x)
x**3*(4*a**3/3 + 4*a**2 + 8*a/3) + x*(-2*a**2 - 2*a)

>>> gegenbauer(n, a, x)
gegenbauer(n, a, x)
>>> gegenbauer(n, a, -x)
(-1)**n*gegenbauer(n, a, x)

5.10. Functions Module 565

SymPy Documentation, Release 1.3

>>> gegenbauer(n, a, 0)
2**n*sqrt(pi)*gamma(a + n/2)/(gamma(a)*gamma(-n/2 + 1/2)*gamma(n + 1))
>>> gegenbauer(n, a, 1)
gamma(2*a + n)/(gamma(2*a)*gamma(n + 1))

>>> conjugate(gegenbauer(n, a, x))

gegenbauer(n, conjugate(a), conjugate(x))

>>> diff(gegenbauer(n, a, x), x)

2*a*gegenbauer(n - 1, a + 1, x)

Chebyshev Polynomials

class sympy.functions.special.polynomials.chebyshevt
Chebyshev polynomial of the first kind, Tn (x)
chebyshevt(n, x) gives the nth Chebyshev polynomial (of the first kind) in x, Tn (x).
The Chebyshev polynomials of the first kind are orthogonal on [−1, 1] with respect to the
1
weight √1−x 2
.

See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt_root (page 568), chebyshevu
(page 567), chebyshevu_root (page 568), legendre (page 569), assoc_legendre
(page 569), hermite (page 570), laguerre (page 571), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

References

[R368], [R369], [R370], [R371], [R372]

Examples

>>> from sympy import chebyshevt, chebyshevu, diff

>>> from sympy.abc import n,x
>>> chebyshevt(0, x)
1
>>> chebyshevt(1, x)
x
>>> chebyshevt(2, x)
2*x**2 - 1

>>> chebyshevt(n, x)
chebyshevt(n, x)
>>> chebyshevt(n, -x)
(-1)**n*chebyshevt(n, x)
(continues on next page)

566 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> chebyshevt(-n, x)
chebyshevt(n, x)

>>> chebyshevt(n, 0)
cos(pi*n/2)
>>> chebyshevt(n, -1)
(-1)**n

>>> diff(chebyshevt(n, x), x)

n*chebyshevu(n - 1, x)

class sympy.functions.special.polynomials.chebyshevu
Chebyshev polynomial of the second kind, Un (x)
chebyshevu(n, x) gives the nth Chebyshev polynomial of the second kind in x, Un (x).
The Chebyshev
√ polynomials of the second kind are orthogonal on [−1, 1] with respect to
the weight 1 − x2 .
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu_root (page 568), legendre (page 569), assoc_legendre
(page 569), hermite (page 570), laguerre (page 571), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

References

[R373], [R374], [R375], [R376], [R377]

Examples

>>> from sympy import chebyshevt, chebyshevu, diff

>>> from sympy.abc import n,x
>>> chebyshevu(0, x)
1
>>> chebyshevu(1, x)
2*x
>>> chebyshevu(2, x)
4*x**2 - 1

>>> chebyshevu(n, x)
chebyshevu(n, x)
>>> chebyshevu(n, -x)
(-1)**n*chebyshevu(n, x)
>>> chebyshevu(-n, x)
-chebyshevu(n - 2, x)

5.10. Functions Module 567

SymPy Documentation, Release 1.3

>>> chebyshevu(n, 0)
cos(pi*n/2)
>>> chebyshevu(n, 1)
n + 1

>>> diff(chebyshevu(n, x), x)

(-x*chebyshevu(n, x) + (n + 1)*chebyshevt(n + 1, x))/(x**2 - 1)

class sympy.functions.special.polynomials.chebyshevt_root
chebyshev_root(n, k) returns the kth root (indexed from zero) of the nth Chebyshev poly-
nomial of the first kind; that is, if 0 <= k < n, chebyshevt(n, chebyshevt_root(n, k)) ==
0.
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevu
(page 567), chebyshevu_root (page 568), legendre (page 569), assoc_legendre
(page 569), hermite (page 570), laguerre (page 571), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

Examples

>>> from sympy import chebyshevt, chebyshevt_root

>>> chebyshevt_root(3, 2)
-sqrt(3)/2
>>> chebyshevt(3, chebyshevt_root(3, 2))
0

class sympy.functions.special.polynomials.chebyshevu_root
chebyshevu_root(n, k) returns the kth root (indexed from zero) of the nth Chebyshev
polynomial of the second kind; that is, if 0 <= k < n, chebyshevu(n, chebyshevu_root(n,
k)) == 0.
See also:
chebyshevt (page 566), chebyshevt_root (page 568), chebyshevu (page 567), legen-
dre (page 569), assoc_legendre (page 569), hermite (page 570), laguerre (page 571),
assoc_laguerre (page 572), sympy.polys.orthopolys.jacobi_poly (page 900),
sympy.polys.orthopolys.gegenbauer_poly (page 899), sympy.polys.orthopolys.
chebyshevt_poly (page 899), sympy.polys.orthopolys.chebyshevu_poly (page 899),
sympy.polys.orthopolys.hermite_poly (page 900), sympy.polys.orthopolys.
legendre_poly (page 900), sympy.polys.orthopolys.laguerre_poly (page 900)

Examples

>>> from sympy import chebyshevu, chebyshevu_root

>>> chebyshevu_root(3, 2)
-sqrt(2)/2
(continues on next page)

568 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> chebyshevu(3, chebyshevu_root(3, 2))
0

Legendre Polynomials

class sympy.functions.special.polynomials.legendre
legendre(n, x) gives the nth Legendre polynomial of x, Pn (x)
The Legendre polynomials are orthogonal on [-1, 1] with respect to the constant weight
1. They satisfy Pn (1) = 1 for all n; further, Pn is odd for odd n and even for even n.
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu (page 567), chebyshevu_root (page 568), assoc_legendre
(page 569), hermite (page 570), laguerre (page 571), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

References

[R378], [R379], [R380], [R381]

Examples

>>> from sympy import legendre, diff

>>> from sympy.abc import x, n
>>> legendre(0, x)
1
>>> legendre(1, x)
x
>>> legendre(2, x)
3*x**2/2 - 1/2
>>> legendre(n, x)
legendre(n, x)
>>> diff(legendre(n,x), x)
n*(x*legendre(n, x) - legendre(n - 1, x))/(x**2 - 1)

class sympy.functions.special.polynomials.assoc_legendre
assoc_legendre(n,m, x) gives Pnm (x), where n and m are the degree and order or an ex-
pression which is related to the nth order Legendre polynomial, Pn (x) in the following
manner:
m
m d Pn (x)
Pnm (x) = (−1)m (1 − x2 ) 2
dxm
Associated Legendre polynomial are orthogonal on [-1, 1] with:
• weight = 1 for the same m, and different n.

5.10. Functions Module 569

SymPy Documentation, Release 1.3

• weight = 1/(1-x**2) for the same n, and different m.

See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu (page 567), chebyshevu_root (page 568), legendre (page 569),
hermite (page 570), laguerre (page 571), assoc_laguerre (page 572), sympy.polys.
orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.gegenbauer_poly
(page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899), sympy.polys.
orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.hermite_poly
(page 900), sympy.polys.orthopolys.legendre_poly (page 900), sympy.polys.
orthopolys.laguerre_poly (page 900)

References

[R382], [R383], [R384], [R385]

Examples

>>> from sympy import assoc_legendre

>>> from sympy.abc import x, m, n
>>> assoc_legendre(0,0, x)
1
>>> assoc_legendre(1,0, x)
x
>>> assoc_legendre(1,1, x)
-sqrt(-x**2 + 1)
>>> assoc_legendre(n,m,x)
assoc_legendre(n, m, x)

Hermite Polynomials

class sympy.functions.special.polynomials.hermite
hermite(n, x) gives the nth Hermite polynomial in x, Hn (x)
( )
The Hermite polynomials are orthogonal on (−∞, ∞) with respect to the weight exp −x2 .
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu (page 567), chebyshevu_root (page 568), legendre (page 569),
assoc_legendre (page 569), laguerre (page 571), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

References

[R386], [R387], [R388]

570 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import hermite, diff

>>> from sympy.abc import x, n
>>> hermite(0, x)
1
>>> hermite(1, x)
2*x
>>> hermite(2, x)
4*x**2 - 2
>>> hermite(n, x)
hermite(n, x)
>>> diff(hermite(n,x), x)
2*n*hermite(n - 1, x)
>>> hermite(n, -x)
(-1)**n*hermite(n, x)

Laguerre Polynomials

class sympy.functions.special.polynomials.laguerre
Returns the nth Laguerre polynomial in x, Ln (x).
Parameters n : int
Degree of Laguerre polynomial. Must be n >= 0.
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu (page 567), chebyshevu_root (page 568), legendre (page 569),
assoc_legendre (page 569), hermite (page 570), assoc_laguerre (page 572),
sympy.polys.orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.
gegenbauer_poly (page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899),
sympy.polys.orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.
hermite_poly (page 900), sympy.polys.orthopolys.legendre_poly (page 900),
sympy.polys.orthopolys.laguerre_poly (page 900)

References

[R389], [R390], [R391], [R392]

Examples

>>> from sympy import laguerre, diff

>>> from sympy.abc import x, n
>>> laguerre(0, x)
1
>>> laguerre(1, x)
-x + 1
>>> laguerre(2, x)
x**2/2 - 2*x + 1
>>> laguerre(3, x)
-x**3/6 + 3*x**2/2 - 3*x + 1

5.10. Functions Module 571

SymPy Documentation, Release 1.3

>>> laguerre(n, x)
laguerre(n, x)

>>> diff(laguerre(n, x), x)

-assoc_laguerre(n - 1, 1, x)

class sympy.functions.special.polynomials.assoc_laguerre
Returns the nth generalized Laguerre polynomial in x, Ln (x).
Parameters n : int
Degree of Laguerre polynomial. Must be n >= 0.
alpha : Expr
Arbitrary expression. For alpha=0 regular Laguerre polynomials will
be generated.
See also:
jacobi (page 563), gegenbauer (page 565), chebyshevt (page 566), chebyshevt_root
(page 568), chebyshevu (page 567), chebyshevu_root (page 568), legendre (page 569),
assoc_legendre (page 569), hermite (page 570), laguerre (page 571), sympy.polys.
orthopolys.jacobi_poly (page 900), sympy.polys.orthopolys.gegenbauer_poly
(page 899), sympy.polys.orthopolys.chebyshevt_poly (page 899), sympy.polys.
orthopolys.chebyshevu_poly (page 899), sympy.polys.orthopolys.hermite_poly
(page 900), sympy.polys.orthopolys.legendre_poly (page 900), sympy.polys.
orthopolys.laguerre_poly (page 900)

References

[R393], [R394], [R395], [R396]

Examples

>>> from sympy import laguerre, assoc_laguerre, diff

>>> from sympy.abc import x, n, a
>>> assoc_laguerre(0, a, x)
1
>>> assoc_laguerre(1, a, x)
a - x + 1
>>> assoc_laguerre(2, a, x)
a**2/2 + 3*a/2 + x**2/2 + x*(-a - 2) + 1
>>> assoc_laguerre(3, a, x)
a**3/6 + a**2 + 11*a/6 - x**3/6 + x**2*(a/2 + 3/2) +
x*(-a**2/2 - 5*a/2 - 3) + 1

>>> assoc_laguerre(n, a, 0)
binomial(a + n, a)

>>> assoc_laguerre(n, a, x)
assoc_laguerre(n, a, x)

572 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> assoc_laguerre(n, 0, x)
laguerre(n, x)

>>> diff(assoc_laguerre(n, a, x), x)

-assoc_laguerre(n - 1, a + 1, x)

>>> diff(assoc_laguerre(n, a, x), a)

Sum(assoc_laguerre(_k, a, x)/(-a + n), (_k, 0, n - 1))

Spherical Harmonics

class sympy.functions.special.spherical_harmonics.Ynm
Spherical harmonics defined as
√
m (2n + 1)(n − m)! m
Yn (θ, φ) := exp(imφ)Pn (cos(θ))
4π(n + m)!

Ynm() gives the spherical harmonic function of order n and m in θ and φ, Ynm (θ, φ). The
four parameters are as follows: n ≥ 0 an integer and m an integer such that −n ≤ m ≤ n
holds. The two angles are real-valued with θ ∈ [0, π] and φ ∈ [0, 2π].
See also:
Ynm_c (page 575), Znm (page 575)

References

[R397], [R398], [R399], [R400]

Examples

>>> from sympy import Ynm, Symbol

>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> Ynm(n, m, theta, phi)

Ynm(n, m, theta, phi)

Several symmetries are known, for the order

>>> from sympy import Ynm, Symbol

>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> Ynm(n, -m, theta, phi)

(-1)**m*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

as well as for the angles

5.10. Functions Module 573

SymPy Documentation, Release 1.3

>>> from sympy import Ynm, Symbol, simplify

>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> Ynm(n, m, -theta, phi)

Ynm(n, m, theta, phi)

>>> Ynm(n, m, theta, -phi)

exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

For specific integers n and m we can evaluate the harmonics to more useful expressions
>>> simplify(Ynm(0, 0, theta, phi).expand(func=True))
1/(2*sqrt(pi))

>>> simplify(Ynm(1, -1, theta, phi).expand(func=True))

sqrt(6)*exp(-I*phi)*sin(theta)/(4*sqrt(pi))

>>> simplify(Ynm(1, 0, theta, phi).expand(func=True))

sqrt(3)*cos(theta)/(2*sqrt(pi))

>>> simplify(Ynm(1, 1, theta, phi).expand(func=True))

-sqrt(6)*exp(I*phi)*sin(theta)/(4*sqrt(pi))

>>> simplify(Ynm(2, -2, theta, phi).expand(func=True))

sqrt(30)*exp(-2*I*phi)*sin(theta)**2/(8*sqrt(pi))

>>> simplify(Ynm(2, -1, theta, phi).expand(func=True))

sqrt(30)*exp(-I*phi)*sin(2*theta)/(8*sqrt(pi))

>>> simplify(Ynm(2, 0, theta, phi).expand(func=True))

sqrt(5)*(3*cos(theta)**2 - 1)/(4*sqrt(pi))

>>> simplify(Ynm(2, 1, theta, phi).expand(func=True))

-sqrt(30)*exp(I*phi)*sin(2*theta)/(8*sqrt(pi))

>>> simplify(Ynm(2, 2, theta, phi).expand(func=True))

sqrt(30)*exp(2*I*phi)*sin(theta)**2/(8*sqrt(pi))

We can differentiate the functions with respect to both angles

>>> from sympy import Ynm, Symbol, diff
>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> diff(Ynm(n, m, theta, phi), theta)

m*cot(theta)*Ynm(n, m, theta, phi) + sqrt((-m + n)*(m + n + 1))*exp(-I*phi)*Ynm(n,
,→ m + 1, theta, phi)

>>> diff(Ynm(n, m, theta, phi), phi)

I*m*Ynm(n, m, theta, phi)

574 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Further we can compute the complex conjugation

>>> from sympy import Ynm, Symbol, conjugate
>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> conjugate(Ynm(n, m, theta, phi))

(-1)**(2*m)*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

To get back the well known expressions in spherical coordinates we use full expansion
>>> from sympy import Ynm, Symbol, expand_func
>>> from sympy.abc import n,m
>>> theta = Symbol(”theta”)
>>> phi = Symbol(”phi”)

>>> expand_func(Ynm(n, m, theta, phi))

sqrt((2*n + 1)*factorial(-m + n)/factorial(m + n))*exp(I*m*phi)*assoc_legendre(n,␣
,→m, cos(theta))/(2*sqrt(pi))

sympy.functions.special.spherical_harmonics.Ynm_c(n, m, theta, phi)

Conjugate spherical harmonics defined as

Ynm (θ, φ) := (−1)m Yn−m (θ, φ)

See also:
Ynm (page 573), Znm (page 575)

References

[R401], [R402], [R403]

class sympy.functions.special.spherical_harmonics.Znm
Real spherical harmonics defined as
 m


Yn (θ,φ)+Ynm (θ,φ)
√ m>0
 2
Znm (θ, φ) := Ynm (θ, φ) m=0


 Ynm (θ,φ)−Y
√ n
m (θ,φ)
m<0
i 2

which gives in simplified form

 m
 Yn (θ,φ)+(−1)m Yn−m (θ,φ)

 √
2
m>0
m m
Zn (θ, φ) = Yn (θ, φ) m=0


 Ynm (θ,φ)−(−1)
√
m −m
Yn (θ,φ)
m<0
i 2

See also:
Ynm (page 573), Ynm_c (page 575)

References

[R404], [R405], [R406]

5.10. Functions Module 575

SymPy Documentation, Release 1.3

Tensor Functions

sympy.functions.special.tensor_functions.Eijk(*args, **kwargs)
Represent the Levi-Civita symbol.
This is just compatibility wrapper to LeviCivita().
See also:
LeviCivita (page 576)
sympy.functions.special.tensor_functions.eval_levicivita(*args)
Evaluate Levi-Civita symbol.
class sympy.functions.special.tensor_functions.LeviCivita
Represent the Levi-Civita symbol.
For even permutations of indices it returns 1, for odd permutations -1, and for everything
else (a repeated index) it returns 0.
Thus it represents an alternating pseudotensor.
See also:
Eijk (page 576)

Examples

>>> from sympy import LeviCivita

>>> from sympy.abc import i, j, k
>>> LeviCivita(1, 2, 3)
1
>>> LeviCivita(1, 3, 2)
-1
>>> LeviCivita(1, 2, 2)
0
>>> LeviCivita(i, j, k)
LeviCivita(i, j, k)
>>> LeviCivita(i, j, i)
0

class sympy.functions.special.tensor_functions.KroneckerDelta
The discrete, or Kronecker, delta function.
A function that takes in two integers i and j. It returns 0 if i and j are not equal or it
returns 1 if i and j are equal.
Parameters i : Number, Symbol
The first index of the delta function.
j : Number, Symbol
The second index of the delta function.
See also:
eval (page 577), sympy.functions.special.delta_functions.DiracDelta (page 498)

576 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R407]

Examples

A simple example with integer indices:

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> KroneckerDelta(1, 2)
0
>>> KroneckerDelta(3, 3)
1

Symbolic indices:

>>> from sympy.abc import i, j, k

>>> KroneckerDelta(i, j)
KroneckerDelta(i, j)
>>> KroneckerDelta(i, i)
1
>>> KroneckerDelta(i, i + 1)
0
>>> KroneckerDelta(i, i + 1 + k)
KroneckerDelta(i, i + k + 1)

classmethod eval(i, j)
Evaluates the discrete delta function.

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy.abc import i, j, k

>>> KroneckerDelta(i, j)
KroneckerDelta(i, j)
>>> KroneckerDelta(i, i)
1
>>> KroneckerDelta(i, i + 1)
0
>>> KroneckerDelta(i, i + 1 + k)
KroneckerDelta(i, i + k + 1)

# indirect doctest
indices_contain_equal_information
Returns True if indices are either both above or below fermi.

Examples

5.10. Functions Module 577

SymPy Documentation, Release 1.3

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, q).indices_contain_equal_information
True
>>> KroneckerDelta(p, q+1).indices_contain_equal_information
True
>>> KroneckerDelta(i, p).indices_contain_equal_information
False

is_above_fermi
True if Delta can be non-zero above fermi
See also:
is_below_fermi (page 578), is_only_below_fermi (page 579),
is_only_above_fermi (page 579)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_above_fermi
True
>>> KroneckerDelta(p, i).is_above_fermi
False
>>> KroneckerDelta(p, q).is_above_fermi
True

is_below_fermi
True if Delta can be non-zero below fermi
See also:
is_above_fermi (page 578), is_only_above_fermi (page 579),
is_only_below_fermi (page 579)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_below_fermi
False
>>> KroneckerDelta(p, i).is_below_fermi
(continues on next page)

578 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

True
>>> KroneckerDelta(p, q).is_below_fermi
True

is_only_above_fermi
True if Delta is restricted to above fermi
See also:
is_above_fermi (page 578), is_below_fermi (page 578), is_only_below_fermi
(page 579)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_only_above_fermi
True
>>> KroneckerDelta(p, q).is_only_above_fermi
False
>>> KroneckerDelta(p, i).is_only_above_fermi
False

is_only_below_fermi
True if Delta is restricted to below fermi
See also:
is_above_fermi (page 578), is_below_fermi (page 578), is_only_above_fermi
(page 579)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, i).is_only_below_fermi
True
>>> KroneckerDelta(p, q).is_only_below_fermi
False
>>> KroneckerDelta(p, a).is_only_below_fermi
False

killable_index
Returns the index which is preferred to substitute in the final expression.
The index to substitute is the index with less information regarding fermi level. If
indices contain same information, ‘a’ is preferred before ‘b’.

5.10. Functions Module 579

SymPy Documentation, Release 1.3

See also:
preferred_index (page 580)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> j = Symbol('j', below_fermi=True)
>>> p = Symbol('p')
>>> KroneckerDelta(p, i).killable_index
p
>>> KroneckerDelta(p, a).killable_index
p
>>> KroneckerDelta(i, j).killable_index
j

preferred_index
Returns the index which is preferred to keep in the final expression.
The preferred index is the index with more information regarding fermi level. If
indices contain same information, ‘a’ is preferred before ‘b’.
See also:
killable_index (page 579)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> j = Symbol('j', below_fermi=True)
>>> p = Symbol('p')
>>> KroneckerDelta(p, i).preferred_index
i
>>> KroneckerDelta(p, a).preferred_index
a
>>> KroneckerDelta(i, j).preferred_index
i

5.11 Geometry Module

5.11.1 Introduction

The geometry module for SymPy allows one to create two-dimensional geometrical entities,
such as lines and circles, and query for information about these entities. This could include
asking the area of an ellipse, checking for collinearity of a set of points, or finding the intersec-
tion between two lines. The primary use case of the module involves entities with numerical
values, but it is possible to also use symbolic representations.

580 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.11.2 Available Entities

The following entities are currently available in the geometry module:

• Point (page 590)
• Line (page 612), Segment (page 617), Ray (page 615)
• Ellipse (page 635), Circle (page 647)
• Polygon (page 650), RegularPolygon (page 657), Triangle (page 665)
Most of the work one will do will be through the properties and methods of these entities, but
several global methods exist:
• intersection(entity1, entity2)
• are_similar(entity1, entity2)
• convex_hull(points)
For a full API listing and an explanation of the methods and their return values please see the
list of classes at the end of this document.

5.11.3 Example Usage

The following Python session gives one an idea of how to work with some of the geometry
module.

>>> from sympy import *

>>> from sympy.geometry import *
>>> x = Point(0, 0)
>>> y = Point(1, 1)
>>> z = Point(2, 2)
>>> zp = Point(1, 0)
>>> Point.is_collinear(x, y, z)
True
>>> Point.is_collinear(x, y, zp)
False
>>> t = Triangle(zp, y, x)
>>> t.area
1/2
>>> t.medians[x]
Segment2D(Point2D(0, 0), Point2D(1, 1/2))
>>> m = t.medians
>>> intersection(m[x], m[y], m[zp])
[Point2D(2/3, 1/3)]
>>> c = Circle(x, 5)
>>> l = Line(Point(5, -5), Point(5, 5))
>>> c.is_tangent(l) # is l tangent to c?
True
>>> l = Line(x, y)
>>> c.is_tangent(l) # is l tangent to c?
False
>>> intersection(c, l)
[Point2D(-5*sqrt(2)/2, -5*sqrt(2)/2), Point2D(5*sqrt(2)/2, 5*sqrt(2)/2)]

5.11. Geometry Module 581

SymPy Documentation, Release 1.3

5.11.4 Intersection of medians

>>> from sympy import symbols

>>> from sympy.geometry import Point, Triangle, intersection

>>> a, b = symbols(”a,b”, positive=True)

>>> x = Point(0, 0)
>>> y = Point(a, 0)
>>> z = Point(2*a, b)
>>> t = Triangle(x, y, z)

>>> t.area
a*b/2

>>> t.medians[x]
Segment2D(Point2D(0, 0), Point2D(3*a/2, b/2))

>>> intersection(t.medians[x], t.medians[y], t.medians[z])

[Point2D(a, b/3)]

5.11.5 An in-depth example: Pappus’ Hexagon Theorem

From Wikipedia ([WikiPappus]):

Given one set of collinear points A, B, C, and another set of collinear points a, b, c,
then the intersection points X, Y , Z of line pairs Ab and aB, Ac and aC, Bc and bC
are collinear.

>>> from sympy import *

>>> from sympy.geometry import *
>>>
>>> l1 = Line(Point(0, 0), Point(5, 6))
>>> l2 = Line(Point(0, 0), Point(2, -2))
>>>
>>> def subs_point(l, val):
... ”””Take an arbitrary point and make it a fixed point.”””
... t = Symbol('t', real=True)
... ap = l.arbitrary_point()
... return Point(ap.x.subs(t, val), ap.y.subs(t, val))
...
>>> p11 = subs_point(l1, 5)
>>> p12 = subs_point(l1, 6)
>>> p13 = subs_point(l1, 11)
>>>
>>> p21 = subs_point(l2, -1)
>>> p22 = subs_point(l2, 2)
>>> p23 = subs_point(l2, 13)
>>>
>>> ll1 = Line(p11, p22)
>>> ll2 = Line(p11, p23)
>>> ll3 = Line(p12, p21)
>>> ll4 = Line(p12, p23)
>>> ll5 = Line(p13, p21)
>>> ll6 = Line(p13, p22)
(continues on next page)

582 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>>
>>> pp1 = intersection(ll1, ll3)[0]
>>> pp2 = intersection(ll2, ll5)[0]
>>> pp3 = intersection(ll4, ll6)[0]
>>>
>>> Point.is_collinear(pp1, pp2, pp3)
True

References

5.11.6 Miscellaneous Notes

• The area property of Polygon and Triangle may return a positive or negative value,
depending on whether or not the points are oriented counter-clockwise or clockwise,
respectively. If you always want a positive value be sure to use the abs function.
• Although Polygon can refer to any type of polygon, the code has been written for simple
polygons. Hence, expect potential problems if dealing with complex polygons (overlap-
ping sides).
• Since SymPy is still in its infancy some things may not simplify properly and hence some
things that should return True (e.g., Point.is_collinear) may not actually do so. Sim-
ilarly, attempting to find the intersection of entities that do intersect may result in an
empty result.

5.11.7 Future Work

Truth Setting Expressions

When one deals with symbolic entities, it often happens that an assertion cannot be guaran-
teed. For example, consider the following code:
>>> from sympy import *
>>> from sympy.geometry import *
>>> x,y,z = map(Symbol, 'xyz')
>>> p1,p2,p3 = Point(x, y), Point(y, z), Point(2*x*y, y)
>>> Point.is_collinear(p1, p2, p3)
False

Even though the result is currently False, this is not always true. If the quantity z − y − 2 ∗
y ∗ z + 2 ∗ y ∗ ∗2 == 0 then the points will be collinear. It would be really nice to inform the
user of this because such a quantity may be useful to a user for further calculation and, at
the very least, being nice to know. This could be potentially done by returning an object (e.g.,
GeometryResult) that the user could use. This actually would not involve an extensive amount
of work.

Three Dimensions and Beyond

Currently a limited subset of the geometry module has been extended to three dimensions,
but it certainly would be a good addition to extend more. This would probably involve a fair
amount of work since many of the algorithms used are specific to two dimensions.

5.11. Geometry Module 583

SymPy Documentation, Release 1.3

Geometry Visualization

The plotting module is capable of plotting geometric entities. See Plotting Geometric Entities
(page 1104) in the plotting module entry.

Submodules

Entities

class sympy.geometry.entity.GeometryEntity
The base class for all geometrical entities.
This class doesn’t represent any particular geometric entity, it only provides the imple-
mentation of some methods common to all subclasses.
ambient_dimension
What is the dimension of the space that the object is contained in?
bounds
Return a tuple (xmin, ymin, xmax, ymax) representing the bounding rectangle for
the geometric figure.
encloses(o)
Return True if o is inside (not on or outside) the boundaries of self.
The object will be decomposed into Points and individual Entities need only define
an encloses_point method for their class.
See also:
sympy.geometry.ellipse.Ellipse.encloses_point (page 638), sympy.geometry.
polygon.Polygon.encloses_point (page 653)

Examples

>>> from sympy import RegularPolygon, Point, Polygon

>>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
>>> t2 = Polygon(*RegularPolygon(Point(0, 0), 2, 3).vertices)
>>> t2.encloses(t)
True
>>> t.encloses(t2)
False

intersection(o)
Returns a list of all of the intersections of self with o.
See also:
sympy.geometry.util.intersection (page 587)

Notes

An entity is not required to implement this method.

If two different types of entities can intersect, the item with higher index in order-
ing_of_classes should implement intersections with anything having a lower index.

584 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

is_similar(other)
Is this geometrical entity similar to another geometrical entity?
Two entities are similar if a uniform scaling (enlarging or shrinking) of one of the
entities will allow one to obtain the other.
See also:
scale (page 586)

Notes

This method is not intended to be used directly but rather through the ares imilar
function found in util.py. An entity is not required to implement this method. If two
different types of entities can be similar, it is only required that one of them be able
to determine this.
parameter_value(other, t)
Return the parameter corresponding to the given point. Evaluating an arbitrary
point of the entity at this parameter value will return the given point.

Examples

>>> from sympy import Line, Point

>>> from sympy.abc import t
>>> a = Point(0, 0)
>>> b = Point(2, 2)
>>> Line(a, b).parameter_value((1, 1), t)
{t: 1/2}
>>> Line(a, b).arbitrary_point(t).subs(_)
Point2D(1, 1)

reflect(line)
Reflects an object across a line.
Parameters line: Line

Examples

>>> from sympy import pi, sqrt, Line, RegularPolygon

>>> l = Line((0, pi), slope=sqrt(2))
>>> pent = RegularPolygon((1, 2), 1, 5)
>>> rpent = pent.reflect(l)
>>> rpent
RegularPolygon(Point2D(-2*sqrt(2)*pi/3 - 1/3 + 4*sqrt(2)/3, 2/3 + 2*sqrt(2)/3␣
,→+ 2*pi/3), -1, 5, -atan(2*sqrt(2)) + 3*pi/5)

>>> from sympy import pi, Line, Circle, Point

>>> l = Line((0, pi), slope=1)
>>> circ = Circle(Point(0, 0), 5)
>>> rcirc = circ.reflect(l)
>>> rcirc
Circle(Point2D(-pi, pi), -5)

5.11. Geometry Module 585

SymPy Documentation, Release 1.3

rotate(angle, pt=None)
Rotate angle radians counterclockwise about Point pt.
The default pt is the origin, Point(0, 0)
See also:
scale (page 586), translate (page 586)

Examples

>>> from sympy import Point, RegularPolygon, Polygon, pi

>>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
>>> t # vertex on x axis
Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
>>> t.rotate(pi/2) # vertex on y axis now
Triangle(Point2D(0, 1), Point2D(-sqrt(3)/2, -1/2), Point2D(sqrt(3)/2, -1/2))

scale(x=1, y=1, pt=None)

Scale the object by multiplying the x,y-coordinates by x and y.
If pt is given, the scaling is done relative to that point; the object is shifted by -pt,
scaled, and shifted by pt.
See also:
rotate (page 585), translate (page 586)

Examples

>>> from sympy import RegularPolygon, Point, Polygon

>>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
>>> t
Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
>>> t.scale(2)
Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)/2), Point2D(-1, -sqrt(3)/2))
>>> t.scale(2, 2)
Triangle(Point2D(2, 0), Point2D(-1, sqrt(3)), Point2D(-1, -sqrt(3)))

translate(x=0, y=0)
Shift the object by adding to the x,y-coordinates the values x and y.
See also:
rotate (page 585), scale (page 586)

Examples

>>> from sympy import RegularPolygon, Point, Polygon

>>> t = Polygon(*RegularPolygon(Point(0, 0), 1, 3).vertices)
>>> t
Triangle(Point2D(1, 0), Point2D(-1/2, sqrt(3)/2), Point2D(-1/2, -sqrt(3)/2))
>>> t.translate(2)
Triangle(Point2D(3, 0), Point2D(3/2, sqrt(3)/2), Point2D(3/2, -sqrt(3)/2))
>>> t.translate(2, 2)
(continues on next page)

586 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Triangle(Point2D(3, 2), Point2D(3/2, sqrt(3)/2 + 2),
Point2D(3/2, -sqrt(3)/2 + 2))

Utils

sympy.geometry.util.intersection(*entities, **kwargs)
The intersection of a collection of GeometryEntity instances.
Parameters entities : sequence of GeometryEntity
pairwise (keyword argument) : Can be either True or False
Returns intersection : list of GeometryEntity
Raises NotImplementedError
When unable to calculate intersection.
See also:
sympy.geometry.entity.GeometryEntity.intersection (page 584)

Notes

The intersection of any geometrical entity with itself should return a list with one item:
the entity in question. An intersection requires two or more entities. If only a single en-
tity is given then the function will return an empty list. It is possible for intersection to miss
intersections that one knows exists because the required quantities were not fully sim-
plified internally. Reals should be converted to Rationals, e.g. Rational(str(real_num))
or else failures due to floating point issues may result.
Case 1: When the keyword argument ‘pairwise’ is False (default value): In this case, the
function returns a list of intersections common to all entities.
Case 2: When the keyword argument ‘pairwise’ is True: In this case, the functions re-
turns a list intersections that occur between any pair of entities.

Examples

>>> from sympy.geometry import Ray, Circle, intersection

>>> c = Circle((0, 1), 1)
>>> intersection(c, c.center)
[]
>>> right = Ray((0, 0), (1, 0))
>>> up = Ray((0, 0), (0, 1))
>>> intersection(c, right, up)
[Point2D(0, 0)]
>>> intersection(c, right, up, pairwise=True)
[Point2D(0, 0), Point2D(0, 2)]
>>> left = Ray((1, 0), (0, 0))
>>> intersection(right, left)
[Segment2D(Point2D(0, 0), Point2D(1, 0))]

5.11. Geometry Module 587

SymPy Documentation, Release 1.3

sympy.geometry.util.convex_hull(*args, **kwargs)
The convex hull surrounding the Points contained in the list of entities.
Parameters args : a collection of Points, Segments and/or Polygons
Returns convex_hull : Polygon if polygon is True else as a tuple (U, L) where
L and U are the lower and upper hulls, respectively.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.polygon.Polygon
(page 650)

Notes

This can only be performed on a set of points whose coordinates can be ordered on the
number line.

References

[1] http://en.wikipedia.org/wiki/Graham_scan
[2] Andrew’s Monotone Chain Algorithm (A.M. Andrew, “Another Efficient Algorithm for
Convex Hulls in Two Dimensions”, 1979) http://geomalgorithms.com/a10-_hull-1.html

Examples

>>> from sympy.geometry import Point, convex_hull

>>> points = [(1, 1), (1, 2), (3, 1), (-5, 2), (15, 4)]
>>> convex_hull(*points)
Polygon(Point2D(-5, 2), Point2D(1, 1), Point2D(3, 1), Point2D(15, 4))
>>> convex_hull(*points, **dict(polygon=False))
([Point2D(-5, 2), Point2D(15, 4)],
[Point2D(-5, 2), Point2D(1, 1), Point2D(3, 1), Point2D(15, 4)])

sympy.geometry.util.are_similar(e1, e2)
Are two geometrical entities similar.
Can one geometrical entity be uniformly scaled to the other?
Parameters e1 : GeometryEntity
e2 : GeometryEntity
Returns are_similar : boolean
Raises GeometryError
When e1 and e2 cannot be compared.
See also:
sympy.geometry.entity.GeometryEntity.is_similar (page 585)

Notes

If the two objects are equal then they are similar.

588 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Circle, Triangle, are_similar

>>> c1, c2 = Circle(Point(0, 0), 4), Circle(Point(1, 4), 3)
>>> t1 = Triangle(Point(0, 0), Point(1, 0), Point(0, 1))
>>> t2 = Triangle(Point(0, 0), Point(2, 0), Point(0, 2))
>>> t3 = Triangle(Point(0, 0), Point(3, 0), Point(0, 1))
>>> are_similar(t1, t2)
True
>>> are_similar(t1, t3)
False

sympy.geometry.util.centroid(*args)
Find the centroid (center of mass) of the collection containing only Points, Segments
or Polygons. The centroid is the weighted average of the individual centroid where the
weights are the lengths (of segments) or areas (of polygons). Overlapping regions will
add to the weight of that region.
If there are no objects (or a mixture of objects) then None is returned.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment (page 617),
sympy.geometry.polygon.Polygon (page 650)

Examples

>>> from sympy import Point, Segment, Polygon

>>> from sympy.geometry.util import centroid
>>> p = Polygon((0, 0), (10, 0), (10, 10))
>>> q = p.translate(0, 20)
>>> p.centroid, q.centroid
(Point2D(20/3, 10/3), Point2D(20/3, 70/3))
>>> centroid(p, q)
Point2D(20/3, 40/3)
>>> p, q = Segment((0, 0), (2, 0)), Segment((0, 0), (2, 2))
>>> centroid(p, q)
Point2D(1, -sqrt(2) + 2)
>>> centroid(Point(0, 0), Point(2, 0))
Point2D(1, 0)

Stacking 3 polygons on top of each other effectively triples the weight of that polygon:

>>> p = Polygon((0, 0), (1, 0), (1, 1), (0, 1))

>>> q = Polygon((1, 0), (3, 0), (3, 1), (1, 1))
>>> centroid(p, q)
Point2D(3/2, 1/2)
>>> centroid(p, p, p, q) # centroid x-coord shifts left
Point2D(11/10, 1/2)

Stacking the squares vertically above and below p has the same effect:

>>> centroid(p, p.translate(0, 1), p.translate(0, -1), q)

Point2D(11/10, 1/2)

5.11. Geometry Module 589

SymPy Documentation, Release 1.3

Points

class sympy.geometry.point.Point
A point in a n-dimensional Euclidean space.
Parameters coords : sequence of n-coordinate values. In the special
case where n=2 or 3, a Point2D or Point3D will be created as appro-
priate.
evaluate : if T rue (default), all floats are turn into
exact types.
dim : number of coordinates the point should have. If coordinates
are unspecified, they are padded with zeros.
on_morph : indicates what should happen when the number of
coordinates of a point need to be changed by adding or removing ze-
ros. Possible values are ′ warn′ , ′ error′ , or ignore (default). No warning
or error is given when ∗args is empty and dim is given. An error is
always raised when trying to remove nonzero coordinates.
Raises TypeError : When instantiating with anything but a Point or sequence
ValueError : when instantiating with a sequence with length < 2 or
when trying to reduce dimensions if keyword onm orph =′ error′ is set.
See also:

sympy.geometry.line.Segment (page 617) Connects two Points

Examples

>>> from sympy.geometry import Point

>>> from sympy.abc import x
>>> Point(1, 2, 3)
Point3D(1, 2, 3)
>>> Point([1, 2])
Point2D(1, 2)
>>> Point(0, x)
Point2D(0, x)
>>> Point(dim=4)
Point(0, 0, 0, 0)

Floats are automatically converted to Rational unless the evaluate flag is False:

>>> Point(0.5, 0.25)

Point2D(1/2, 1/4)
>>> Point(0.5, 0.25, evaluate=False)
Point2D(0.5, 0.25)

590 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

length
origin: A P oint representing the origin of the appropriately-dimensioned space.

static affine_rank(*args)
The affine rank of a set of points is the dimension of the smallest affine space con-
taining all the points. For example, if the points lie on a line (and are not all the
same) their affine rank is 1. If the points lie on a plane but not a line, their affine
rank is 2. By convention, the empty set has affine rank -1.
ambient_dimension
Number of components this point has.
classmethod are_coplanar(*points)
Return True if there exists a plane in which all the points lie. A trivial True value is
returned if len(points) < 3 or all Points are 2-dimensional.
Parameters A set of points
Returns boolean
Raises ValueError : if less than 3 unique points are given

Examples

>>> from sympy import Point3D

>>> p1 = Point3D(1, 2, 2)
>>> p2 = Point3D(2, 7, 2)
>>> p3 = Point3D(0, 0, 2)
>>> p4 = Point3D(1, 1, 2)
>>> Point3D.are_coplanar(p1, p2, p3, p4)
True
>>> p5 = Point3D(0, 1, 3)
>>> Point3D.are_coplanar(p1, p2, p3, p5)
False

canberra_distance(p)
The Canberra Distance from self to point p.
Returns the weighted sum of horizontal and vertical distances to point p.
Parameters p : Point
Returns canberra_distance : The weighted sum of horizontal and vertical
distances to point p. The weight used is the sum of absolute values
of the coordinates.
Raises ValueError when both vectors are zero.
See also:
sympy.geometry.point.Point.distance (page 592)

5.11. Geometry Module 591

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import Point

>>> p1, p2 = Point(1, 1), Point(3, 3)
>>> p1.canberra_distance(p2)
1
>>> p1, p2 = Point(0, 0), Point(3, 3)
>>> p1.canberra_distance(p2)
2

distance(p)
The Euclidean distance from self to point p.
Parameters p : Point
Returns distance : number or symbolic expression.
See also:
sympy.geometry.line.Segment.length (page 619), sympy.geometry.point.
Point.taxicab_distance (page 596)

Examples

>>> from sympy.geometry import Point

>>> p1, p2 = Point(1, 1), Point(4, 5)
>>> p1.distance(p2)
5

>>> from sympy.abc import x, y

>>> p3 = Point(x, y)
>>> p3.distance(Point(0, 0))
sqrt(x**2 + y**2)

dot(p)
Return dot product of self with another Point.
equals(other)
Returns whether the coordinates of self and other agree.
evalf(prec=None, **options)
Evaluate the coordinates of the point.
This method will, where possible, create and return a new Point where the co-
ordinates are evaluated as floating point numbers to the precision indicated (de-
fault=15).
Parameters prec : int
Returns point : Point

Examples

>>> from sympy import Point, Rational

>>> p1 = Point(Rational(1, 2), Rational(3, 2))
>>> p1
(continues on next page)

592 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Point2D(1/2, 3/2)
>>> p1.evalf()
Point2D(0.5, 1.5)

intersection(other)
The intersection between this point and another GeometryEntity.
Parameters other : Point
Returns intersection : list of Points

Notes

The return value will either be an empty list if there is no intersection, otherwise it
will contain this point.

Examples

>>> from sympy import Point

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, 0)
>>> p1.intersection(p2)
[]
>>> p1.intersection(p3)
[Point2D(0, 0)]

is_collinear(*args)
Returns T rue if there exists a line that contains self and points. Returns F alse other-
wise. A trivially True value is returned if no points are given.
Parameters args : sequence of Points
Returns is_collinear : boolean
See also:
sympy.geometry.line.Line (page 612)

Examples

>>> from sympy import Point

>>> from sympy.abc import x
>>> p1, p2 = Point(0, 0), Point(1, 1)
>>> p3, p4, p5 = Point(2, 2), Point(x, x), Point(1, 2)
>>> Point.is_collinear(p1, p2, p3, p4)
True
>>> Point.is_collinear(p1, p2, p3, p5)
False

is_concyclic(*args)
Do self and the given sequence of points lie in a circle?
Returns True if the set of points are concyclic and False otherwise. A trivial value
of True is returned if there are fewer than 2 other points.

5.11. Geometry Module 593

SymPy Documentation, Release 1.3

Parameters args : sequence of Points

Returns is_concyclic : boolean

Examples

>>> from sympy import Point

Define 4 points that are on the unit circle:

>>> p1, p2, p3, p4 = Point(1, 0), (0, 1), (-1, 0), (0, -1)

>>> p1.is_concyclic() == p1.is_concyclic(p2, p3, p4) == True

True

Define a point not on that circle:

>>> p = Point(1, 1)

>>> p.is_concyclic(p1, p2, p3)

False

is_nonzero
True if any coordinate is nonzero, False if every coordinate is zero, and None if it
cannot be determined.
is_scalar_multiple(p)
Returns whether each coordinate of self is a scalar multiple of the corresponding
coordinate in point p.
is_zero
True if every coordinate is zero, False if any coordinate is not zero, and None if it
cannot be determined.
length
Treating a Point as a Line, this returns 0 for the length of a Point.

Examples

>>> from sympy import Point

>>> p = Point(0, 1)
>>> p.length
0

midpoint(p)
The midpoint between self and point p.
Parameters p : Point
Returns midpoint : Point
See also:
sympy.geometry.line.Segment.midpoint (page 619)

594 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import Point

>>> p1, p2 = Point(1, 1), Point(13, 5)
>>> p1.midpoint(p2)
Point2D(7, 3)

n(prec=None, **options)
Evaluate the coordinates of the point.
This method will, where possible, create and return a new Point where the co-
ordinates are evaluated as floating point numbers to the precision indicated (de-
fault=15).
Parameters prec : int
Returns point : Point

Examples

>>> from sympy import Point, Rational

>>> p1 = Point(Rational(1, 2), Rational(3, 2))
>>> p1
Point2D(1/2, 3/2)
>>> p1.evalf()
Point2D(0.5, 1.5)

origin
A point of all zeros of the same ambient dimension as the current point
orthogonal_direction
Returns a non-zero point that is orthogonal to the line containing self and the origin.

Examples

>>> from sympy.geometry import Line, Point

>>> a = Point(1, 2, 3)
>>> a.orthogonal_direction
Point3D(-2, 1, 0)
>>> b = _
>>> Line(b, b.origin).is_perpendicular(Line(a, a.origin))
True

static project(a, b)
Project the point a onto the line between the origin and point b along the normal
direction.
Parameters a : Point
b : Point
Returns p : Point
See also:
sympy.geometry.line.LinearEntity.projection (page 611)

5.11. Geometry Module 595

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import Line, Point

>>> a = Point(1, 2)
>>> b = Point(2, 5)
>>> z = a.origin
>>> p = Point.project(a, b)
>>> Line(p, a).is_perpendicular(Line(p, b))
True
>>> Point.is_collinear(z, p, b)
True

taxicab_distance(p)
The Taxicab Distance from self to point p.
Returns the sum of the horizontal and vertical distances to point p.
Parameters p : Point
Returns taxicab_distance : The sum of the horizontal
and vertical distances to point p.
See also:
sympy.geometry.point.Point.distance (page 592)

Examples

>>> from sympy.geometry import Point

>>> p1, p2 = Point(1, 1), Point(4, 5)
>>> p1.taxicab_distance(p2)
7

unit
Return the Point that is in the same direction as self and a distance of 1 from the
origin
class sympy.geometry.point.Point2D
A point in a 2-dimensional Euclidean space.
Parameters coords : sequence of 2 coordinate values.
Raises TypeError
When trying to add or subtract points with different dimensions.
When trying to create a point with more than two dimensions. When
intersection is called with object other than a Point.
See also:

sympy.geometry.line.Segment (page 617) Connects two Points

Examples

596 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.geometry import Point2D

>>> from sympy.abc import x
>>> Point2D(1, 2)
Point2D(1, 2)
>>> Point2D([1, 2])
Point2D(1, 2)
>>> Point2D(0, x)
Point2D(0, x)

Floats are automatically converted to Rational unless the evaluate flag is False:

>>> Point2D(0.5, 0.25)

Point2D(1/2, 1/4)
>>> Point2D(0.5, 0.25, evaluate=False)
Point2D(0.5, 0.25)

Attributes

x
y
length

bounds
Return a tuple (xmin, ymin, xmax, ymax) representing the bounding rectangle for
the geometric figure.
rotate(angle, pt=None)
Rotate angle radians counterclockwise about Point pt.
See also:
rotate (page 597), scale (page 597)

Examples

>>> from sympy import Point2D, pi

>>> t = Point2D(1, 0)
>>> t.rotate(pi/2)
Point2D(0, 1)
>>> t.rotate(pi/2, (2, 0))
Point2D(2, -1)

scale(x=1, y=1, pt=None)

Scale the coordinates of the Point by multiplying by x and y after subtracting pt –
default is (0, 0) – and then adding pt back again (i.e. pt is the point of reference for
the scaling).
See also:
rotate (page 597), translate (page 598)

5.11. Geometry Module 597

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point2D

>>> t = Point2D(1, 1)
>>> t.scale(2)
Point2D(2, 1)
>>> t.scale(2, 2)
Point2D(2, 2)

transform(matrix)
Return the point after applying the transformation described by the 3x3 Matrix,
matrix.
See also:
geometry.entity.rotate, geometry.entity.scale, geometry.entity.translate
translate(x=0, y=0)
Shift the Point by adding x and y to the coordinates of the Point.
See also:
rotate (page 597), scale (page 597)

Examples

>>> from sympy import Point2D

>>> t = Point2D(0, 1)
>>> t.translate(2)
Point2D(2, 1)
>>> t.translate(2, 2)
Point2D(2, 3)
>>> t + Point2D(2, 2)
Point2D(2, 3)

x
Returns the X coordinate of the Point.

Examples

>>> from sympy import Point2D

>>> p = Point2D(0, 1)
>>> p.x
0

y
Returns the Y coordinate of the Point.

Examples

>>> from sympy import Point2D

>>> p = Point2D(0, 1)
>>> p.y
1

598 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.geometry.point.Point3D
A point in a 3-dimensional Euclidean space.
Parameters coords : sequence of 3 coordinate values.
Raises TypeError
When trying to add or subtract points with different dimensions.
When intersection is called with object other than a Point.

Examples

>>> from sympy import Point3D

>>> from sympy.abc import x
>>> Point3D(1, 2, 3)
Point3D(1, 2, 3)
>>> Point3D([1, 2, 3])
Point3D(1, 2, 3)
>>> Point3D(0, x, 3)
Point3D(0, x, 3)

Floats are automatically converted to Rational unless the evaluate flag is False:

>>> Point3D(0.5, 0.25, 2)

Point3D(1/2, 1/4, 2)
>>> Point3D(0.5, 0.25, 3, evaluate=False)
Point3D(0.5, 0.25, 3)

Attributes

x
y
z
length

static are_collinear(*points)
Is a sequence of points collinear?
Test whether or not a set of points are collinear. Returns True if the set of points
are collinear, or False otherwise.
Parameters points : sequence of Point
Returns are_collinear : boolean
See also:
sympy.geometry.line.Line3D (page 627)

Examples

5.11. Geometry Module 599

SymPy Documentation, Release 1.3

>>> from sympy import Point3D, Matrix

>>> from sympy.abc import x
>>> p1, p2 = Point3D(0, 0, 0), Point3D(1, 1, 1)
>>> p3, p4, p5 = Point3D(2, 2, 2), Point3D(x, x, x), Point3D(1, 2, 6)
>>> Point3D.are_collinear(p1, p2, p3, p4)
True
>>> Point3D.are_collinear(p1, p2, p3, p5)
False

direction_cosine(point)
Gives the direction cosine between 2 points
Parameters p : Point3D
Returns list

Examples

>>> from sympy import Point3D

>>> p1 = Point3D(1, 2, 3)
>>> p1.direction_cosine(Point3D(2, 3, 5))
[sqrt(6)/6, sqrt(6)/6, sqrt(6)/3]

direction_ratio(point)
Gives the direction ratio between 2 points
Parameters p : Point3D
Returns list

Examples

>>> from sympy import Point3D

>>> p1 = Point3D(1, 2, 3)
>>> p1.direction_ratio(Point3D(2, 3, 5))
[1, 1, 2]

intersection(other)
The intersection between this point and another point.
Parameters other : Point
Returns intersection : list of Points

Notes

The return value will either be an empty list if there is no intersection, otherwise it
will contain this point.

Examples

600 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Point3D

>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, 0, 0)
>>> p1.intersection(p2)
[]
>>> p1.intersection(p3)
[Point3D(0, 0, 0)]

scale(x=1, y=1, z=1, pt=None)

Scale the coordinates of the Point by multiplying by x and y after subtracting pt –
default is (0, 0) – and then adding pt back again (i.e. pt is the point of reference for
the scaling).
See also:
translate (page 601)

Examples

>>> from sympy import Point3D

>>> t = Point3D(1, 1, 1)
>>> t.scale(2)
Point3D(2, 1, 1)
>>> t.scale(2, 2)
Point3D(2, 2, 1)

transform(matrix)
Return the point after applying the transformation described by the 4x4 Matrix,
matrix.
See also:
geometry.entity.rotate, geometry.entity.scale, geometry.entity.translate
translate(x=0, y=0, z=0)
Shift the Point by adding x and y to the coordinates of the Point.
See also:
rotate, scale (page 601)

Examples

>>> from sympy import Point3D

>>> t = Point3D(0, 1, 1)
>>> t.translate(2)
Point3D(2, 1, 1)
>>> t.translate(2, 2)
Point3D(2, 3, 1)
>>> t + Point3D(2, 2, 2)
Point3D(2, 3, 3)

x
Returns the X coordinate of the Point.

5.11. Geometry Module 601

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point3D

>>> p = Point3D(0, 1, 3)
>>> p.x
0

y
Returns the Y coordinate of the Point.

Examples

>>> from sympy import Point3D

>>> p = Point3D(0, 1, 2)
>>> p.y
1

z
Returns the Z coordinate of the Point.

Examples

>>> from sympy import Point3D

>>> p = Point3D(0, 1, 1)
>>> p.z
1

Lines

class sympy.geometry.line.LinearEntity
A base class for all linear entities (Line, Ray and Segment) in n-dimensional Euclidean
space.
See also:
sympy.geometry.entity.GeometryEntity (page 584)

Notes

This is an abstract class and is not meant to be instantiated.

Attributes

ambient_dimension
direction
length
p1
p2
points

602 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ambient_dimension
A property method that returns the dimension of LinearEntity object.
Parameters p1 : LinearEntity
Returns dimension : integer

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(1, 1)
>>> l1 = Line(p1, p2)
>>> l1.ambient_dimension
2

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0, 0), Point(1, 1, 1)
>>> l1 = Line(p1, p2)
>>> l1.ambient_dimension
3

angle_between(l2)
Return the non-reflex angle formed by rays emanating from the origin with direc-
tions the same as the direction vectors of the linear entities.
Parameters l1 : LinearEntity
l2 : LinearEntity
Returns angle : angle in radians
See also:
is_perpendicular (page 607), Ray2D.closing_angle (page 624)

Notes

From the dot product of vectors v1 and v2 it is known that:

dot(v1, v2) = |v1|*|v2|*cos(A)
where A is the angle formed between the two vectors. We can get the directional
vectors of the two lines and readily find the angle between the two using the above
formula.

Examples

>>> from sympy import Point, Line, pi

>>> e = Line((0, 0), (1, 0))
>>> ne = Line((0, 0), (1, 1))
>>> sw = Line((1, 1), (0, 0))
>>> ne.angle_between(e)
pi/4
>>> sw.angle_between(e)
3*pi/4

5.11. Geometry Module 603

SymPy Documentation, Release 1.3

To obtain the non-obtuse angle at the intersection of lines, use the small-
est_angle_between method:
>>> sw.smallest_angle_between(e)
pi/4

>>> from sympy import Point3D, Line3D

>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(-1, 2, 0)
>>> l1, l2 = Line3D(p1, p2), Line3D(p2, p3)
>>> l1.angle_between(l2)
acos(-sqrt(2)/3)
>>> l1.smallest_angle_between(l2)
acos(sqrt(2)/3)

arbitrary_point(parameter=’t’)
A parameterized point on the Line.
Parameters parameter : str, optional
The name of the parameter which will be used for the parametric
point. The default value is ‘t’. When this parameter is 0, the first
point used to define the line will be returned, and when it is 1 the
second point will be returned.
Returns point : Point
Raises ValueError
When parameter already appears in the Line’s definition.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(1, 0), Point(5, 3)
>>> l1 = Line(p1, p2)
>>> l1.arbitrary_point()
Point2D(4*t + 1, 3*t)
>>> from sympy import Point3D, Line3D
>>> p1, p2 = Point3D(1, 0, 0), Point3D(5, 3, 1)
>>> l1 = Line3D(p1, p2)
>>> l1.arbitrary_point()
Point3D(4*t + 1, 3*t, t)

static are_concurrent(*lines)
Is a sequence of linear entities concurrent?
Two or more linear entities are concurrent if they all intersect at a single point.
Parameters lines : a sequence of linear entities.
Returns True : if the set of linear entities intersect in one point
False : otherwise.
See also:
sympy.geometry.util.intersection (page 587)

604 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Line, Line3D

>>> p1, p2 = Point(0, 0), Point(3, 5)
>>> p3, p4 = Point(-2, -2), Point(0, 2)
>>> l1, l2, l3 = Line(p1, p2), Line(p1, p3), Line(p1, p4)
>>> Line.are_concurrent(l1, l2, l3)
True
>>> l4 = Line(p2, p3)
>>> Line.are_concurrent(l2, l3, l4)
False
>>> from sympy import Point3D, Line3D
>>> p1, p2 = Point3D(0, 0, 0), Point3D(3, 5, 2)
>>> p3, p4 = Point3D(-2, -2, -2), Point3D(0, 2, 1)
>>> l1, l2, l3 = Line3D(p1, p2), Line3D(p1, p3), Line3D(p1, p4)
>>> Line3D.are_concurrent(l1, l2, l3)
True
>>> l4 = Line3D(p2, p3)
>>> Line3D.are_concurrent(l2, l3, l4)
False

contains(other)
Subclasses should implement this method and should return True if other is on the
boundaries of self; False if not on the boundaries of self; None if a determination
cannot be made.
direction
The direction vector of the LinearEntity.
Returns p : a Point; the ray from the origin to this point is the
direction of self
See also:
sympy.geometry.point.Point.unit (page 596)

Examples

>>> from sympy.geometry import Line

>>> a, b = (1, 1), (1, 3)
>>> Line(a, b).direction
Point2D(0, 2)
>>> Line(b, a).direction
Point2D(0, -2)

This can be reported so the distance from the origin is 1:

>>> Line(b, a).direction.unit

Point2D(0, -1)

intersection(other)
The intersection with another geometrical entity.
Parameters o : Point or LinearEntity
Returns intersection : list of geometrical entities

5.11. Geometry Module 605

SymPy Documentation, Release 1.3

See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Line, Segment

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(7, 7)
>>> l1 = Line(p1, p2)
>>> l1.intersection(p3)
[Point2D(7, 7)]
>>> p4, p5 = Point(5, 0), Point(0, 3)
>>> l2 = Line(p4, p5)
>>> l1.intersection(l2)
[Point2D(15/8, 15/8)]
>>> p6, p7 = Point(0, 5), Point(2, 6)
>>> s1 = Segment(p6, p7)
>>> l1.intersection(s1)
[]
>>> from sympy import Point3D, Line3D, Segment3D
>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(7, 7, 7)
>>> l1 = Line3D(p1, p2)
>>> l1.intersection(p3)
[Point3D(7, 7, 7)]
>>> l1 = Line3D(Point3D(4,19,12), Point3D(5,25,17))
>>> l2 = Line3D(Point3D(-3, -15, -19), direction_ratio=[2,8,8])
>>> l1.intersection(l2)
[Point3D(1, 1, -3)]
>>> p6, p7 = Point3D(0, 5, 2), Point3D(2, 6, 3)
>>> s1 = Segment3D(p6, p7)
>>> l1.intersection(s1)
[]

is_parallel(l2)
Are two linear entities parallel?
Parameters l1 : LinearEntity
l2 : LinearEntity
Returns True : if l1 and l2 are parallel,
False : otherwise.
See also:
coefficients

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(1, 1)
>>> p3, p4 = Point(3, 4), Point(6, 7)
>>> l1, l2 = Line(p1, p2), Line(p3, p4)
>>> Line.is_parallel(l1, l2)
True
>>> p5 = Point(6, 6)
(continues on next page)

606 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> l3 = Line(p3, p5)
>>> Line.is_parallel(l1, l3)
False
>>> from sympy import Point3D, Line3D
>>> p1, p2 = Point3D(0, 0, 0), Point3D(3, 4, 5)
>>> p3, p4 = Point3D(2, 1, 1), Point3D(8, 9, 11)
>>> l1, l2 = Line3D(p1, p2), Line3D(p3, p4)
>>> Line3D.is_parallel(l1, l2)
True
>>> p5 = Point3D(6, 6, 6)
>>> l3 = Line3D(p3, p5)
>>> Line3D.is_parallel(l1, l3)
False

is_perpendicular(l2)
Are two linear entities perpendicular?
Parameters l1 : LinearEntity
l2 : LinearEntity
Returns True : if l1 and l2 are perpendicular,
False : otherwise.
See also:
coefficients

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(-1, 1)
>>> l1, l2 = Line(p1, p2), Line(p1, p3)
>>> l1.is_perpendicular(l2)
True
>>> p4 = Point(5, 3)
>>> l3 = Line(p1, p4)
>>> l1.is_perpendicular(l3)
False
>>> from sympy import Point3D, Line3D
>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(-1, 2, 0)
>>> l1, l2 = Line3D(p1, p2), Line3D(p2, p3)
>>> l1.is_perpendicular(l2)
False
>>> p4 = Point3D(5, 3, 7)
>>> l3 = Line3D(p1, p4)
>>> l1.is_perpendicular(l3)
False

is_similar(other)
Return True if self and other are contained in the same line.

5.11. Geometry Module 607

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 1), Point(3, 4), Point(2, 3)
>>> l1 = Line(p1, p2)
>>> l2 = Line(p1, p3)
>>> l1.is_similar(l2)
True

length
The length of the line.

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(3, 5)
>>> l1 = Line(p1, p2)
>>> l1.length
oo

p1
The first defining point of a linear entity.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> l = Line(p1, p2)
>>> l.p1
Point2D(0, 0)

p2
The second defining point of a linear entity.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> l = Line(p1, p2)
>>> l.p2
Point2D(5, 3)

parallel_line(p)
Create a new Line parallel to this linear entity which passes through the point p.
Parameters p : Point

608 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns line : Line

See also:
is_parallel (page 606)

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 0), Point(2, 3), Point(-2, 2)
>>> l1 = Line(p1, p2)
>>> l2 = l1.parallel_line(p3)
>>> p3 in l2
True
>>> l1.is_parallel(l2)
True
>>> from sympy import Point3D, Line3D
>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(2, 3, 4), Point3D(-2, 2, 0)
>>> l1 = Line3D(p1, p2)
>>> l2 = l1.parallel_line(p3)
>>> p3 in l2
True
>>> l1.is_parallel(l2)
True

perpendicular_line(p)
Create a new Line perpendicular to this linear entity which passes through the point
p.
Parameters p : Point
Returns line : Line
See also:
is_perpendicular (page 607), perpendicular_segment (page 609)

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 0), Point(2, 3), Point(-2, 2)
>>> l1 = Line(p1, p2)
>>> l2 = l1.perpendicular_line(p3)
>>> p3 in l2
True
>>> l1.is_perpendicular(l2)
True
>>> from sympy import Point3D, Line3D
>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(2, 3, 4), Point3D(-2, 2, 0)
>>> l1 = Line3D(p1, p2)
>>> l2 = l1.perpendicular_line(p3)
>>> p3 in l2
True
>>> l1.is_perpendicular(l2)
True

5.11. Geometry Module 609

SymPy Documentation, Release 1.3

perpendicular_segment(p)
Create a perpendicular line segment from p to this line.
The enpoints of the segment are p and the closest point in the line containing self.
(If self is not a line, the point might not be in self.)
Parameters p : Point
Returns segment : Segment
See also:
perpendicular_line (page 609)

Notes

Returns p itself if p is on this linear entity.

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, 2)
>>> l1 = Line(p1, p2)
>>> s1 = l1.perpendicular_segment(p3)
>>> l1.is_perpendicular(s1)
True
>>> p3 in s1
True
>>> l1.perpendicular_segment(Point(4, 0))
Segment2D(Point2D(4, 0), Point2D(2, 2))
>>> from sympy import Point3D, Line3D
>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, 2, 0)
>>> l1 = Line3D(p1, p2)
>>> s1 = l1.perpendicular_segment(p3)
>>> l1.is_perpendicular(s1)
True
>>> p3 in s1
True
>>> l1.perpendicular_segment(Point3D(4, 0, 0))
Segment3D(Point3D(4, 0, 0), Point3D(4/3, 4/3, 4/3))

points
The two points used to define this linear entity.
Returns points : tuple of Points
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(5, 11)
>>> l1 = Line(p1, p2)
(continues on next page)

610 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> l1.points
(Point2D(0, 0), Point2D(5, 11))

projection(other)
Project a point, line, ray, or segment onto this linear entity.
Parameters other : Point or LinearEntity (Line, Ray, Segment)
Returns projection : Point or LinearEntity (Line, Ray, Segment)
The return type matches the type of the parameter other.
Raises GeometryError
When method is unable to perform projection.
See also:
sympy.geometry.point.Point (page 590), perpendicular_line (page 609)

Notes

A projection involves taking the two points that define the linear entity and pro-
jecting those points onto a Line and then reforming the linear entity using these
projections. A point P is projected onto a line L by finding the point on L that is
closest to P. This point is the intersection of L and the line perpendicular to L that
passes through P.

Examples

>>> from sympy import Point, Line, Segment, Rational

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(Rational(1, 2), 0)
>>> l1 = Line(p1, p2)
>>> l1.projection(p3)
Point2D(1/4, 1/4)
>>> p4, p5 = Point(10, 0), Point(12, 1)
>>> s1 = Segment(p4, p5)
>>> l1.projection(s1)
Segment2D(Point2D(5, 5), Point2D(13/2, 13/2))
>>> p1, p2, p3 = Point(0, 0, 1), Point(1, 1, 2), Point(2, 0, 1)
>>> l1 = Line(p1, p2)
>>> l1.projection(p3)
Point3D(2/3, 2/3, 5/3)
>>> p4, p5 = Point(10, 0, 1), Point(12, 1, 3)
>>> s1 = Segment(p4, p5)
>>> l1.projection(s1)
Segment3D(Point3D(10/3, 10/3, 13/3), Point3D(5, 5, 6))

random_point(seed=None)
A random point on a LinearEntity.
Returns point : Point
See also:
sympy.geometry.point.Point (page 590)

5.11. Geometry Module 611

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Line, Ray, Segment

>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> line = Line(p1, p2)
>>> r = line.random_point(seed=42) # seed value is optional
>>> r.n(3)
Point2D(-0.72, -0.432)
>>> r in line
True
>>> Ray(p1, p2).random_point(seed=42).n(3)
Point2D(0.72, 0.432)
>>> Segment(p1, p2).random_point(seed=42).n(3)
Point2D(3.2, 1.92)

smallest_angle_between(l2)
Return the smallest angle formed at the intersection of the lines containing the linear
entities.
Parameters l1 : LinearEntity
l2 : LinearEntity
Returns angle : angle in radians
See also:
angle_between (page 603), Ray2D.closing_angle (page 624)

Examples

>>> from sympy import Point, Line, pi

>>> p1, p2, p3 = Point(0, 0), Point(0, 4), Point(2, -2)
>>> l1, l2 = Line(p1, p2), Line(p1, p3)
>>> l1.smallest_angle_between(l2)
pi/4

class sympy.geometry.line.Line
An infinite line in space.
A line is declared with two distinct points. A 2D line may be declared with a point and
slope and a 3D line may be defined with a point and a direction ratio.
Parameters p1 : Point
p2 : Point
slope : sympy expression
direction_ratio : list
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Line2D (page 622),
sympy.geometry.line.Line3D (page 627)

612 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notes

Line will automatically subclass to Line2D or Line3D based on the dimension of p1. The
slope argument is only relevant for Line2D and the directionr atio argument is only relevant
for Line3D.

Examples

>>> from sympy import Point

>>> from sympy.geometry import Line, Segment
>>> L = Line(Point(2,3), Point(3,5))
>>> L
Line2D(Point2D(2, 3), Point2D(3, 5))
>>> L.points
(Point2D(2, 3), Point2D(3, 5))
>>> L.equation()
-2*x + y + 1
>>> L.coefficients
(-2, 1, 1)

Instantiate with keyword slope:

>>> Line(Point(0, 0), slope=0)
Line2D(Point2D(0, 0), Point2D(1, 0))

Instantiate with another linear object

>>> s = Segment((0, 0), (0, 1))
>>> Line(s).equation()
x

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

contains(other)
Return True if other is on this Line, or False otherwise.

Examples

>>> from sympy import Line,Point

>>> p1, p2 = Point(0, 1), Point(3, 4)
>>> l = Line(p1, p2)
>>> l.contains(p1)
True
>>> l.contains((0, 1))
True
(continues on next page)

5.11. Geometry Module 613

SymPy Documentation, Release 1.3

(continued from previous page)

>>> l.contains((0, 0))
False
>>> a = (0, 0, 0)
>>> b = (1, 1, 1)
>>> c = (2, 2, 2)
>>> l1 = Line(a, b)
>>> l2 = Line(b, a)
>>> l1 == l2
False
>>> l1 in l2
True

distance(other)
Finds the shortest distance between a line and a point.
Raises NotImplementedError is raised if ‘other‘ is not a Point

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(1, 1)
>>> s = Line(p1, p2)
>>> s.distance(Point(-1, 1))
sqrt(2)
>>> s.distance((-1, 2))
3*sqrt(2)/2
>>> p1, p2 = Point(0, 0, 0), Point(1, 1, 1)
>>> s = Line(p1, p2)
>>> s.distance(Point(-1, 1, 1))
2*sqrt(6)/3
>>> s.distance((-1, 1, 1))
2*sqrt(6)/3

equals(other)
Returns True if self and other are the same mathematical entities
plot_interval(parameter=’t’)
The plot interval for the default geometric plot of line. Gives values that will produce
a line that is +/- 5 units long (where a unit is the distance between the two points
that define the line).
Parameters parameter : str, optional
Default value is ‘t’.
Returns plot_interval : list (plot interval)
[parameter, lower_bound, upper_bound]

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> l1 = Line(p1, p2)
(continues on next page)

614 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> l1.plot_interval()
[t, -5, 5]

class sympy.geometry.line.Ray
A Ray is a semi-line in the space with a source point and a direction.
Parameters p1 : Point
The source of the Ray
p2 : Point or radian value
This point determines the direction in which the Ray propagates. If
given as an angle it is interpreted in radians with the positive direc-
tion being ccw.
See also:
sympy.geometry.line.Ray2D (page 623), sympy.geometry.line.Ray3D (page 628),
sympy.geometry.point.Point (page 590), sympy.geometry.line.Line (page 612)

Notes

Ray will automatically subclass to Ray2D or Ray3D based on the dimension of p1.

Examples

>>> from sympy import Point, pi

>>> from sympy.geometry import Ray
>>> r = Ray(Point(2, 3), Point(3, 5))
>>> r
Ray2D(Point2D(2, 3), Point2D(3, 5))
>>> r.points
(Point2D(2, 3), Point2D(3, 5))
>>> r.source
Point2D(2, 3)
>>> r.xdirection
oo
>>> r.ydirection
oo
>>> r.slope
2
>>> Ray(Point(0, 0), angle=pi/4).slope
1

Attributes

source

contains(other)
Is other GeometryEntity contained in this Ray?

5.11. Geometry Module 615

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Ray,Point,Segment

>>> p1, p2 = Point(0, 0), Point(4, 4)
>>> r = Ray(p1, p2)
>>> r.contains(p1)
True
>>> r.contains((1, 1))
True
>>> r.contains((1, 3))
False
>>> s = Segment((1, 1), (2, 2))
>>> r.contains(s)
True
>>> s = Segment((1, 2), (2, 5))
>>> r.contains(s)
False
>>> r1 = Ray((2, 2), (3, 3))
>>> r.contains(r1)
True
>>> r1 = Ray((2, 2), (3, 5))
>>> r.contains(r1)
False

distance(other)
Finds the shortest distance between the ray and a point.
Raises NotImplementedError is raised if ‘other‘ is not a Point

Examples

>>> from sympy import Point, Ray

>>> p1, p2 = Point(0, 0), Point(1, 1)
>>> s = Ray(p1, p2)
>>> s.distance(Point(-1, -1))
sqrt(2)
>>> s.distance((-1, 2))
3*sqrt(2)/2
>>> p1, p2 = Point(0, 0, 0), Point(1, 1, 2)
>>> s = Ray(p1, p2)
>>> s
Ray3D(Point3D(0, 0, 0), Point3D(1, 1, 2))
>>> s.distance(Point(-1, -1, 2))
4*sqrt(3)/3
>>> s.distance((-1, -1, 2))
4*sqrt(3)/3

equals(other)
Returns True if self and other are the same mathematical entities
plot_interval(parameter=’t’)
The plot interval for the default geometric plot of the Ray. Gives values that will
produce a ray that is 10 units long (where a unit is the distance between the two
points that define the ray).
Parameters parameter : str, optional

616 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Default value is ‘t’.

Returns plot_interval : list
[parameter, lower_bound, upper_bound]

Examples

>>> from sympy import Ray, pi

>>> r = Ray((0, 0), angle=pi/4)
>>> r.plot_interval()
[t, 0, 10]

source
The point from which the ray emanates.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Ray

>>> p1, p2 = Point(0, 0), Point(4, 1)
>>> r1 = Ray(p1, p2)
>>> r1.source
Point2D(0, 0)
>>> p1, p2 = Point(0, 0, 0), Point(4, 1, 5)
>>> r1 = Ray(p2, p1)
>>> r1.source
Point3D(4, 1, 5)

class sympy.geometry.line.Segment
A line segment in space.
Parameters p1 : Point
p2 : Point
See also:
sympy.geometry.line.Segment2D (page 625), sympy.geometry.line.Segment3D
(page 630), sympy.geometry.point.Point (page 590), sympy.geometry.line.Line
(page 612)

Notes

If 2D or 3D points are used to define Segment, it will be automatically subclassed to

Segment2D or Segment3D.

Examples

5.11. Geometry Module 617

SymPy Documentation, Release 1.3

>>> from sympy import Point

>>> from sympy.geometry import Segment
>>> Segment((1, 0), (1, 1)) # tuples are interpreted as pts
Segment2D(Point2D(1, 0), Point2D(1, 1))
>>> s = Segment(Point(4, 3), Point(1, 1))
>>> s.points
(Point2D(4, 3), Point2D(1, 1))
>>> s.slope
2/3
>>> s.length
sqrt(13)
>>> s.midpoint
Point2D(5/2, 2)
>>> Segment((1, 0, 0), (1, 1, 1)) # tuples are interpreted as pts
Segment3D(Point3D(1, 0, 0), Point3D(1, 1, 1))
>>> s = Segment(Point(4, 3, 9), Point(1, 1, 7)); s
Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7))
>>> s.points
(Point3D(4, 3, 9), Point3D(1, 1, 7))
>>> s.length
sqrt(17)
>>> s.midpoint
Point3D(5/2, 2, 8)

Attributes

length (number or sympy expression)

midpoint (Point)

contains(other)
Is the other GeometryEntity contained within this Segment?

Examples

>>> from sympy import Point, Segment

>>> p1, p2 = Point(0, 1), Point(3, 4)
>>> s = Segment(p1, p2)
>>> s2 = Segment(p2, p1)
>>> s.contains(s2)
True
>>> from sympy import Point3D, Segment3D
>>> p1, p2 = Point3D(0, 1, 1), Point3D(3, 4, 5)
>>> s = Segment3D(p1, p2)
>>> s2 = Segment3D(p2, p1)
>>> s.contains(s2)
True
>>> s.contains((p1 + p2) / 2)
True

distance(other)
Finds the shortest distance between a line segment and a point.
Raises NotImplementedError is raised if ‘other‘ is not a Point

618 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Segment

>>> p1, p2 = Point(0, 1), Point(3, 4)
>>> s = Segment(p1, p2)
>>> s.distance(Point(10, 15))
sqrt(170)
>>> s.distance((0, 12))
sqrt(73)
>>> from sympy import Point3D, Segment3D
>>> p1, p2 = Point3D(0, 0, 3), Point3D(1, 1, 4)
>>> s = Segment3D(p1, p2)
>>> s.distance(Point3D(10, 15, 12))
sqrt(341)
>>> s.distance((10, 15, 12))
sqrt(341)

equals(other)
Returns True if self and other are the same mathematical entities
length
The length of the line segment.
See also:
sympy.geometry.point.Point.distance (page 592)

Examples

>>> from sympy import Point, Segment

>>> p1, p2 = Point(0, 0), Point(4, 3)
>>> s1 = Segment(p1, p2)
>>> s1.length
5
>>> from sympy import Point3D, Segment3D
>>> p1, p2 = Point3D(0, 0, 0), Point3D(4, 3, 3)
>>> s1 = Segment3D(p1, p2)
>>> s1.length
sqrt(34)

midpoint
The midpoint of the line segment.
See also:
sympy.geometry.point.Point.midpoint (page 594)

Examples

>>> from sympy import Point, Segment

>>> p1, p2 = Point(0, 0), Point(4, 3)
>>> s1 = Segment(p1, p2)
>>> s1.midpoint
Point2D(2, 3/2)
>>> from sympy import Point3D, Segment3D
(continues on next page)

5.11. Geometry Module 619

SymPy Documentation, Release 1.3

(continued from previous page)

>>> p1, p2 = Point3D(0, 0, 0), Point3D(4, 3, 3)
>>> s1 = Segment3D(p1, p2)
>>> s1.midpoint
Point3D(2, 3/2, 3/2)

perpendicular_bisector(p=None)
The perpendicular bisector of this segment.
If no point is specified or the point specified is not on the bisector then the bisector
is returned as a Line. Otherwise a Segment is returned that joins the point specified
and the intersection of the bisector and the segment.
Parameters p : Point
Returns bisector : Line or Segment
See also:
LinearEntity.perpendicular_segment (page 609)

Examples

>>> from sympy import Point, Segment

>>> p1, p2, p3 = Point(0, 0), Point(6, 6), Point(5, 1)
>>> s1 = Segment(p1, p2)
>>> s1.perpendicular_bisector()
Line2D(Point2D(3, 3), Point2D(-3, 9))

>>> s1.perpendicular_bisector(p3)
Segment2D(Point2D(5, 1), Point2D(3, 3))

plot_interval(parameter=’t’)
The plot interval for the default geometric plot of the Segment gives values that will
produce the full segment in a plot.
Parameters parameter : str, optional
Default value is ‘t’.
Returns plot_interval : list
[parameter, lower_bound, upper_bound]

Examples

>>> from sympy import Point, Segment

>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> s1 = Segment(p1, p2)
>>> s1.plot_interval()
[t, 0, 1]

class sympy.geometry.line.LinearEntity2D
A base class for all linear entities (line, ray and segment) in a 2-dimensional Euclidean
space.
See also:

620 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.geometry.entity.GeometryEntity (page 584)

Notes

This is an abstract class and is not meant to be instantiated.

Attributes

p1
p2
coefficients
slope
points

bounds
Return a tuple (xmin, ymin, xmax, ymax) representing the bounding rectangle for
the geometric figure.
perpendicular_line(p)
Create a new Line perpendicular to this linear entity which passes through the point
p.
Parameters p : Point
Returns line : Line
See also:
is_perpendicular, perpendicular_segment

Examples

>>> from sympy import Point, Line

>>> p1, p2, p3 = Point(0, 0), Point(2, 3), Point(-2, 2)
>>> l1 = Line(p1, p2)
>>> l2 = l1.perpendicular_line(p3)
>>> p3 in l2
True
>>> l1.is_perpendicular(l2)
True

slope
The slope of this linear entity, or infinity if vertical.
Returns slope : number or sympy expression
See also:
coefficients

5.11. Geometry Module 621

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(0, 0), Point(3, 5)
>>> l1 = Line(p1, p2)
>>> l1.slope
5/3

>>> p3 = Point(0, 4)
>>> l2 = Line(p1, p3)
>>> l2.slope
oo

class sympy.geometry.line.Line2D
An infinite line in space 2D.
A line is declared with two distinct points or a point and slope as defined using keyword
slope.
Parameters p1 : Point
pt : Point
slope : sympy expression
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point

>>> from sympy.abc import L
>>> from sympy.geometry import Line, Segment
>>> L = Line(Point(2,3), Point(3,5))
>>> L
Line2D(Point2D(2, 3), Point2D(3, 5))
>>> L.points
(Point2D(2, 3), Point2D(3, 5))
>>> L.equation()
-2*x + y + 1
>>> L.coefficients
(-2, 1, 1)

Instantiate with keyword slope:

>>> Line(Point(0, 0), slope=0)

Line2D(Point2D(0, 0), Point2D(1, 0))

Instantiate with another linear object

>>> s = Segment((0, 0), (0, 1))

>>> Line(s).equation()
x

622 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

coefficients
The coefficients (a, b, c) for ax + by + c = 0.
See also:
sympy.geometry.line.Line.equation

Examples

>>> from sympy import Point, Line

>>> from sympy.abc import x, y
>>> p1, p2 = Point(0, 0), Point(5, 3)
>>> l = Line(p1, p2)
>>> l.coefficients
(-3, 5, 0)

>>> p3 = Point(x, y)
>>> l2 = Line(p1, p3)
>>> l2.coefficients
(-y, x, 0)

equation(x=’x’, y=’y’)
The equation of the line: ax + by + c.
Parameters x : str, optional
The name to use for the x-axis, default value is ‘x’.
y : str, optional
The name to use for the y-axis, default value is ‘y’.
Returns equation : sympy expression
See also:
LinearEntity.coefficients

Examples

>>> from sympy import Point, Line

>>> p1, p2 = Point(1, 0), Point(5, 3)
>>> l1 = Line(p1, p2)
>>> l1.equation()
-3*x + 4*y + 3

class sympy.geometry.line.Ray2D
A Ray is a semi-line in the space with a source point and a direction.

5.11. Geometry Module 623

SymPy Documentation, Release 1.3

Parameters p1 : Point
The source of the Ray
p2 : Point or radian value
This point determines the direction in which the Ray propagates. If
given as an angle it is interpreted in radians with the positive direc-
tion being ccw.
See also:
sympy.geometry.point.Point (page 590), Line (page 612)

Examples

>>> from sympy import Point, pi

>>> from sympy.geometry import Ray
>>> r = Ray(Point(2, 3), Point(3, 5))
>>> r
Ray2D(Point2D(2, 3), Point2D(3, 5))
>>> r.points
(Point2D(2, 3), Point2D(3, 5))
>>> r.source
Point2D(2, 3)
>>> r.xdirection
oo
>>> r.ydirection
oo
>>> r.slope
2
>>> Ray(Point(0, 0), angle=pi/4).slope
1

Attributes

source
xdirection
ydirection

closing_angle(r2)
Return the angle by which r2 must be rotated so it faces the same direction as r1.
Parameters r1 : Ray2D
r2 : Ray2D
Returns angle : angle in radians (ccw angle is positive)
See also:
LinearEntity.angle_between (page 603)

624 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Ray, pi

>>> r1 = Ray((0, 0), (1, 0))
>>> r2 = r1.rotate(-pi/2)
>>> angle = r1.closing_angle(r2); angle
pi/2
>>> r2.rotate(angle).direction.unit == r1.direction.unit
True
>>> r2.closing_angle(r1)
-pi/2

xdirection
The x direction of the ray.
Positive infinity if the ray points in the positive x direction, negative infinity if the
ray points in the negative x direction, or 0 if the ray is vertical.
See also:
ydirection (page 625)

Examples

>>> from sympy import Point, Ray

>>> p1, p2, p3 = Point(0, 0), Point(1, 1), Point(0, -1)
>>> r1, r2 = Ray(p1, p2), Ray(p1, p3)
>>> r1.xdirection
oo
>>> r2.xdirection
0

ydirection
The y direction of the ray.
Positive infinity if the ray points in the positive y direction, negative infinity if the
ray points in the negative y direction, or 0 if the ray is horizontal.
See also:
xdirection (page 625)

Examples

>>> from sympy import Point, Ray

>>> p1, p2, p3 = Point(0, 0), Point(-1, -1), Point(-1, 0)
>>> r1, r2 = Ray(p1, p2), Ray(p1, p3)
>>> r1.ydirection
-oo
>>> r2.ydirection
0

class sympy.geometry.line.Segment2D
A line segment in 2D space.

5.11. Geometry Module 625

SymPy Documentation, Release 1.3

Parameters p1 : Point
p2 : Point
See also:
sympy.geometry.point.Point (page 590), Line (page 612)

Examples

>>> from sympy import Point

>>> from sympy.geometry import Segment
>>> Segment((1, 0), (1, 1)) # tuples are interpreted as pts
Segment2D(Point2D(1, 0), Point2D(1, 1))
>>> s = Segment(Point(4, 3), Point(1, 1)); s
Segment2D(Point2D(4, 3), Point2D(1, 1))
>>> s.points
(Point2D(4, 3), Point2D(1, 1))
>>> s.slope
2/3
>>> s.length
sqrt(13)
>>> s.midpoint
Point2D(5/2, 2)

Attributes

length (number or sympy expression)

midpoint (Point)

class sympy.geometry.line.LinearEntity3D
An base class for all linear entities (line, ray and segment) in a 3-dimensional Euclidean
space.

Notes

This is a base class and is not meant to be instantiated.

Attributes

p1
p2
direction_ratio
direction_cosine
points

direction_cosine
The normalized direction ratio of a given line in 3D.
See also:

626 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.geometry.line.Line.equation

Examples

>>> from sympy import Point3D, Line3D

>>> p1, p2 = Point3D(0, 0, 0), Point3D(5, 3, 1)
>>> l = Line3D(p1, p2)
>>> l.direction_cosine
[sqrt(35)/7, 3*sqrt(35)/35, sqrt(35)/35]
>>> sum(i**2 for i in _)
1

direction_ratio
The direction ratio of a given line in 3D.
See also:
sympy.geometry.line.Line.equation

Examples

>>> from sympy import Point3D, Line3D

>>> p1, p2 = Point3D(0, 0, 0), Point3D(5, 3, 1)
>>> l = Line3D(p1, p2)
>>> l.direction_ratio
[5, 3, 1]

class sympy.geometry.line.Line3D
An infinite 3D line in space.
A line is declared with two distinct points or a point and direction_ratio as defined using
keyword directionr atio.
Parameters p1 : Point3D
pt : Point3D
direction_ratio : list
See also:
sympy.geometry.point.Point3D (page 598), sympy.geometry.line.Line (page 612),
sympy.geometry.line.Line2D (page 622)

Examples

>>> from sympy import Point3D

>>> from sympy.geometry import Line3D, Segment3D
>>> L = Line3D(Point3D(2, 3, 4), Point3D(3, 5, 1))
>>> L
Line3D(Point3D(2, 3, 4), Point3D(3, 5, 1))
>>> L.points
(Point3D(2, 3, 4), Point3D(3, 5, 1))

5.11. Geometry Module 627

SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

equation(x=’x’, y=’y’, z=’z’, k=None)

Return the equations that define the line in 3D.
Parameters x : str, optional
The name to use for the x-axis, default value is ‘x’.
y : str, optional
The name to use for the y-axis, default value is ‘y’.
z : str, optional
The name to use for the z-axis, default value is ‘z’.
Returns equation : Tuple of simultaneous equations

Examples

>>> from sympy import Point3D, Line3D, solve

>>> from sympy.abc import x, y, z
>>> p1, p2 = Point3D(1, 0, 0), Point3D(5, 3, 0)
>>> l1 = Line3D(p1, p2)
>>> eq = l1.equation(x, y, z); eq
(-3*x + 4*y + 3, z)
>>> solve(eq.subs(z, 0), (x, y, z))
{x: 4*y/3 + 1}

class sympy.geometry.line.Ray3D
A Ray is a semi-line in the space with a source point and a direction.
Parameters p1 : Point3D
The source of the Ray
p2 : Point or a direction vector
direction_ratio: Determines the direction in which the Ray propa-
gates.
See also:
sympy.geometry.point.Point3D (page 598), Line3D (page 627)

Examples

>>> from sympy import Point3D

>>> from sympy.geometry import Ray3D
>>> r = Ray3D(Point3D(2, 3, 4), Point3D(3, 5, 0))
>>> r
(continues on next page)

628 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Ray3D(Point3D(2, 3, 4), Point3D(3, 5, 0))
>>> r.points
(Point3D(2, 3, 4), Point3D(3, 5, 0))
>>> r.source
Point3D(2, 3, 4)
>>> r.xdirection
oo
>>> r.ydirection
oo
>>> r.direction_ratio
[1, 2, -4]

Attributes

source
xdirection
ydirection
zdirection

xdirection
The x direction of the ray.
Positive infinity if the ray points in the positive x direction, negative infinity if the
ray points in the negative x direction, or 0 if the ray is vertical.
See also:
ydirection (page 629)

Examples

>>> from sympy import Point3D, Ray3D

>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(1, 1, 1), Point3D(0, -1, 0)
>>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
>>> r1.xdirection
oo
>>> r2.xdirection
0

ydirection
The y direction of the ray.
Positive infinity if the ray points in the positive y direction, negative infinity if the
ray points in the negative y direction, or 0 if the ray is horizontal.
See also:
xdirection (page 629)

5.11. Geometry Module 629

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point3D, Ray3D

>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(-1, -1, -1), Point3D(-1, 0, 0)
>>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
>>> r1.ydirection
-oo
>>> r2.ydirection
0

zdirection
The z direction of the ray.
Positive infinity if the ray points in the positive z direction, negative infinity if the
ray points in the negative z direction, or 0 if the ray is horizontal.
See also:
xdirection (page 629)

Examples

>>> from sympy import Point3D, Ray3D

>>> p1, p2, p3 = Point3D(0, 0, 0), Point3D(-1, -1, -1), Point3D(-1, 0, 0)
>>> r1, r2 = Ray3D(p1, p2), Ray3D(p1, p3)
>>> r1.ydirection
-oo
>>> r2.ydirection
0
>>> r2.zdirection
0

class sympy.geometry.line.Segment3D
A line segment in a 3D space.
Parameters p1 : Point3D
p2 : Point3D
See also:
sympy.geometry.point.Point3D (page 598), Line3D (page 627)

Examples

>>> from sympy import Point3D

>>> from sympy.geometry import Segment3D
>>> Segment3D((1, 0, 0), (1, 1, 1)) # tuples are interpreted as pts
Segment3D(Point3D(1, 0, 0), Point3D(1, 1, 1))
>>> s = Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7)); s
Segment3D(Point3D(4, 3, 9), Point3D(1, 1, 7))
>>> s.points
(Point3D(4, 3, 9), Point3D(1, 1, 7))
>>> s.length
sqrt(17)
(continues on next page)

630 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> s.midpoint
Point3D(5/2, 2, 8)

Attributes

length (number or sympy expression)

midpoint (Point3D)

Curves

class sympy.geometry.curve.Curve
A curve in space.
A curve is defined by parametric functions for the coordinates, a parameter and the lower
and upper bounds for the parameter value.
Parameters function : list of functions
limits : 3-tuple
Function parameter and lower and upper bounds.
Raises ValueError
When f unctions are specified incorrectly. When limits are specified
incorrectly.
See also:
sympy.core.function.Function (page 189), sympy.polys.polyfuncs.interpolate
(page 890)

Examples

>>> from sympy import sin, cos, Symbol, interpolate

>>> from sympy.abc import t, a
>>> from sympy.geometry import Curve
>>> C = Curve((sin(t), cos(t)), (t, 0, 2))
>>> C.functions
(sin(t), cos(t))
>>> C.limits
(t, 0, 2)
>>> C.parameter
t
>>> C = Curve((t, interpolate([1, 4, 9, 16], t)), (t, 0, 1)); C
Curve((t, t**2), (t, 0, 1))
>>> C.subs(t, 4)
Point2D(4, 16)
>>> C.arbitrary_point(a)
Point2D(a, a**2)

5.11. Geometry Module 631

SymPy Documentation, Release 1.3

Attributes

functions
parameter
limits

arbitrary_point(parameter=’t’)
A parameterized point on the curve.
Parameters parameter : str or Symbol, optional
Default value is ‘t’; the Curve’s parameter is selected with None or
self.parameter otherwise the provided symbol is used.
Returns arbitrary_point : Point
Raises ValueError
When parameter already appears in the functions.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Symbol

>>> from sympy.abc import s
>>> from sympy.geometry import Curve
>>> C = Curve([2*s, s**2], (s, 0, 2))
>>> C.arbitrary_point()
Point2D(2*t, t**2)
>>> C.arbitrary_point(C.parameter)
Point2D(2*s, s**2)
>>> C.arbitrary_point(None)
Point2D(2*s, s**2)
>>> C.arbitrary_point(Symbol('a'))
Point2D(2*a, a**2)

free_symbols
Return a set of symbols other than the bound symbols used to parametrically define
the Curve.

Examples

>>> from sympy.abc import t, a

>>> from sympy.geometry import Curve
>>> Curve((t, t**2), (t, 0, 2)).free_symbols
set()
>>> Curve((t, t**2), (t, a, 2)).free_symbols
{a}

functions
The functions specifying the curve.
Returns functions : list of parameterized coordinate functions.

632 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
parameter (page 633)

Examples

>>> from sympy.abc import t

>>> from sympy.geometry import Curve
>>> C = Curve((t, t**2), (t, 0, 2))
>>> C.functions
(t, t**2)

length
The curve length.

Examples

>>> from sympy.geometry.curve import Curve

>>> from sympy import cos, sin
>>> from sympy.abc import t
>>> Curve((t, t), (t, 0, 1)).length
sqrt(2)

limits
The limits for the curve.
Returns limits : tuple
Contains parameter and lower and upper limits.
See also:
plot_interval (page 634)

Examples

>>> from sympy.abc import t

>>> from sympy.geometry import Curve
>>> C = Curve([t, t**3], (t, -2, 2))
>>> C.limits
(t, -2, 2)

parameter
The curve function variable.
Returns parameter : SymPy symbol
See also:
functions (page 632)

5.11. Geometry Module 633

SymPy Documentation, Release 1.3

Examples

>>> from sympy.abc import t

>>> from sympy.geometry import Curve
>>> C = Curve([t, t**2], (t, 0, 2))
>>> C.parameter
t

plot_interval(parameter=’t’)
The plot interval for the default geometric plot of the curve.
Parameters parameter : str or Symbol, optional
Default value is ‘t’; otherwise the provided symbol is used.
Returns plot_interval : list (plot interval)
[parameter, lower_bound, upper_bound]
See also:

limits (page 633) Returns limits of the parameter interval

Examples

>>> from sympy import Curve, sin

>>> from sympy.abc import x, t, s
>>> Curve((x, sin(x)), (x, 1, 2)).plot_interval()
[t, 1, 2]
>>> Curve((x, sin(x)), (x, 1, 2)).plot_interval(s)
[s, 1, 2]

rotate(angle=0, pt=None)
Rotate angle radians counterclockwise about Point pt.
The default pt is the origin, Point(0, 0).

Examples

>>> from sympy.geometry.curve import Curve

>>> from sympy.abc import x
>>> from sympy import pi
>>> Curve((x, x), (x, 0, 1)).rotate(pi/2)
Curve((-x, x), (x, 0, 1))

scale(x=1, y=1, pt=None)

Override GeometryEntity.scale since Curve is not made up of Points.

Examples

>>> from sympy.geometry.curve import Curve

>>> from sympy import pi
>>> from sympy.abc import x
(continues on next page)

634 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> Curve((x, x), (x, 0, 1)).scale(2)
Curve((2*x, x), (x, 0, 1))

translate(x=0, y=0)
Translate the Curve by (x, y).

Examples

>>> from sympy.geometry.curve import Curve

>>> from sympy import pi
>>> from sympy.abc import x
>>> Curve((x, x), (x, 0, 1)).translate(1, 2)
Curve((x + 1, x + 2), (x, 0, 1))

Ellipses

class sympy.geometry.ellipse.Ellipse
An elliptical GeometryEntity.
Parameters center : Point, optional
Default value is Point(0, 0)
hradius : number or SymPy expression, optional
vradius : number or SymPy expression, optional
eccentricity : number or SymPy expression, optional
Two of hradius, vradius and eccentricity must be supplied to create an
Ellipse. The third is derived from the two supplied.
Raises GeometryError
When hradius, vradius and eccentricity are incorrectly supplied as pa-
rameters.
TypeError
When center is not a Point.
See also:
Circle (page 647)

Notes

Constructed from a center and two radii, the first being the horizontal radius (along the
x-axis) and the second being the vertical radius (along the y-axis).
When symbolic value for hradius and vradius are used, any calculation that refers to the
foci or the major or minor axis will assume that the ellipse has its major radius on the
x-axis. If this is not true then a manual rotation is necessary.

5.11. Geometry Module 635

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Ellipse, Point, Rational

>>> e1 = Ellipse(Point(0, 0), 5, 1)
>>> e1.hradius, e1.vradius
(5, 1)
>>> e2 = Ellipse(Point(3, 1), hradius=3, eccentricity=Rational(4, 5))
>>> e2
Ellipse(Point2D(3, 1), 3, 9/5)

Attributes

center
hradius
vradius
area
circumference
eccentricity
periapsis
apoapsis
focus_distance
foci

apoapsis
The apoapsis of the ellipse.
The greatest distance between the focus and the contour.
Returns apoapsis : number
See also:

periapsis (page 643) Returns shortest distance between foci and contour

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.apoapsis
2*sqrt(2) + 3

arbitrary_point(parameter=’t’)
A parameterized point on the ellipse.
Parameters parameter : str, optional
Default value is ‘t’.
Returns arbitrary_point : Point
Raises ValueError
When parameter already appears in the functions.

636 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Ellipse

>>> e1 = Ellipse(Point(0, 0), 3, 2)
>>> e1.arbitrary_point()
Point2D(3*cos(t), 2*sin(t))

area
The area of the ellipse.
Returns area : number

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.area
3*pi

bounds
Return a tuple (xmin, ymin, xmax, ymax) representing the bounding rectangle for
the geometric figure.
center
The center of the ellipse.
Returns center : number
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.center
Point2D(0, 0)

circumference
The circumference of the ellipse.

Examples

5.11. Geometry Module 637

SymPy Documentation, Release 1.3

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.circumference
12*elliptic_e(8/9)

eccentricity
The eccentricity of the ellipse.
Returns eccentricity : number

Examples

>>> from sympy import Point, Ellipse, sqrt

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, sqrt(2))
>>> e1.eccentricity
sqrt(7)/3

encloses_point(p)
Return True if p is enclosed by (is inside of) self.
Parameters p : Point
Returns encloses_point : True, False or None
See also:
sympy.geometry.point.Point (page 590)

Notes

Being on the border of self is considered False.

Examples

>>> from sympy import Ellipse, S

>>> from sympy.abc import t
>>> e = Ellipse((0, 0), 3, 2)
>>> e.encloses_point((0, 0))
True
>>> e.encloses_point(e.arbitrary_point(t).subs(t, S.Half))
False
>>> e.encloses_point((4, 0))
False

equation(x=’x’, y=’y’)
The equation of the ellipse.
Parameters x : str, optional
Label for the x-axis. Default value is ‘x’.
y : str, optional
Label for the y-axis. Default value is ‘y’.

638 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns equation : sympy expression

See also:

arbitrary_point (page 636) Returns parameterized point on ellipse

Examples

>>> from sympy import Point, Ellipse

>>> e1 = Ellipse(Point(1, 0), 3, 2)
>>> e1.equation()
y**2/4 + (x/3 - 1/3)**2 - 1

evolute(x=’x’, y=’y’)
The equation of evolute of the ellipse.
Parameters x : str, optional
Label for the x-axis. Default value is ‘x’.
y : str, optional
Label for the y-axis. Default value is ‘y’.
Returns equation : sympy expression

Examples

>>> from sympy import Point, Ellipse

>>> e1 = Ellipse(Point(1, 0), 3, 2)
>>> e1.evolute()
2**(2/3)*y**(2/3) + (3*x - 3)**(2/3) - 5**(2/3)

foci
The foci of the ellipse.
Raises ValueError
When the major and minor axis cannot be determined.
See also:
sympy.geometry.point.Point (page 590)
focus_distance (page 640) Returns the distance between focus and center

Notes

The foci can only be calculated if the major/minor axes are known.

Examples

5.11. Geometry Module 639

SymPy Documentation, Release 1.3

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.foci
(Point2D(-2*sqrt(2), 0), Point2D(2*sqrt(2), 0))

focus_distance
The focal distance of the ellipse.
The distance between the center and one focus.
Returns focus_distance : number
See also:
foci (page 639)

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.focus_distance
2*sqrt(2)

hradius
The horizontal radius of the ellipse.
Returns hradius : number
See also:
vradius (page 647), major (page 641), minor (page 642)

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.hradius
3

intersection(o)
The intersection of this ellipse and another geometrical entity o.
Parameters o : GeometryEntity
Returns intersection : list of GeometryEntity objects
See also:
sympy.geometry.entity.GeometryEntity (page 584)

Notes

Currently supports intersections with Point, Line, Segment, Ray, Circle and Ellipse
types.

640 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Ellipse, Point, Line, sqrt

>>> e = Ellipse(Point(0, 0), 5, 7)
>>> e.intersection(Point(0, 0))
[]
>>> e.intersection(Point(5, 0))
[Point2D(5, 0)]
>>> e.intersection(Line(Point(0,0), Point(0, 1)))
[Point2D(0, -7), Point2D(0, 7)]
>>> e.intersection(Line(Point(5,0), Point(5, 1)))
[Point2D(5, 0)]
>>> e.intersection(Line(Point(6,0), Point(6, 1)))
[]
>>> e = Ellipse(Point(-1, 0), 4, 3)
>>> e.intersection(Ellipse(Point(1, 0), 4, 3))
[Point2D(0, -3*sqrt(15)/4), Point2D(0, 3*sqrt(15)/4)]
>>> e.intersection(Ellipse(Point(5, 0), 4, 3))
[Point2D(2, -3*sqrt(7)/4), Point2D(2, 3*sqrt(7)/4)]
>>> e.intersection(Ellipse(Point(100500, 0), 4, 3))
[]
>>> e.intersection(Ellipse(Point(0, 0), 3, 4))
[Point2D(3, 0), Point2D(-363/175, -48*sqrt(111)/175), Point2D(-363/175,␣
,→48*sqrt(111)/175)]

>>> e.intersection(Ellipse(Point(-1, 0), 3, 4))

[Point2D(-17/5, -12/5), Point2D(-17/5, 12/5), Point2D(7/5, -12/5), Point2D(7/
,→5, 12/5)]

is_tangent(o)
Is o tangent to the ellipse?
Parameters o : GeometryEntity
An Ellipse, LinearEntity or Polygon
Returns is_tangent: boolean
True if o is tangent to the ellipse, False otherwise.
Raises NotImplementedError
When the wrong type of argument is supplied.
See also:
tangent_lines (page 646)

Examples

>>> from sympy import Point, Ellipse, Line

>>> p0, p1, p2 = Point(0, 0), Point(3, 0), Point(3, 3)
>>> e1 = Ellipse(p0, 3, 2)
>>> l1 = Line(p1, p2)
>>> e1.is_tangent(l1)
True

major
Longer axis of the ellipse (if it can be determined) else hradius.

5.11. Geometry Module 641

SymPy Documentation, Release 1.3

Returns major : number or expression

See also:
hradius (page 640), vradius (page 647), minor (page 642)

Examples

>>> from sympy import Point, Ellipse, Symbol

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.major
3

>>> a = Symbol('a')
>>> b = Symbol('b')
>>> Ellipse(p1, a, b).major
a
>>> Ellipse(p1, b, a).major
b

>>> m = Symbol('m')
>>> M = m + 1
>>> Ellipse(p1, m, M).major
m + 1

minor
Shorter axis of the ellipse (if it can be determined) else vradius.
Returns minor : number or expression
See also:
hradius (page 640), vradius (page 647), major (page 641)

Examples

>>> from sympy import Point, Ellipse, Symbol

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.minor
1

>>> a = Symbol('a')
>>> b = Symbol('b')
>>> Ellipse(p1, a, b).minor
b
>>> Ellipse(p1, b, a).minor
a

>>> m = Symbol('m')
>>> M = m + 1
>>> Ellipse(p1, m, M).minor
m

642 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

normal_lines(p, prec=None)
Normal lines between p and the ellipse.
Parameters p : Point
Returns normal_lines : list with 1, 2 or 4 Lines

Examples

>>> from sympy import Line, Point, Ellipse

>>> e = Ellipse((0, 0), 2, 3)
>>> c = e.center
>>> e.normal_lines(c + Point(1, 0))
[Line2D(Point2D(0, 0), Point2D(1, 0))]
>>> e.normal_lines(c)
[Line2D(Point2D(0, 0), Point2D(0, 1)), Line2D(Point2D(0, 0), Point2D(1, 0))]

Off-axis points require the solution of a quartic equation. This often leads to very
large expressions that may be of little practical use. An approximate solution of prec
digits can be obtained by passing in the desired value:

>>> e.normal_lines((3, 3), prec=2)

[Line2D(Point2D(-0.81, -2.7), Point2D(0.19, -1.2)),
Line2D(Point2D(1.5, -2.0), Point2D(2.5, -2.7))]

Whereas the above solution has an operation count of 12, the exact solution has an
operation count of 2020.
periapsis
The periapsis of the ellipse.
The shortest distance between the focus and the contour.
Returns periapsis : number
See also:

apoapsis (page 636) Returns greatest distance between focus and contour

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.periapsis
-2*sqrt(2) + 3

plot_interval(parameter=’t’)
The plot interval for the default geometric plot of the Ellipse.
Parameters parameter : str, optional
Default value is ‘t’.
Returns plot_interval : list
[parameter, lower_bound, upper_bound]

5.11. Geometry Module 643

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Ellipse

>>> e1 = Ellipse(Point(0, 0), 3, 2)
>>> e1.plot_interval()
[t, -pi, pi]

random_point(seed=None)
A random point on the ellipse.
Returns point : Point
See also:
sympy.geometry.point.Point (page 590)
arbitrary_point (page 636) Returns parameterized point on ellipse

Notes

When creating a random point, one may simply replace the parameter with a random
number. When doing so, however, the random number should be made a Rational
or else the point may not test as being in the ellipse:

>>> from sympy.abc import t

>>> from sympy import Rational
>>> arb = e1.arbitrary_point(t); arb
Point2D(3*cos(t), 2*sin(t))
>>> arb.subs(t, .1) in e1
False
>>> arb.subs(t, Rational(.1)) in e1
True
>>> arb.subs(t, Rational('.1')) in e1
True

Examples

>>> from sympy import Point, Ellipse, Segment

>>> e1 = Ellipse(Point(0, 0), 3, 2)
>>> e1.random_point() # gives some random point
Point2D(...)
>>> p1 = e1.random_point(seed=0); p1.n(2)
Point2D(2.1, 1.4)

reflect(line)
Override GeometryEntity.reflect since the radius is not a GeometryEntity.

Notes

Until the general ellipse (with no axis parallel to the x-axis) is supported a NotIm-
plemented error is raised and the equation whose zeros define the rotated ellipse is
given.

644 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Circle, Line

>>> Circle((0, 1), 1).reflect(Line((0, 0), (1, 1)))
Circle(Point2D(1, 0), -1)
>>> from sympy import Ellipse, Line, Point
>>> Ellipse(Point(3, 4), 1, 3).reflect(Line(Point(0, -4), Point(5, 0)))
Traceback (most recent call last):
...
NotImplementedError:
General Ellipse is not supported but the equation of the reflected
Ellipse is given by the zeros of: f(x, y) = (9*x/41 + 40*y/41 +
37/41)**2 + (40*x/123 - 3*y/41 - 364/123)**2 - 1

rotate(angle=0, pt=None)
Rotate angle radians counterclockwise about Point pt.
Note: since the general ellipse is not supported, only rotations that are integer
multiples of pi/2 are allowed.

Examples

>>> from sympy import Ellipse, pi

>>> Ellipse((1, 0), 2, 1).rotate(pi/2)
Ellipse(Point2D(0, 1), 1, 2)
>>> Ellipse((1, 0), 2, 1).rotate(pi)
Ellipse(Point2D(-1, 0), 2, 1)

scale(x=1, y=1, pt=None)

Override GeometryEntity.scale since it is the major and minor axes which must be
scaled and they are not GeometryEntities.

Examples

>>> from sympy import Ellipse

>>> Ellipse((0, 0), 2, 1).scale(2, 4)
Circle(Point2D(0, 0), 4)
>>> Ellipse((0, 0), 2, 1).scale(2)
Ellipse(Point2D(0, 0), 4, 1)

second_moment_of_area(point=None)
Returns the second moment and product moment area of an ellipse.
Parameters point : Point, two-tuple of sympifiable objects, or
None(default=None)
point is the point about which second moment of area is to be found.
If “point=None” it will be calculated about the axis passing through
the centroid of the ellipse.
Returns I_xx, I_yy, I_xy : number or sympy expression
I_xx, I_yy are second moment of area of an ellise. I_xy is product
moment of area of an ellipse.

5.11. Geometry Module 645

SymPy Documentation, Release 1.3

References

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

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.second_moment_of_area()
(3*pi/4, 27*pi/4, 0)

semilatus_rectum
Calculates the semi-latus rectum of the Ellipse.
Semi-latus rectum is defined as one half of the the chord through a focus parallel to
the conic section directrix of a conic section.
Returns semilatus_rectum : number
See also:

apoapsis (page 636) Returns greatest distance between focus and contour
periapsis (page 643) The shortest distance between the focus and the contour

References

[1] http://mathworld.wolfram.com/SemilatusRectum.html [2] https://en.wikipedia.

org/wiki/Ellipse#Semi-latus_rectum

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.semilatus_rectum
1/3

tangent_lines(p)
Tangent lines between p and the ellipse.
If p is on the ellipse, returns the tangent line through point p. Otherwise, returns
the tangent line(s) from p to the ellipse, or None if no tangent line is possible (e.g.,
p inside ellipse).
Parameters p : Point
Returns tangent_lines : list with 1 or 2 Lines
Raises NotImplementedError
Can only find tangent lines for a point, p, on the ellipse.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Line (page 612)

646 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Ellipse

>>> e1 = Ellipse(Point(0, 0), 3, 2)
>>> e1.tangent_lines(Point(3, 0))
[Line2D(Point2D(3, 0), Point2D(3, -12))]

vradius
The vertical radius of the ellipse.
Returns vradius : number
See also:
hradius (page 640), major (page 641), minor (page 642)

Examples

>>> from sympy import Point, Ellipse

>>> p1 = Point(0, 0)
>>> e1 = Ellipse(p1, 3, 1)
>>> e1.vradius
1

class sympy.geometry.ellipse.Circle
A circle in space.
Constructed simply from a center and a radius, or from three non-collinear points.
Parameters center : Point
radius : number or sympy expression
points : sequence of three Points
Raises GeometryError
When trying to construct circle from three collinear points. When
trying to construct circle from incorrect parameters.
See also:
Ellipse (page 635), sympy.geometry.point.Point (page 590)

Examples

>>> from sympy.geometry import Point, Circle

>>> # a circle constructed from a center and radius
>>> c1 = Circle(Point(0, 0), 5)
>>> c1.hradius, c1.vradius, c1.radius
(5, 5, 5)

>>> # a circle constructed from three points

>>> c2 = Circle(Point(0, 0), Point(1, 1), Point(1, 0))
>>> c2.hradius, c2.vradius, c2.radius, c2.center
(sqrt(2)/2, sqrt(2)/2, sqrt(2)/2, Point2D(1/2, 1/2))

5.11. Geometry Module 647

SymPy Documentation, Release 1.3

Attributes

radius (synonymous with hradius, vradius, major and minor)

circumference
equation

circumference
The circumference of the circle.
Returns circumference : number or SymPy expression

Examples

>>> from sympy import Point, Circle

>>> c1 = Circle(Point(3, 4), 6)
>>> c1.circumference
12*pi

equation(x=’x’, y=’y’)
The equation of the circle.
Parameters x : str or Symbol, optional
Default value is ‘x’.
y : str or Symbol, optional
Default value is ‘y’.
Returns equation : SymPy expression

Examples

>>> from sympy import Point, Circle

>>> c1 = Circle(Point(0, 0), 5)
>>> c1.equation()
x**2 + y**2 - 25

intersection(o)
The intersection of this circle with another geometrical entity.
Parameters o : GeometryEntity
Returns intersection : list of GeometryEntities

Examples

>>> from sympy import Point, Circle, Line, Ray

>>> p1, p2, p3 = Point(0, 0), Point(5, 5), Point(6, 0)
>>> p4 = Point(5, 0)
>>> c1 = Circle(p1, 5)
>>> c1.intersection(p2)
[]
(continues on next page)

648 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> c1.intersection(p4)
[Point2D(5, 0)]
>>> c1.intersection(Ray(p1, p2))
[Point2D(5*sqrt(2)/2, 5*sqrt(2)/2)]
>>> c1.intersection(Line(p2, p3))
[]

radius
The radius of the circle.
Returns radius : number or sympy expression
See also:
Ellipse.major (page 641), Ellipse.minor (page 642), Ellipse.hradius
(page 640), Ellipse.vradius (page 647)

Examples

>>> from sympy import Point, Circle

>>> c1 = Circle(Point(3, 4), 6)
>>> c1.radius
6

reflect(line)
Override GeometryEntity.reflect since the radius is not a GeometryEntity.

Examples

>>> from sympy import Circle, Line

>>> Circle((0, 1), 1).reflect(Line((0, 0), (1, 1)))
Circle(Point2D(1, 0), -1)

scale(x=1, y=1, pt=None)

Override GeometryEntity.scale since the radius is not a GeometryEntity.

Examples

>>> from sympy import Circle

>>> Circle((0, 0), 1).scale(2, 2)
Circle(Point2D(0, 0), 2)
>>> Circle((0, 0), 1).scale(2, 4)
Ellipse(Point2D(0, 0), 2, 4)

vradius
This Ellipse property is an alias for the Circle’s radius.
Whereas hradius, major and minor can use Ellipse’s conventions, the vradius does
not exist for a circle. It is always a positive value in order that the Circle, like
Polygons, will have an area that can be positive or negative as determined by the
sign of the hradius.

5.11. Geometry Module 649

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point, Circle

>>> c1 = Circle(Point(3, 4), 6)
>>> c1.vradius
6

Polygons

class sympy.geometry.polygon.Polygon
A two-dimensional polygon.
A simple polygon in space. Can be constructed from a sequence of points or from a
center, radius, number of sides and rotation angle.
Parameters vertices : sequence of Points
Raises GeometryError
If all parameters are not Points.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment (page 617),
Triangle (page 665)

Notes

Polygons are treated as closed paths rather than 2D areas so some calculations can be
be negative or positive (e.g., area) based on the orientation of the points.
Any consecutive identical points are reduced to a single point and any points collinear
and between two points will be removed unless they are needed to define an explicit
intersection (see examples).
A Triangle, Segment or Point will be returned when there are 3 or fewer points provided.

Examples

>>> from sympy import Point, Polygon, pi

>>> p1, p2, p3, p4, p5 = [(0, 0), (1, 0), (5, 1), (0, 1), (3, 0)]
>>> Polygon(p1, p2, p3, p4)
Polygon(Point2D(0, 0), Point2D(1, 0), Point2D(5, 1), Point2D(0, 1))
>>> Polygon(p1, p2)
Segment2D(Point2D(0, 0), Point2D(1, 0))
>>> Polygon(p1, p2, p5)
Segment2D(Point2D(0, 0), Point2D(3, 0))

The area of a polygon is calculated as positive when vertices are traversed in a ccw
direction. When the sides of a polygon cross the area will have positive and negative
contributions. The following defines a Z shape where the bottom right connects back to
the top left.

650 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Polygon((0, 2), (2, 2), (0, 0), (2, 0)).area

0

When the the keyword n is used to define the number of sides of the Polygon then a
RegularPolygon is created and the other arguments are interpreted as center, radius and
rotation. The unrotated RegularPolygon will always have a vertex at Point(r, 0) where r
is the radius of the circle that circumscribes the RegularPolygon. Its method spin can be
used to increment that angle.

>>> p = Polygon((0,0), 1, n=3)

>>> p
RegularPolygon(Point2D(0, 0), 1, 3, 0)
>>> p.vertices[0]
Point2D(1, 0)
>>> p.args[0]
Point2D(0, 0)
>>> p.spin(pi/2)
>>> p.vertices[0]
Point2D(0, 1)

Attributes

area
angles
perimeter
vertices
centroid
sides

angles
The internal angle at each vertex.
Returns angles : dict
A dictionary where each key is a vertex and each value is the internal
angle at that vertex. The vertices are represented as Points.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.LinearEntity.
angle_between (page 603)

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.angles[p1]
pi/2
>>> poly.angles[p2]
acos(-4*sqrt(17)/17)

5.11. Geometry Module 651

SymPy Documentation, Release 1.3

arbitrary_point(parameter=’t’)
A parameterized point on the polygon.
The parameter, varying from 0 to 1, assigns points to the position on the perimeter
that is that fraction of the total perimeter. So the point evaluated at t=1/2 would
return the point from the first vertex that is 1/2 way around the polygon.
Parameters parameter : str, optional
Default value is ‘t’.
Returns arbitrary_point : Point
Raises ValueError
When parameter already appears in the Polygon’s definition.
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy import Polygon, S, Symbol

>>> t = Symbol('t', real=True)
>>> tri = Polygon((0, 0), (1, 0), (1, 1))
>>> p = tri.arbitrary_point('t')
>>> perimeter = tri.perimeter
>>> s1, s2 = [s.length for s in tri.sides[:2]]
>>> p.subs(t, (s1 + s2/2)/perimeter)
Point2D(1, 1/2)

area
The area of the polygon.
See also:
sympy.geometry.ellipse.Ellipse.area (page 637)

Notes

The area calculation can be positive or negative based on the orientation of the
points. If any side of the polygon crosses any other side, there will be areas having
opposite signs.

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.area
3

In the Z shaped polygon (with the lower right connecting back to the upper left) the
areas cancel out:

652 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Z = Polygon((0, 1), (1, 1), (0, 0), (1, 0))

>>> Z.area
0

In the M shaped polygon, areas do not cancel because no side crosses any other
(though there is a point of contact).

>>> M = Polygon((0, 0), (0, 1), (2, 0), (3, 1), (3, 0))
>>> M.area
-3/2

bounds
Return a tuple (xmin, ymin, xmax, ymax) representing the bounding rectangle for
the geometric figure.
centroid
The centroid of the polygon.
Returns centroid : Point
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.util.centroid
(page 589)

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.centroid
Point2D(31/18, 11/18)

distance(o)
Returns the shortest distance between self and o.
If o is a point, then self does not need to be convex. If o is another polygon self and
o must be complex.

Examples

>>> from sympy import Point, Polygon, RegularPolygon

>>> p1, p2 = map(Point, [(0, 0), (7, 5)])
>>> poly = Polygon(*RegularPolygon(p1, 1, 3).vertices)
>>> poly.distance(p2)
sqrt(61)

encloses_point(p)
Return True if p is enclosed by (is inside of) self.
Parameters p : Point
Returns encloses_point : True, False or None
See also:

5.11. Geometry Module 653

SymPy Documentation, Release 1.3

sympy.geometry.point.Point (page 590), sympy.geometry.ellipse.Ellipse.

encloses_point (page 638)

Notes

Being on the border of self is considered False.

References

[1] http://paulbourke.net/geometry/polygonmesh/#insidepoly

Examples

>>> from sympy import Polygon, Point

>>> from sympy.abc import t
>>> p = Polygon((0, 0), (4, 0), (4, 4))
>>> p.encloses_point(Point(2, 1))
True
>>> p.encloses_point(Point(2, 2))
False
>>> p.encloses_point(Point(5, 5))
False

intersection(o)
The intersection of polygon and geometry entity.
The intersection may be empty and can contain individual Points and complete Line
Segments.
Parameters other: GeometryEntity
Returns intersection : list
The list of Segments and Points
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment
(page 617)

Examples

>>> from sympy import Point, Polygon, Line

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly1 = Polygon(p1, p2, p3, p4)
>>> p5, p6, p7 = map(Point, [(3, 2), (1, -1), (0, 2)])
>>> poly2 = Polygon(p5, p6, p7)
>>> poly1.intersection(poly2)
[Point2D(1/3, 1), Point2D(2/3, 0), Point2D(9/5, 1/5), Point2D(7/3, 1)]
>>> poly1.intersection(Line(p1, p2))
[Segment2D(Point2D(0, 0), Point2D(1, 0))]
>>> poly1.intersection(p1)
[Point2D(0, 0)]

654 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

is_convex()
Is the polygon convex?
A polygon is convex if all its interior angles are less than 180 degrees and there are
no intersections between sides.
Returns is_convex : boolean
True if this polygon is convex, False otherwise.
See also:
sympy.geometry.util.convex_hull (page 587)

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.is_convex()
True

perimeter
The perimeter of the polygon.
Returns perimeter : number or Basic instance
See also:
sympy.geometry.line.Segment.length (page 619)

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.perimeter
sqrt(17) + 7

plot_interval(parameter=’t’)
The plot interval for the default geometric plot of the polygon.
Parameters parameter : str, optional
Default value is ‘t’.
Returns plot_interval : list (plot interval)
[parameter, lower_bound, upper_bound]

Examples

>>> from sympy import Polygon

>>> p = Polygon((0, 0), (1, 0), (1, 1))
>>> p.plot_interval()
[t, 0, 1]

5.11. Geometry Module 655

SymPy Documentation, Release 1.3

second_moment_of_area(point=None)
Returns the second moment and product moment of area of a two dimensional poly-
gon.
Parameters point : Point, two-tuple of sympifiable objects, or
None(default=None)
point is the point about which second moment of area is to be found.
If “point=None” it will be calculated about the axis passing through
the centroid of the polygon.
Returns I_xx, I_yy, I_xy : number or sympy expression
I_xx, I_yy are second moment of area of a two dimensional polygon.
I_xy is product moment of area of a two dimensional polygon.

References

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

Examples

>>> from sympy import Point, Polygon, symbols

>>> a, b = symbols('a, b')
>>> p1, p2, p3, p4, p5 = [(0, 0), (a, 0), (a, b), (0, b), (a/3, b/3)]
>>> rectangle = Polygon(p1, p2, p3, p4)
>>> rectangle.second_moment_of_area()
(a*b**3/12, a**3*b/12, 0)
>>> rectangle.second_moment_of_area(p5)
(a*b**3/9, a**3*b/9, a**2*b**2/36)

sides
The directed line segments that form the sides of the polygon.
Returns sides : list of sides
Each side is a directed Segment.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment
(page 617)

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.sides
[Segment2D(Point2D(0, 0), Point2D(1, 0)),
Segment2D(Point2D(1, 0), Point2D(5, 1)),
Segment2D(Point2D(5, 1), Point2D(0, 1)), Segment2D(Point2D(0, 1), Point2D(0,␣
,→0))]

vertices
The vertices of the polygon.

656 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns vertices : list of Points

See also:
sympy.geometry.point.Point (page 590)

Notes

When iterating over the vertices, it is more efficient to index self rather than to
request the vertices and index them. Only use the vertices when you want to process
all of them at once. This is even more important with RegularPolygons that calculate
each vertex.

Examples

>>> from sympy import Point, Polygon

>>> p1, p2, p3, p4 = map(Point, [(0, 0), (1, 0), (5, 1), (0, 1)])
>>> poly = Polygon(p1, p2, p3, p4)
>>> poly.vertices
[Point2D(0, 0), Point2D(1, 0), Point2D(5, 1), Point2D(0, 1)]
>>> poly.vertices[0]
Point2D(0, 0)

class sympy.geometry.polygon.RegularPolygon
A regular polygon.
Such a polygon has all internal angles equal and all sides the same length.
Parameters center : Point
radius : number or Basic instance
The distance from the center to a vertex
n : int
The number of sides
Raises GeometryError
If the center is not a Point, or the radius is not a number or Basic
instance, or the number of sides, n, is less than three.
See also:
sympy.geometry.point.Point (page 590), Polygon (page 650)

Notes

A RegularPolygon can be instantiated with Polygon with the kwarg n.

Regular polygons are instantiated with a center, radius, number of sides and a rotation
angle. Whereas the arguments of a Polygon are vertices, the vertices of the Regular-
Polygon must be obtained with the vertices method.

5.11. Geometry Module 657

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> r = RegularPolygon(Point(0, 0), 5, 3)
>>> r
RegularPolygon(Point2D(0, 0), 5, 3, 0)
>>> r.vertices[0]
Point2D(5, 0)

Attributes

vertices
center
radius
rotation
apothem
interior_angle
exterior_angle
circumcircle
incircle
angles

angles
Returns a dictionary with keys, the vertices of the Polygon, and values, the interior
angle at each vertex.

Examples

>>> from sympy import RegularPolygon, Point

>>> r = RegularPolygon(Point(0, 0), 5, 3)
>>> r.angles
{Point2D(-5/2, -5*sqrt(3)/2): pi/3,
Point2D(-5/2, 5*sqrt(3)/2): pi/3,
Point2D(5, 0): pi/3}

apothem
The inradius of the RegularPolygon.
The apothem/inradius is the radius of the inscribed circle.
Returns apothem : number or instance of Basic
See also:
sympy.geometry.line.Segment.length (page 619), sympy.geometry.ellipse.
Circle.radius (page 649)

Examples

658 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Symbol

>>> from sympy.geometry import RegularPolygon, Point
>>> radius = Symbol('r')
>>> rp = RegularPolygon(Point(0, 0), radius, 4)
>>> rp.apothem
sqrt(2)*r/2

area
Returns the area.

Examples

>>> from sympy.geometry import RegularPolygon

>>> square = RegularPolygon((0, 0), 1, 4)
>>> square.area
2
>>> _ == square.length**2
True

args
Returns the center point, the radius, the number of sides, and the orientation angle.

Examples

>>> from sympy import RegularPolygon, Point

>>> r = RegularPolygon(Point(0, 0), 5, 3)
>>> r.args
(Point2D(0, 0), 5, 3, 0)

center
The center of the RegularPolygon
This is also the center of the circumscribing circle.
Returns center : Point
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.ellipse.Ellipse.
center (page 637)

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 5, 4)
>>> rp.center
Point2D(0, 0)

centroid
The center of the RegularPolygon
This is also the center of the circumscribing circle.
Returns center : Point

5.11. Geometry Module 659

SymPy Documentation, Release 1.3

See also:
sympy.geometry.point.Point (page 590), sympy.geometry.ellipse.Ellipse.
center (page 637)

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 5, 4)
>>> rp.center
Point2D(0, 0)

circumcenter
Alias for center.

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 5, 4)
>>> rp.circumcenter
Point2D(0, 0)

circumcircle
The circumcircle of the RegularPolygon.
Returns circumcircle : Circle
See also:
circumcenter (page 660), sympy.geometry.ellipse.Circle (page 647)

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 4, 8)
>>> rp.circumcircle
Circle(Point2D(0, 0), 4)

circumradius
Alias for radius.

Examples

>>> from sympy import Symbol

>>> from sympy.geometry import RegularPolygon, Point
>>> radius = Symbol('r')
>>> rp = RegularPolygon(Point(0, 0), radius, 4)
>>> rp.circumradius
r

encloses_point(p)
Return True if p is enclosed by (is inside of) self.

660 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters p : Point
Returns encloses_point : True, False or None
See also:
sympy.geometry.ellipse.Ellipse.encloses_point (page 638)

Notes

Being on the border of self is considered False.

The general Polygon.encloses_point method is called only if a point is not within or
beyond the incircle or circumcircle, respectively.

Examples

>>> from sympy import RegularPolygon, S, Point, Symbol

>>> p = RegularPolygon((0, 0), 3, 4)
>>> p.encloses_point(Point(0, 0))
True
>>> r, R = p.inradius, p.circumradius
>>> p.encloses_point(Point((r + R)/2, 0))
True
>>> p.encloses_point(Point(R/2, R/2 + (R - r)/10))
False
>>> t = Symbol('t', real=True)
>>> p.encloses_point(p.arbitrary_point().subs(t, S.Half))
False
>>> p.encloses_point(Point(5, 5))
False

exterior_angle
Measure of the exterior angles.
Returns exterior_angle : number
See also:
sympy.geometry.line.LinearEntity.angle_between (page 603)

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 4, 8)
>>> rp.exterior_angle
pi/4

incircle
The incircle of the RegularPolygon.
Returns incircle : Circle
See also:
inradius (page 662), sympy.geometry.ellipse.Circle (page 647)

5.11. Geometry Module 661

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 4, 7)
>>> rp.incircle
Circle(Point2D(0, 0), 4*cos(pi/7))

inradius
Alias for apothem.

Examples

>>> from sympy import Symbol

>>> from sympy.geometry import RegularPolygon, Point
>>> radius = Symbol('r')
>>> rp = RegularPolygon(Point(0, 0), radius, 4)
>>> rp.inradius
sqrt(2)*r/2

interior_angle
Measure of the interior angles.
Returns interior_angle : number
See also:
sympy.geometry.line.LinearEntity.angle_between (page 603)

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 4, 8)
>>> rp.interior_angle
3*pi/4

length
Returns the length of the sides.
The half-length of the side and the apothem form two legs of a right triangle whose
hypotenuse is the radius of the regular polygon.

Examples

>>> from sympy.geometry import RegularPolygon

>>> from sympy import sqrt
>>> s = square_in_unit_circle = RegularPolygon((0, 0), 1, 4)
>>> s.length
sqrt(2)
>>> sqrt((_/2)**2 + s.apothem**2) == s.radius
True

radius
Radius of the RegularPolygon

662 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

This is also the radius of the circumscribing circle.

Returns radius : number or instance of Basic
See also:
sympy.geometry.line.Segment.length (page 619), sympy.geometry.ellipse.
Circle.radius (page 649)

Examples

>>> from sympy import Symbol

>>> from sympy.geometry import RegularPolygon, Point
>>> radius = Symbol('r')
>>> rp = RegularPolygon(Point(0, 0), radius, 4)
>>> rp.radius
r

reflect(line)
Override GeometryEntity.reflect since this is not made of only points.

Examples

>>> from sympy import RegularPolygon, Line

>>> RegularPolygon((0, 0), 1, 4).reflect(Line((0, 1), slope=-2))

RegularPolygon(Point2D(4/5, 2/5), -1, 4, atan(4/3))

rotate(angle, pt=None)
Override GeometryEntity.rotate to first rotate the RegularPolygon about its center.

>>> from sympy import Point, RegularPolygon, Polygon, pi

>>> t = RegularPolygon(Point(1, 0), 1, 3)
>>> t.vertices[0] # vertex on x-axis
Point2D(2, 0)
>>> t.rotate(pi/2).vertices[0] # vertex on y axis now
Point2D(0, 2)

See also:
rotation (page 663)
spin (page 664) Rotates a RegularPolygon in place
rotation
CCW angle by which the RegularPolygon is rotated
Returns rotation : number or instance of Basic

Examples

5.11. Geometry Module 663

SymPy Documentation, Release 1.3

>>> from sympy import pi

>>> from sympy.abc import a
>>> from sympy.geometry import RegularPolygon, Point
>>> RegularPolygon(Point(0, 0), 3, 4, pi/4).rotation
pi/4

Numerical rotation angles are made canonical:

>>> RegularPolygon(Point(0, 0), 3, 4, a).rotation

a
>>> RegularPolygon(Point(0, 0), 3, 4, pi).rotation
0

scale(x=1, y=1, pt=None)

Override GeometryEntity.scale since it is the radius that must be scaled (if x == y)
or else a new Polygon must be returned.

>>> from sympy import RegularPolygon

Symmetric scaling returns a RegularPolygon:

>>> RegularPolygon((0, 0), 1, 4).scale(2, 2)

RegularPolygon(Point2D(0, 0), 2, 4, 0)

Asymmetric scaling returns a kite as a Polygon:

>>> RegularPolygon((0, 0), 1, 4).scale(2, 1)

Polygon(Point2D(2, 0), Point2D(0, 1), Point2D(-2, 0), Point2D(0, -1))

spin(angle)
Increment in place the virtual Polygon’s rotation by ccw angle.
See also: rotate method which moves the center.

>>> from sympy import Polygon, Point, pi

>>> r = Polygon(Point(0,0), 1, n=3)
>>> r.vertices[0]
Point2D(1, 0)
>>> r.spin(pi/6)
>>> r.vertices[0]
Point2D(sqrt(3)/2, 1/2)

See also:
rotation (page 663)
rotate (page 663) Creates a copy of the RegularPolygon rotated about a Point
vertices
The vertices of the RegularPolygon.
Returns vertices : list
Each vertex is a Point.
See also:
sympy.geometry.point.Point (page 590)

664 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import RegularPolygon, Point

>>> rp = RegularPolygon(Point(0, 0), 5, 4)
>>> rp.vertices
[Point2D(5, 0), Point2D(0, 5), Point2D(-5, 0), Point2D(0, -5)]

class sympy.geometry.polygon.Triangle
A polygon with three vertices and three sides.
Parameters points : sequence of Points
keyword: asa, sas, or sss to specify sides/angles of the triangle
Raises GeometryError
If the number of vertices is not equal to three, or one of the vertices
is not a Point, or a valid keyword is not given.
See also:
sympy.geometry.point.Point (page 590), Polygon (page 650)

Examples

>>> from sympy.geometry import Triangle, Point

>>> Triangle(Point(0, 0), Point(4, 0), Point(4, 3))
Triangle(Point2D(0, 0), Point2D(4, 0), Point2D(4, 3))

Keywords sss, sas, or asa can be used to give the desired side lengths (in order) and
interior angles (in degrees) that define the triangle:

>>> Triangle(sss=(3, 4, 5))

Triangle(Point2D(0, 0), Point2D(3, 0), Point2D(3, 4))
>>> Triangle(asa=(30, 1, 30))
Triangle(Point2D(0, 0), Point2D(1, 0), Point2D(1/2, sqrt(3)/6))
>>> Triangle(sas=(1, 45, 2))
Triangle(Point2D(0, 0), Point2D(2, 0), Point2D(sqrt(2)/2, sqrt(2)/2))

Attributes

vertices
altitudes
orthocenter
circumcenter
circumradius
circumcircle
inradius
incircle
exradii
medians
medial
nine_point_circle

5.11. Geometry Module 665

SymPy Documentation, Release 1.3

altitudes
The altitudes of the triangle.
An altitude of a triangle is a segment through a vertex, perpendicular to the opposite
side, with length being the height of the vertex measured from the line containing
the side.
Returns altitudes : dict
The dictionary consists of keys which are vertices and values which
are Segments.
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment.length
(page 619)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.altitudes[p1]
Segment2D(Point2D(0, 0), Point2D(1/2, 1/2))

bisectors()
The angle bisectors of the triangle.
An angle bisector of a triangle is a straight line through a vertex which cuts the
corresponding angle in half.
Returns bisectors : dict
Each key is a vertex (Point) and each value is the corresponding bi-
sector (Segment).
See also:
sympy.geometry.point.Point (page 590), sympy.geometry.line.Segment
(page 617)

Examples

>>> from sympy.geometry import Point, Triangle, Segment

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> from sympy import sqrt
>>> t.bisectors()[p2] == Segment(Point(1, 0), Point(0, sqrt(2) - 1))
True

circumcenter
The circumcenter of the triangle
The circumcenter is the center of the circumcircle.
Returns circumcenter : Point

666 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.circumcenter
Point2D(1/2, 1/2)

circumcircle
The circle which passes through the three vertices of the triangle.
Returns circumcircle : Circle
See also:
sympy.geometry.ellipse.Circle (page 647)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.circumcircle
Circle(Point2D(1/2, 1/2), sqrt(2)/2)

circumradius
The radius of the circumcircle of the triangle.
Returns circumradius : number of Basic instance
See also:
sympy.geometry.ellipse.Circle.radius (page 649)

Examples

>>> from sympy import Symbol

>>> from sympy.geometry import Point, Triangle
>>> a = Symbol('a')
>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, a)
>>> t = Triangle(p1, p2, p3)
>>> t.circumradius
sqrt(a**2/4 + 1/4)

eulerline
The Euler line of the triangle.
The line which passes through circumcenter, centroid and orthocenter.
Returns eulerline : Line (or Point for equilateral triangles in which case
all
centers coincide)

5.11. Geometry Module 667

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.eulerline
Line2D(Point2D(0, 0), Point2D(1/2, 1/2))

exradii
The radius of excircles of a triangle.
An excircle of the triangle is a circle lying outside the triangle, tangent to one of its
sides and tangent to the extensions of the other two.
Returns exradii : dict
See also:
sympy.geometry.polygon.Triangle.inradius (page 669)

References

[1] http://mathworld.wolfram.com/Exradius.html [2] http://mathworld.wolfram.com/

Excircles.html

Examples

The exradius touches the side of the triangle to which it is keyed, e.g. the exradius
touching side 2 is:

>>> from sympy.geometry import Point, Triangle, Segment2D, Point2D

>>> p1, p2, p3 = Point(0, 0), Point(6, 0), Point(0, 2)
>>> t = Triangle(p1, p2, p3)
>>> t.exradii[t.sides[2]]
-2 + sqrt(10)

incenter
The center of the incircle.
The incircle is the circle which lies inside the triangle and touches all three sides.
Returns incenter : Point
See also:
incircle (page 668), sympy.geometry.point.Point (page 590)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.incenter
Point2D(-sqrt(2)/2 + 1, -sqrt(2)/2 + 1)

668 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

incircle
The incircle of the triangle.
The incircle is the circle which lies inside the triangle and touches all three sides.
Returns incircle : Circle
See also:
sympy.geometry.ellipse.Circle (page 647)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(2, 0), Point(0, 2)
>>> t = Triangle(p1, p2, p3)
>>> t.incircle
Circle(Point2D(-sqrt(2) + 2, -sqrt(2) + 2), -sqrt(2) + 2)

inradius
The radius of the incircle.
Returns inradius : number of Basic instance
See also:
incircle (page 668), sympy.geometry.ellipse.Circle.radius (page 649)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(4, 0), Point(0, 3)
>>> t = Triangle(p1, p2, p3)
>>> t.inradius
1

is_equilateral()
Are all the sides the same length?
Returns is_equilateral : boolean
See also:
sympy.geometry.entity.GeometryEntity.is_similar (page 585), RegularPoly-
gon (page 657), is_isosceles (page 670), is_right (page 670), is_scalene
(page 670)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t1 = Triangle(Point(0, 0), Point(4, 0), Point(4, 3))
>>> t1.is_equilateral()
False

5.11. Geometry Module 669

SymPy Documentation, Release 1.3

>>> from sympy import sqrt

>>> t2 = Triangle(Point(0, 0), Point(10, 0), Point(5, 5*sqrt(3)))
>>> t2.is_equilateral()
True

is_isosceles()
Are two or more of the sides the same length?
Returns is_isosceles : boolean
See also:
is_equilateral (page 669), is_right (page 670), is_scalene (page 670)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t1 = Triangle(Point(0, 0), Point(4, 0), Point(2, 4))
>>> t1.is_isosceles()
True

is_right()
Is the triangle right-angled.
Returns is_right : boolean
See also:
sympy.geometry.line.LinearEntity.is_perpendicular (page 607),
is_equilateral (page 669), is_isosceles (page 670), is_scalene (page 670)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t1 = Triangle(Point(0, 0), Point(4, 0), Point(4, 3))
>>> t1.is_right()
True

is_scalene()
Are all the sides of the triangle of different lengths?
Returns is_scalene : boolean
See also:
is_equilateral (page 669), is_isosceles (page 670), is_right (page 670)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t1 = Triangle(Point(0, 0), Point(4, 0), Point(1, 4))
>>> t1.is_scalene()
True

670 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

is_similar(t2)
Is another triangle similar to this one.
Two triangles are similar if one can be uniformly scaled to the other.
Parameters other: Triangle
Returns is_similar : boolean
See also:
sympy.geometry.entity.GeometryEntity.is_similar (page 585)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t1 = Triangle(Point(0, 0), Point(4, 0), Point(4, 3))
>>> t2 = Triangle(Point(0, 0), Point(-4, 0), Point(-4, -3))
>>> t1.is_similar(t2)
True

>>> t2 = Triangle(Point(0, 0), Point(-4, 0), Point(-4, -4))

>>> t1.is_similar(t2)
False

medial
The medial triangle of the triangle.
The triangle which is formed from the midpoints of the three sides.
Returns medial : Triangle
See also:
sympy.geometry.line.Segment.midpoint (page 619)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.medial
Triangle(Point2D(1/2, 0), Point2D(1/2, 1/2), Point2D(0, 1/2))

medians
The medians of the triangle.
A median of a triangle is a straight line through a vertex and the midpoint of the
opposite side, and divides the triangle into two equal areas.
Returns medians : dict
Each key is a vertex (Point) and each value is the median (Segment)
at that point.
See also:
sympy.geometry.point.Point.midpoint (page 594), sympy.geometry.line.
Segment.midpoint (page 619)

5.11. Geometry Module 671

SymPy Documentation, Release 1.3

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.medians[p1]
Segment2D(Point2D(0, 0), Point2D(1/2, 1/2))

nine_point_circle
The nine-point circle of the triangle.
Nine-point circle is the circumcircle of the medial triangle, which passes through
the feet of altitudes and the middle points of segments connecting the vertices and
the orthocenter.
Returns nine_point_circle : Circle
See also:
sympy.geometry.line.Segment.midpoint (page 619), sympy.geometry.polygon.
Triangle.medial (page 671), sympy.geometry.polygon.Triangle.orthocenter
(page 672)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.nine_point_circle
Circle(Point2D(1/4, 1/4), sqrt(2)/4)

orthocenter
The orthocenter of the triangle.
The orthocenter is the intersection of the altitudes of a triangle. It may lie inside,
outside or on the triangle.
Returns orthocenter : Point
See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy.geometry import Point, Triangle

>>> p1, p2, p3 = Point(0, 0), Point(1, 0), Point(0, 1)
>>> t = Triangle(p1, p2, p3)
>>> t.orthocenter
Point2D(0, 0)

vertices
The triangle’s vertices
Returns vertices : tuple
Each element in the tuple is a Point

672 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
sympy.geometry.point.Point (page 590)

Examples

>>> from sympy.geometry import Triangle, Point

>>> t = Triangle(Point(0, 0), Point(4, 0), Point(4, 3))
>>> t.vertices
(Point2D(0, 0), Point2D(4, 0), Point2D(4, 3))

Plane

class sympy.geometry.plane.Plane
A plane is a flat, two-dimensional surface. A plane is the two-dimensional analogue of a
point (zero-dimensions), a line (one-dimension) and a solid (three-dimensions). A plane
can generally be constructed by two types of inputs. They are three non-collinear points
and a point and the plane’s normal vector.

Examples

>>> from sympy import Plane, Point3D

>>> from sympy.abc import x
>>> Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
Plane(Point3D(1, 1, 1), (-1, 2, -1))
>>> Plane((1, 1, 1), (2, 3, 4), (2, 2, 2))
Plane(Point3D(1, 1, 1), (-1, 2, -1))
>>> Plane(Point3D(1, 1, 1), normal_vector=(1,4,7))
Plane(Point3D(1, 1, 1), (1, 4, 7))

Attributes

p1
normal_vector

angle_between(o)
Angle between the plane and other geometric entity.
Parameters LinearEntity3D, Plane.
Returns angle : angle in radians

Notes

This method accepts only 3D entities as it’s parameter, but if you want to calculate
the angle between a 2D entity and a plane you should first convert to a 3D entity by
projecting onto a desired plane and then proceed to calculate the angle.

5.11. Geometry Module 673

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Point3D, Line3D, Plane

>>> a = Plane(Point3D(1, 2, 2), normal_vector=(1, 2, 3))
>>> b = Line3D(Point3D(1, 3, 4), Point3D(2, 2, 2))
>>> a.angle_between(b)
-asin(sqrt(21)/6)

arbitrary_point(u=None, v=None)
Returns an arbitrary point on the Plane. If given two parameters, the point ranges
over the entire plane. If given 1 or no parameters, returns a point with one parame-
ter which, when varying from 0 to 2*pi, moves the point in a circle of radius 1 about
p1 of the Plane.
Returns Point3D

Examples

>>> from sympy.geometry import Plane, Ray

>>> from sympy.abc import u, v, t, r
>>> p = Plane((1, 1, 1), normal_vector=(1, 0, 0))
>>> p.arbitrary_point(u, v)
Point3D(1, u + 1, v + 1)
>>> p.arbitrary_point(t)
Point3D(1, cos(t) + 1, sin(t) + 1)

While arbitrary values of u and v can move the point anywhere in the plane, the
single-parameter point can be used to construct a ray whose arbitrary point can be
located at angle t and radius r from p.p1:

>>> Ray(p.p1, _).arbitrary_point(r)

Point3D(1, r*cos(t) + 1, r*sin(t) + 1)

static are_concurrent(*planes)
Is a sequence of Planes concurrent?
Two or more Planes are concurrent if their intersections are a common line.
Parameters planes: list
Returns Boolean

Examples

>>> from sympy import Plane, Point3D

>>> a = Plane(Point3D(5, 0, 0), normal_vector=(1, -1, 1))
>>> b = Plane(Point3D(0, -2, 0), normal_vector=(3, 1, 1))
>>> c = Plane(Point3D(0, -1, 0), normal_vector=(5, -1, 9))
>>> Plane.are_concurrent(a, b)
True
>>> Plane.are_concurrent(a, b, c)
False

distance(o)
Distance between the plane and another geometric entity.

674 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters Point3D, LinearEntity3D, Plane.

Returns distance

Notes

This method accepts only 3D entities as it’s parameter, but if you want to calculate
the distance between a 2D entity and a plane you should first convert to a 3D entity
by projecting onto a desired plane and then proceed to calculate the distance.

Examples

>>> from sympy import Point, Point3D, Line, Line3D, Plane

>>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 1, 1))
>>> b = Point3D(1, 2, 3)
>>> a.distance(b)
sqrt(3)
>>> c = Line3D(Point3D(2, 3, 1), Point3D(1, 2, 2))
>>> a.distance(c)
0

equals(o)
Returns True if self and o are the same mathematical entities.

Examples

>>> from sympy import Plane, Point3D

>>> a = Plane(Point3D(1, 2, 3), normal_vector=(1, 1, 1))
>>> b = Plane(Point3D(1, 2, 3), normal_vector=(2, 2, 2))
>>> c = Plane(Point3D(1, 2, 3), normal_vector=(-1, 4, 6))
>>> a.equals(a)
True
>>> a.equals(b)
True
>>> a.equals(c)
False

equation(x=None, y=None, z=None)

The equation of the Plane.

Examples

>>> from sympy import Point3D, Plane

>>> a = Plane(Point3D(1, 1, 2), Point3D(2, 4, 7), Point3D(3, 5, 1))
>>> a.equation()
-23*x + 11*y - 2*z + 16
>>> a = Plane(Point3D(1, 4, 2), normal_vector=(6, 6, 6))
>>> a.equation()
6*x + 6*y + 6*z - 42

intersection(o)
The intersection with other geometrical entity.

5.11. Geometry Module 675

SymPy Documentation, Release 1.3

Parameters Point, Point3D, LinearEntity, LinearEntity3D, Plane

Returns List

Examples

>>> from sympy import Point, Point3D, Line, Line3D, Plane

>>> a = Plane(Point3D(1, 2, 3), normal_vector=(1, 1, 1))
>>> b = Point3D(1, 2, 3)
>>> a.intersection(b)
[Point3D(1, 2, 3)]
>>> c = Line3D(Point3D(1, 4, 7), Point3D(2, 2, 2))
>>> a.intersection(c)
[Point3D(2, 2, 2)]
>>> d = Plane(Point3D(6, 0, 0), normal_vector=(2, -5, 3))
>>> e = Plane(Point3D(2, 0, 0), normal_vector=(3, 4, -3))
>>> d.intersection(e)
[Line3D(Point3D(78/23, -24/23, 0), Point3D(147/23, 321/23, 23))]

is_coplanar(o)
Returns True if o is coplanar with self, else False.

Examples

>>> from sympy import Plane, Point3D

>>> o = (0, 0, 0)
>>> p = Plane(o, (1, 1, 1))
>>> p2 = Plane(o, (2, 2, 2))
>>> p == p2
False
>>> p.is_coplanar(p2)
True

is_parallel(l)
Is the given geometric entity parallel to the plane?
Parameters LinearEntity3D or Plane
Returns Boolean

Examples

>>> from sympy import Plane, Point3D

>>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
>>> b = Plane(Point3D(3,1,3), normal_vector=(4, 8, 12))
>>> a.is_parallel(b)
True

is_perpendicular(l)
is the given geometric entity perpendicualar to the given plane?
Parameters LinearEntity3D or Plane
Returns Boolean

676 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Plane, Point3D

>>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
>>> b = Plane(Point3D(2, 2, 2), normal_vector=(-1, 2, -1))
>>> a.is_perpendicular(b)
True

normal_vector
Normal vector of the given plane.

Examples

>>> from sympy import Point3D, Plane

>>> a = Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
>>> a.normal_vector
(-1, 2, -1)
>>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 4, 7))
>>> a.normal_vector
(1, 4, 7)

p1
The only defining point of the plane. Others can be obtained from the arbitrary_point
method.
See also:
sympy.geometry.point.Point3D (page 598)

Examples

>>> from sympy import Point3D, Plane

>>> a = Plane(Point3D(1, 1, 1), Point3D(2, 3, 4), Point3D(2, 2, 2))
>>> a.p1
Point3D(1, 1, 1)

parallel_plane(pt)
Plane parallel to the given plane and passing through the point pt.
Parameters pt: Point3D
Returns Plane

Examples

>>> from sympy import Plane, Point3D

>>> a = Plane(Point3D(1, 4, 6), normal_vector=(2, 4, 6))
>>> a.parallel_plane(Point3D(2, 3, 5))
Plane(Point3D(2, 3, 5), (2, 4, 6))

parameter_value(other, u, v=None)
Return the parameter(s) corresponding to the given point.

5.11. Geometry Module 677

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Plane, Point, pi

>>> from sympy.abc import t, u, v
>>> p = Plane((2, 0, 0), (0, 0, 1), (0, 1, 0))

By default, the parameter value returned defines a point that is a distance of 1 from
the Plane’s p1 value and in line with the given point:

>>> on_circle = p.arbitrary_point(t).subs(t, pi/4)

>>> on_circle.distance(p.p1)
1
>>> p.parameter_value(on_circle, t)
{t: pi/4}

Moving the point twice as far from p1 does not change the parameter value:

>>> off_circle = p.p1 + (on_circle - p.p1)*2

>>> off_circle.distance(p.p1)
2
>>> p.parameter_value(off_circle, t)
{t: pi/4}

If the 2-value parameter is desired, supply the two parameter symbols and a replace-
ment dictionary will be returned:

>>> p.parameter_value(on_circle, u, v)
{u: sqrt(10)/10, v: sqrt(10)/30}
>>> p.parameter_value(off_circle, u, v)
{u: sqrt(10)/5, v: sqrt(10)/15}

perpendicular_line(pt)
A line perpendicular to the given plane.
Parameters pt: Point3D
Returns Line3D

Examples

>>> from sympy import Plane, Point3D, Line3D

>>> a = Plane(Point3D(1,4,6), normal_vector=(2, 4, 6))
>>> a.perpendicular_line(Point3D(9, 8, 7))
Line3D(Point3D(9, 8, 7), Point3D(11, 12, 13))

perpendicular_plane(*pts)
Return a perpendicular passing through the given points. If the direction ratio be-
tween the points is the same as the Plane’s normal vector then, to select from the
infinite number of possible planes, a third point will be chosen on the z-axis (or the
y-axis if the normal vector is already parallel to the z-axis). If less than two points
are given they will be supplied as follows: if no point is given then pt1 will be self.p1;
if a second point is not given it will be a point through pt1 on a line parallel to the
z-axis (if the normal is not already the z-axis, otherwise on the line parallel to the
y-axis).
Parameters pts: 0, 1 or 2 Point3D

678 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns Plane

Examples

>>> from sympy import Plane, Point3D, Line3D

>>> a, b = Point3D(0, 0, 0), Point3D(0, 1, 0)
>>> Z = (0, 0, 1)
>>> p = Plane(a, normal_vector=Z)
>>> p.perpendicular_plane(a, b)
Plane(Point3D(0, 0, 0), (1, 0, 0))

projection(pt)
Project the given point onto the plane along the plane normal.
Parameters Point or Point3D
Returns Point3D

Examples

>>> from sympy import Plane, Point, Point3D

>>> A = Plane(Point3D(1, 1, 2), normal_vector=(1, 1, 1))

The projection is along the normal vector direction, not the z axis, so (1, 1) does not
project to (1, 1, 2) on the plane A:

>>> b = Point3D(1, 1)
>>> A.projection(b)
Point3D(5/3, 5/3, 2/3)
>>> _ in A
True

But the point (1, 1, 2) projects to (1, 1) on the XY-plane:

>>> XY = Plane((0, 0, 0), (0, 0, 1))

>>> XY.projection((1, 1, 2))
Point3D(1, 1, 0)

projection_line(line)
Project the given line onto the plane through the normal plane containing the line.
Parameters LinearEntity or LinearEntity3D
Returns Point3D, Line3D, Ray3D or Segment3D

Notes

For the interaction between 2D and 3D lines(segments, rays), you should convert the
line to 3D by using this method. For example for finding the intersection between
a 2D and a 3D line, convert the 2D line to a 3D line by projecting it on a required
plane and then proceed to find the intersection between those lines.

5.11. Geometry Module 679

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Plane, Line, Line3D, Point, Point3D

>>> a = Plane(Point3D(1, 1, 1), normal_vector=(1, 1, 1))
>>> b = Line(Point3D(1, 1), Point3D(2, 2))
>>> a.projection_line(b)
Line3D(Point3D(4/3, 4/3, 1/3), Point3D(5/3, 5/3, -1/3))
>>> c = Line3D(Point3D(1, 1, 1), Point3D(2, 2, 2))
>>> a.projection_line(c)
Point3D(1, 1, 1)

random_point(seed=None)
Returns a random point on the Plane.
Returns Point3D

Examples

>>> from sympy import Plane

>>> p = Plane((1, 0, 0), normal_vector=(0, 1, 0))
>>> r = p.random_point(seed=42) # seed value is optional
>>> r.n(3)
Point3D(2.29, 0, -1.35)

The random point can be moved to lie on the circle of radius 1 centered on p1:

>>> c = p.p1 + (r - p.p1).unit

>>> c.distance(p.p1).equals(1)
True

5.12 Holonomic Functions

The holonomic (page 680) module is intended to deal with holonomic functions along with
various operations on them like addition, multiplication, composition, integration and dif-
ferentiation. The module also implements various kinds of conversions such as converting
holonomic functions to a different form and the other way around.

5.12.1 Contents

About Holonomic Functions

This text aims to explain holonomic functions. We assume you have a basic idea of Differential
equations and Abstract algebra.

Definition

Holonomic function is a very general type of special function that includes lots of simple
known functions as its special cases. In fact the more known hypergeometric function and
Meijer G-function are also a special case of it.

680 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

A function is called holonomic if it’s a solution to an ordinary differential equation having

polynomial coefficients only. Since the general solution of a differential equation consists of
a family of functions rather than a single function, holonomic functions are usually defined
by a set of initial conditions along with the differential equation.
Let K be a field of characteristic 0. For example, K can be QQ or RR. A function f (x) will be
holonomic if there exists polynomials p0 , p1 , p2 , ...pr ∈ K[x] such that

p0 · f (x) + p1 · f (1) (x) + p2 · f (2) (x) + ... + pr · f (r) (x) = 0

This differential equation can also be written as L · f (x) = 0 where

L = p0 + p1 · D + p2 · D2 + ...pr · Dr

Here D is the Differential Operator and L is called the annihilator of the function.
A unique holonomic function can be defined from the annihilator and a set of initial conditons.
For instance:
f (x) = exp(x) : L = D − 1, f (0) = 1
f (x) = sin(x) : L = D2 + 1, f (0) = 0, f ′ (0) = 1

Other fundamental functions such as cos(x), log(x), bessel functions etc. are also holonomic.
The family of holonomic functions is closed under addition, multiplication, integration, com-
position. This means if two functions are given are holonomic, then the function resulting on
applying these operation on them will also be holonomic.

References

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

Representation of holonomic functions in SymPy

Class DifferentialOperator is used to represent the annihilator but we create differential

operators easily using the function DifferentialOperators(). Class HolonomicFunction
represents a holonomic function.
Let’s explain this with an example:
Take sin(x) for instance, the differential equation satisfied by it is y (2) (x)+y(x) = 0. By definition
we conclude it is a holonomic function. The general solution of this ODE is C1 ·sin(x)+C2 ·cos(x)
but to get sin(x) we need to provide initial conditions i.e. y(0) = 0, y (1) (0) = 1.
To represent the same in this module one needs to provide the differential equation in the form
of annihilator. Basically a differential operator is an operator on functions that differentiates
them. So Dn · y(x) = y (n) (x) where y (n) (x) denotes n times differentiation of y(x) with respect to
x.
So the differential equation can also be written as D2 · y(x) + y(x) = 0 or (D2 + 1) · y(x) = 0. The
part left of y(x) is the annihilator i.e. D2 + 1.
So this is how one will represent sin(x) as a Holonomic Function:

5.12. Holonomic Functions 681

SymPy Documentation, Release 1.3

>>> from sympy.holonomic import DifferentialOperators, HolonomicFunction

>>> from sympy.abc import x
>>> from sympy import ZZ
>>> R, D = DifferentialOperators(ZZ.old_poly_ring(x), 'D')
>>> HolonomicFunction(D**2 + 1, x, 0, [0, 1])
HolonomicFunction((1) + (1)*D**2, x, 0, [0, 1])

The polynomial coefficients will be members of the ring ZZ[x] in the example. The D operator
returned by the function DifferentialOperators() can be used to create annihilators just
like SymPy expressions. We currently use the older implementations of rings in SymPy for
priority mechanism.

Operations on holonomic functions

Addition and Multiplication

Two holonomic functions can be added or multiplied with the result also a holonomic func-
tions.
>>> from sympy.holonomic.holonomic import HolonomicFunction,␣
,→DifferentialOperators

>>> from sympy.polys.domains import QQ

>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')

p and q here are holonomic representation of ex and sin(x) respectively.

>>> p = HolonomicFunction(Dx - 1, x, 0, [1])
>>> q = HolonomicFunction(Dx**2 + 1, x, 0, [0, 1])

Holonomic representation of ex + sin(x)

>>> p + q
HolonomicFunction((-1) + (1)*Dx + (-1)*Dx**2 + (1)*Dx**3, x, 0, [1, 2, 1])

Holonomic representation of ex · sin(x)

>>> p * q
HolonomicFunction((2) + (-2)*Dx + (1)*Dx**2, x, 0, [0, 1])

Integration and Differentiation

HolonomicFunction.integrate(limits, initcond=False)
Integrates the given holonomic function.

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
(continues on next page)

682 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(Dx - 1, x, 0, [1]).integrate((x, 0, x)) # e^x - 1
HolonomicFunction((-1)*Dx + (1)*Dx**2, x, 0, [0, 1])
>>> HolonomicFunction(Dx**2 + 1, x, 0, [1, 0]).integrate((x, 0, x))
HolonomicFunction((1)*Dx + (1)*Dx**3, x, 0, [0, 1, 0])

HolonomicFunction.diff(*args)
Differentiation of the given Holonomic function.
See also:
integrate (page 682)

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(ZZ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(Dx**2 + 1, x, 0, [0, 1]).diff().to_expr()
cos(x)
>>> HolonomicFunction(Dx - 2, x, 0, [1]).diff().to_expr()
2*exp(2*x)

Composition with polynomials

HolonomicFunction.composition(expr, *args, **kwargs)

Returns function after composition of a holonomic function with an algebraic function.
The method can’t compute initial conditions for the result by itself, so they can be also
be provided.
See also:
from_hyper (page 687)

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(Dx - 1, x).composition(x**2, 0, [1]) # e^(x**2)
HolonomicFunction((-2*x) + (1)*Dx, x, 0, [1])
>>> HolonomicFunction(Dx**2 + 1, x).composition(x**2 - 1, 1, [1, 0])
HolonomicFunction((4*x**3) + (-1)*Dx + (x)*Dx**2, x, 1, [1, 0])

5.12. Holonomic Functions 683

SymPy Documentation, Release 1.3

Convert to holonomic sequence

HolonomicFunction.to_sequence(lb=True)
Finds recurrence relation for the coefficients in the series expansion of the function
about x0 , where x0 is the point at which the initial condition is stored.
If the point x0 is ordinary, solution of the form [(R, n0 )] is returned. Where R is the recur-
rence relation and n0 is the smallest n for which the recurrence holds true.
If the point x0 is regular singular, a list of solutions in the format (R, p, n0 ) is returned, i.e.
[(R, p, n0 ), ...]. Each tuple in this vector represents a recurrence relation R associated with
a root of the indicial equation p. Conditions of a different format can also be provided in
this case, see the docstring of HolonomicFunction class.
If it’s not possible to numerically compute a initial condition, it is returned as a symbol
Cj , denoting the coefficient of (x − x0 )j in the power series about x0 .
See also:
HolonomicFunction.series (page 684)

References

[R408], [R409]

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols, S
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(Dx - 1, x, 0, [1]).to_sequence()
[(HolonomicSequence((-1) + (n + 1)Sn, n), u(0) = 1, 0)]
>>> HolonomicFunction((1 + x)*Dx**2 + Dx, x, 0, [0, 1]).to_sequence()
[(HolonomicSequence((n**2) + (n**2 + n)Sn, n), u(0) = 0, u(1) = 1, u(2) = -1/2,␣
,→2)]

>>> HolonomicFunction(-S(1)/2 + x*Dx, x, 0, {S(1)/2: [1]}).to_sequence()

[(HolonomicSequence((n), n), u(0) = 1, 1/2, 1)]

Series expansion

HolonomicFunction.series(n=6, coefficient=False, order=True, _recur=None)

Finds the power series expansion of given holonomic function about x0 .
A list of series might be returned if x0 is a regular point with multiple roots of the indicial
equation.
See also:
HolonomicFunction.to_sequence (page 684)

684 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(Dx - 1, x, 0, [1]).series() # e^x
1 + x + x**2/2 + x**3/6 + x**4/24 + x**5/120 + O(x**6)
>>> HolonomicFunction(Dx**2 + 1, x, 0, [0, 1]).series(n=8) # sin(x)
x - x**3/6 + x**5/120 - x**7/5040 + O(x**8)

Numerical evaluation

HolonomicFunction.evalf(points, method=’RK4’, h=0.05, derivatives=False)

Finds numerical value of a holonomic function using numerical methods. (RK4 by de-
fault). A set of points (real or complex) must be provided which will be the path for the
numerical integration.
The path should be given as a list [x1 , x2 , ...xn ]. The numerical values will be computed at
each point in this order x1 − − > x2 − − > x3 ... − − > xn .
Returns values of the function at x1 , x2 , ...xn in a list.

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(QQ.old_poly_ring(x),'Dx')

A straight line on the real axis from (0 to 1)

>>> r = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1]

Runge-Kutta 4th order on e^x from 0.1 to 1. Exact solution at 1 is 2.71828182845905

>>> HolonomicFunction(Dx - 1, x, 0, [1]).evalf(r)

[1.10517083333333, 1.22140257085069, 1.34985849706254, 1.49182424008069,
1.64872063859684, 1.82211796209193, 2.01375162659678, 2.22553956329232,
2.45960141378007, 2.71827974413517]

Euler’s method for the same

>>> HolonomicFunction(Dx - 1, x, 0, [1]).evalf(r, method='Euler')

[1.1, 1.21, 1.331, 1.4641, 1.61051, 1.771561, 1.9487171, 2.14358881,
2.357947691, 2.5937424601]

One can also observe that the value obtained using Runge-Kutta 4th order is much more
accurate than Euler’s method.

5.12. Holonomic Functions 685

SymPy Documentation, Release 1.3

Convert to a linear combination of hypergeometric functions

HolonomicFunction.to_hyper(as_list=False, _recur=None)
Returns a hypergeometric function (or linear combination of them) representing the
given holonomic function.
Returns an answer of the form: a1 · xb1 · hyper() + a2 · xb2 · hyper()...
This is very useful as one can now use hyperexpand to find the symbolic expres-
sions/functions.
See also:
from_hyper (page 687), from_meijerg (page 687)

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(ZZ.old_poly_ring(x),'Dx')
>>> # sin(x)
>>> HolonomicFunction(Dx**2 + 1, x, 0, [0, 1]).to_hyper()
x*hyper((), (3/2,), -x**2/4)
>>> # exp(x)
>>> HolonomicFunction(Dx - 1, x, 0, [1]).to_hyper()
hyper((), (), x)

Convert to a linear combination of Meijer G-functions

HolonomicFunction.to_meijerg()
Returns a linear combination of Meijer G-functions.
See also:
to_hyper (page 686)

Examples

>>> from sympy.holonomic import expr_to_holonomic

>>> from sympy import sin, cos, hyperexpand, log, symbols
>>> x = symbols('x')
>>> hyperexpand(expr_to_holonomic(cos(x) + sin(x)).to_meijerg())
sin(x) + cos(x)
>>> hyperexpand(expr_to_holonomic(log(x)).to_meijerg()).simplify()
log(x)

Convert to expressions

HolonomicFunction.to_expr()
Converts a Holonomic Function back to elementary functions.

686 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.holonomic.holonomic import HolonomicFunction, DifferentialOperators

>>> from sympy.polys.domains import ZZ, QQ
>>> from sympy import symbols, S
>>> x = symbols('x')
>>> R, Dx = DifferentialOperators(ZZ.old_poly_ring(x),'Dx')
>>> HolonomicFunction(x**2*Dx**2 + x*Dx + (x**2 - 1), x, 0, [0, S(1)/2]).to_expr()
besselj(1, x)
>>> HolonomicFunction((1 + x)*Dx**3 + Dx**2, x, 0, [1, 1, 1]).to_expr()
x*log(x + 1) + log(x + 1) + 1

Converting other representations to holonomic

Converting hypergeometric functions

sympy.holonomic.holonomic.from_hyper(func, x0=0, evalf=False)

Converts a hypergeometric function to holonomic. func is the Hypergeometric Function
and x0 is the point at which initial conditions are required.

Examples

>>> from sympy.holonomic.holonomic import from_hyper, DifferentialOperators

>>> from sympy import symbols, hyper, S
>>> x = symbols('x')
>>> from_hyper(hyper([], [S(3)/2], x**2/4))
HolonomicFunction((-x) + (2)*Dx + (x)*Dx**2, x, 1, [sinh(1), -sinh(1) + cosh(1)])

Converting Meijer G-functions

sympy.holonomic.holonomic.from_meijerg(func, x0=0, evalf=False, initcond=True,

domain=QQ)
Converts a Meijer G-function to Holonomic. func is the G-Function and x0 is the point
at which initial conditions are required.

Examples

>>> from sympy.holonomic.holonomic import from_meijerg, DifferentialOperators

>>> from sympy import symbols, meijerg, S
>>> x = symbols('x')
>>> from_meijerg(meijerg(([], []), ([S(1)/2], [0]), x**2/4))
HolonomicFunction((1) + (1)*Dx**2, x, 0, [0, 1/sqrt(pi)])

5.12. Holonomic Functions 687

SymPy Documentation, Release 1.3

Converting symbolic expressions

sympy.holonomic.holonomic.expr_to_holonomic(func, x=None, x0=0, y0=None,

lenics=None, domain=None, init-
cond=True)
Converts a function or an expression to a holonomic function.
Parameters func:
The expression to be converted.
x:
variable for the function.
x0:
point at which initial condition must be computed.
y0:
One can optionally provide initial condition if the method isn’t able to
do it automatically.
lenics:
Number of terms in the initial condition. By default it is equal to the
order of the annihilator.
domain:
Ground domain for the polynomials in x appearing as coefficients in
the annihilator.
initcond:
Set it false if you don’t want the initial conditions to be computed.
See also:
meijerint._rewrite1, _convert_poly_rat_alg, _create_table

Examples

>>> from sympy.holonomic.holonomic import expr_to_holonomic

>>> from sympy import sin, exp, symbols
>>> x = symbols('x')
>>> expr_to_holonomic(sin(x))
HolonomicFunction((1) + (1)*Dx**2, x, 0, [0, 1])
>>> expr_to_holonomic(exp(x))
HolonomicFunction((-1) + (1)*Dx, x, 0, [1])

Uses and Current limitations

Integration

One can perform integrations using holonomic functions by following these steps:
1. Convert the integrand to a holonomic function.

688 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

2. Now integrate the holonomic representation of the function.

3. Convert the integral back to expressions.

Examples

>>> from sympy.abc import x, a

>>> from sympy import sin
>>> from sympy.holonomic import expr_to_holonomic
>>> expr_to_holonomic(1/(x**2+a), x).integrate(x).to_expr()
atan(x/sqrt(a))/sqrt(a)
>>> expr_to_holonomic(sin(x)/x).integrate(x).to_expr()
Si(x)

As you can see in the first example we converted the function to holonomic, integrated the
result and then converted back to symbolic expression.

Limitations

1. Converting to expressions is not always possible. The holonomic function should have a
hypergeometric series at x0.
2. Implementation of converting to holonomic sequence currently doesn’t support Frobenius
method when the solutions need to have log terms. This happens when at least one pair of
the roots of the indicial equation differ by an integer and frobenius method yields linearly
dependent series solutions. Since we use this while converting to expressions, sometimes
to_expr() (page 686) fails.
3. There doesn’t seem to be∫ a way for computing indefinite integrals, so integrate()
x
(page 682) basically computes x0 f (x)dx if no limits are given, where x0 is the point at which
initial conditions for the integrand are stored. Sometimes this gives an additional constant in
the result. For instance:

>>> expr_to_holonomic(sin(x)).integrate(x).to_expr()
-cos(x) + 1
>>> sin(x).integrate(x)
-cos(x)
∫x
The indefinite integral of sin(x) is − cos(x). But the output is − cos(x) + 1 which is 0
sin(x)dx.
Although both are considered correct but − cos(x) is simpler.

5.13 Symbolic Integrals

The integrals module in SymPy implements methods to calculate definite and indefinite
integrals of expressions.
Principal method in this module is integrate() (page 711)
∫
• integrate(f, x) returns the indefinite integral f dx
∫b
• integrate(f, (x, a, b)) returns the definite integral a
f dx

5.13. Symbolic Integrals 689

SymPy Documentation, Release 1.3

5.13.1 Examples

SymPy can integrate a vast array of functions. It can integrate polynomial functions:

>>> from sympy import *

>>> init_printing(use_unicode=False, wrap_line=False)
>>> x = Symbol('x')
>>> integrate(x**2 + x + 1, x)
3 2
x x
-- + -- + x
3 2

Rational functions:

>>> integrate(x/(x**2+2*x+1), x)
1
log(x + 1) + -----
x + 1

Exponential-polynomial functions. These multiplicative combinations of polynomials and the

functions exp, cos and sin can be integrated by hand using repeated integration by parts,
which is an extremely tedious process. Happily, SymPy will deal with these integrals.

>>> integrate(x**2 * exp(x) * cos(x), x)

2 x 2 x x x
x *e *sin(x) x *e *cos(x) x e *sin(x) e *cos(x)
------------ + ------------ - x*e *sin(x) + --------- - ---------
2 2 2 2

even a few nonelementary integrals (in particular, some integrals involving the error function)
can be evaluated:

>>> integrate(exp(-x**2)*erf(x), x)
____ 2
\/ pi *erf (x)
--------------
4

5.13.2 Integral Transforms

SymPy has special support for definite integrals, and integral transforms.
sympy.integrals.transforms.mellin_transform(f, x, s, **hints)
Compute the Mellin transform F (s) of f (x),
∫ ∞
F (s) = xs−1 f (x)dx.
0

For all “sensible” functions, this converges absolutely in a strip a < Re(s) < b.
The Mellin transform is related via change of variables to the Fourier transform, and
also to the (bilateral) Laplace transform.
This function returns (F, (a, b), cond) where F is the Mellin transform of f, (a, b)
is the fundamental strip (as above), and cond are auxiliary convergence conditions.

690 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If the integral cannot be computed in closed form, this function returns an unevaluated
MellinTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). If noconds=False, then only F will be re-
turned (i.e. not cond, and also not the strip (a, b)).
>>> from sympy.integrals.transforms import mellin_transform
>>> from sympy import exp
>>> from sympy.abc import x, s
>>> mellin_transform(exp(-x), x, s)
(gamma(s), (0, oo), True)

See also:
inverse_mellin_transform (page 691), laplace_transform (page 692),
fourier_transform (page 693), hankel_transform (page 695), in-
verse_hankel_transform (page 696)
sympy.integrals.transforms.inverse_mellin_transform(F, s, x, strip, **hints)
Compute the inverse Mellin transform of F (s) over the fundamental strip given by
strip=(a, b).
This can be defined as
∫ c+i∞
1
f (x) = x−s F (s)ds,
2πi c−i∞

for any c in the fundamental strip. Under certain regularity conditions on F and/or f ,
this recovers f from its Mellin transform F (and vice versa), for positive real x.
One of a or b may be passed as None; a suitable c will be inferred.
If the integral cannot be computed in closed form, this function returns an unevaluated
InverseMellinTransform object.
Note that this function will assume x to be positive and real, regardless of the sympy
assumptions!
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit().
>>> from sympy.integrals.transforms import inverse_mellin_transform
>>> from sympy import oo, gamma
>>> from sympy.abc import x, s
>>> inverse_mellin_transform(gamma(s), s, x, (0, oo))
exp(-x)

The fundamental strip matters:

>>> f = 1/(s**2 - 1)
>>> inverse_mellin_transform(f, s, x, (-oo, -1))
(x/2 - 1/(2*x))*Heaviside(x - 1)
>>> inverse_mellin_transform(f, s, x, (-1, 1))
-x*Heaviside(-x + 1)/2 - Heaviside(x - 1)/(2*x)
>>> inverse_mellin_transform(f, s, x, (1, oo))
(-x/2 + 1/(2*x))*Heaviside(-x + 1)

See also:
mellin_transform (page 690), hankel_transform (page 695), in-
verse_hankel_transform (page 696)

5.13. Symbolic Integrals 691

SymPy Documentation, Release 1.3

sympy.integrals.transforms.laplace_transform(f, t, s, **hints)
Compute the Laplace Transform F (s) of f (t),
∫ ∞
F (s) = e−st f (t)dt.
0

For all “sensible” functions, this converges absolutely in a half plane a < Re(s).
This function returns (F, a, cond) where F is the Laplace transform of f, Re(s) > a is
the half-plane of convergence, and cond are auxiliary convergence conditions.
If the integral cannot be computed in closed form, this function returns an unevaluated
LaplaceTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). If noconds=True, only F will be returned (i.e.
not cond, and also not the plane a).
>>> from sympy.integrals import laplace_transform
>>> from sympy.abc import t, s, a
>>> laplace_transform(t**a, t, s)
(s**(-a)*gamma(a + 1)/s, 0, -re(a) < 1)

See also:
inverse_laplace_transform (page 692), mellin_transform (page 690),
fourier_transform (page 693), hankel_transform (page 695), in-
verse_hankel_transform (page 696)
sympy.integrals.transforms.inverse_laplace_transform(F, s, t, plane=None,
**hints)
Compute the inverse Laplace transform of F (s), defined as
∫ c+i∞
1
f (t) = est F (s)ds,
2πi c−i∞
for c so large that F (s) has no singularites in the half-plane Re(s) > c − ϵ.
The plane can be specified by argument plane, but will be inferred if passed as None.
Under certain regularity conditions, this recovers f (t) from its Laplace Transform F (s),
for non-negative t, and vice versa.
If the integral cannot be computed in closed form, this function returns an unevaluated
InverseLaplaceTransform object.
Note that this function will always assume t to be real, regardless of the sympy assump-
tion on t.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit().
>>> from sympy.integrals.transforms import inverse_laplace_transform
>>> from sympy import exp, Symbol
>>> from sympy.abc import s, t
>>> a = Symbol('a', positive=True)
>>> inverse_laplace_transform(exp(-a*s)/s, s, t)
Heaviside(-a + t)

See also:
laplace_transform (page 692), hankel_transform (page 695), in-
verse_hankel_transform (page 696)

692 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.integrals.transforms.fourier_transform(f, x, k, **hints)
Compute the unitary, ordinary-frequency Fourier transform of f , defined as
∫ ∞
F (k) = f (x)e−2πixk dx.
−∞

If the transform cannot be computed in closed form, this function returns an unevaluated
FourierTransform object.
For other Fourier transform conventions, see the function sympy.integrals.
transforms._fourier_transform().
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.
>>> from sympy import fourier_transform, exp
>>> from sympy.abc import x, k
>>> fourier_transform(exp(-x**2), x, k)
sqrt(pi)*exp(-pi**2*k**2)
>>> fourier_transform(exp(-x**2), x, k, noconds=False)
(sqrt(pi)*exp(-pi**2*k**2), True)

See also:
inverse_fourier_transform (page 693), sine_transform (page 693), in-
verse_sine_transform (page 694), cosine_transform (page 694), in-
verse_cosine_transform (page 695), hankel_transform (page 695), in-
verse_hankel_transform (page 696), mellin_transform (page 690),
laplace_transform (page 692)
sympy.integrals.transforms.inverse_fourier_transform(F, k, x, **hints)
Compute the unitary, ordinary-frequency inverse Fourier transform of F , defined as
∫ ∞
f (x) = F (k)e2πixk dk.
−∞

If the transform cannot be computed in closed form, this function returns an unevaluated
InverseFourierTransform object.
For other Fourier transform conventions, see the function sympy.integrals.
transforms._fourier_transform().
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.
>>> from sympy import inverse_fourier_transform, exp, sqrt, pi
>>> from sympy.abc import x, k
>>> inverse_fourier_transform(sqrt(pi)*exp(-(pi*k)**2), k, x)
exp(-x**2)
>>> inverse_fourier_transform(sqrt(pi)*exp(-(pi*k)**2), k, x, noconds=False)
(exp(-x**2), True)

See also:
fourier_transform (page 693), sine_transform (page 693), inverse_sine_transform
(page 694), cosine_transform (page 694), inverse_cosine_transform
(page 695), hankel_transform (page 695), inverse_hankel_transform (page 696),
mellin_transform (page 690), laplace_transform (page 692)

5.13. Symbolic Integrals 693

SymPy Documentation, Release 1.3

sympy.integrals.transforms.sine_transform(f, x, k, **hints)
Compute the unitary, ordinary-frequency sine transform of f , defined as
√ ∫ ∞
2
F (k) = f (x) sin(2πxk)dx.
π 0

If the transform cannot be computed in closed form, this function returns an unevaluated
SineTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.

>>> from sympy import sine_transform, exp

>>> from sympy.abc import x, k, a
>>> sine_transform(x*exp(-a*x**2), x, k)
sqrt(2)*k*exp(-k**2/(4*a))/(4*a**(3/2))
>>> sine_transform(x**(-a), x, k)
2**(-a + 1/2)*k**(a - 1)*gamma(-a/2 + 1)/gamma(a/2 + 1/2)

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
inverse_sine_transform (page 694), cosine_transform (page 694), in-
verse_cosine_transform (page 695), hankel_transform (page 695), in-
verse_hankel_transform (page 696), mellin_transform (page 690),
laplace_transform (page 692)
sympy.integrals.transforms.inverse_sine_transform(F, k, x, **hints)
Compute the unitary, ordinary-frequency inverse sine transform of F , defined as
√ ∫ ∞
2
f (x) = F (k) sin(2πxk)dk.
π 0

If the transform cannot be computed in closed form, this function returns an unevaluated
InverseSineTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.

>>> from sympy import inverse_sine_transform, exp, sqrt, gamma, pi

>>> from sympy.abc import x, k, a
>>> inverse_sine_transform(2**((1-2*a)/2)*k**(a - 1)*
... gamma(-a/2 + 1)/gamma((a+1)/2), k, x)
x**(-a)
>>> inverse_sine_transform(sqrt(2)*k*exp(-k**2/(4*a))/(4*sqrt(a)**3), k, x)
x*exp(-a*x**2)

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
sine_transform (page 693), cosine_transform (page 694), in-
verse_cosine_transform (page 695), hankel_transform (page 695), in-
verse_hankel_transform (page 696), mellin_transform (page 690),
laplace_transform (page 692)

694 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.integrals.transforms.cosine_transform(f, x, k, **hints)
Compute the unitary, ordinary-frequency cosine transform of f , defined as
√ ∫ ∞
2
F (k) = f (x) cos(2πxk)dx.
π 0
If the transform cannot be computed in closed form, this function returns an unevaluated
CosineTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.
>>> from sympy import cosine_transform, exp, sqrt, cos
>>> from sympy.abc import x, k, a
>>> cosine_transform(exp(-a*x), x, k)
sqrt(2)*a/(sqrt(pi)*(a**2 + k**2))
>>> cosine_transform(exp(-a*sqrt(x))*cos(a*sqrt(x)), x, k)
a*exp(-a**2/(2*k))/(2*k**(3/2))

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
sine_transform (page 693), inverse_sine_transform (page 694), in-
verse_cosine_transform (page 695), hankel_transform (page 695), in-
verse_hankel_transform (page 696), mellin_transform (page 690),
laplace_transform (page 692)
sympy.integrals.transforms.inverse_cosine_transform(F, k, x, **hints)
Compute the unitary, ordinary-frequency inverse cosine transform of F , defined as
√ ∫ ∞
2
f (x) = F (k) cos(2πxk)dk.
π 0
If the transform cannot be computed in closed form, this function returns an unevaluated
InverseCosineTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.
>>> from sympy import inverse_cosine_transform, exp, sqrt, pi
>>> from sympy.abc import x, k, a
>>> inverse_cosine_transform(sqrt(2)*a/(sqrt(pi)*(a**2 + k**2)), k, x)
exp(-a*x)
>>> inverse_cosine_transform(1/sqrt(k), k, x)
1/sqrt(x)

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
sine_transform (page 693), inverse_sine_transform (page 694), cosine_transform
(page 694), hankel_transform (page 695), inverse_hankel_transform (page 696),
mellin_transform (page 690), laplace_transform (page 692)
sympy.integrals.transforms.hankel_transform(f, r, k, nu, **hints)
Compute the Hankel transform of f , defined as
∫ ∞
Fν (k) = f (r)Jν (kr)rdr.
0

5.13. Symbolic Integrals 695

SymPy Documentation, Release 1.3

If the transform cannot be computed in closed form, this function returns an unevaluated
HankelTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.

>>> from sympy import hankel_transform, inverse_hankel_transform

>>> from sympy import gamma, exp, sinh, cosh
>>> from sympy.abc import r, k, m, nu, a

>>> ht = hankel_transform(1/r**m, r, k, nu)

>>> ht
2*2**(-m)*k**(m - 2)*gamma(-m/2 + nu/2 + 1)/gamma(m/2 + nu/2)

>>> inverse_hankel_transform(ht, k, r, nu)

r**(-m)

>>> ht = hankel_transform(exp(-a*r), r, k, 0)
>>> ht
a/(k**3*(a**2/k**2 + 1)**(3/2))

>>> inverse_hankel_transform(ht, k, r, 0)
exp(-a*r)

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
sine_transform (page 693), inverse_sine_transform (page 694), cosine_transform
(page 694), inverse_cosine_transform (page 695), inverse_hankel_transform
(page 696), mellin_transform (page 690), laplace_transform (page 692)
sympy.integrals.transforms.inverse_hankel_transform(F, k, r, nu, **hints)
Compute the inverse Hankel transform of F defined as
∫ ∞
f (r) = Fν (k)Jν (kr)kdk.
0

If the transform cannot be computed in closed form, this function returns an unevaluated
InverseHankelTransform object.
For a description of possible hints, refer to the docstring of sympy.integrals.
transforms.IntegralTransform.doit(). Note that for this transform, by default no-
conds=True.

>>> from sympy import hankel_transform, inverse_hankel_transform, gamma

>>> from sympy import gamma, exp, sinh, cosh
>>> from sympy.abc import r, k, m, nu, a

>>> ht = hankel_transform(1/r**m, r, k, nu)

>>> ht
2*2**(-m)*k**(m - 2)*gamma(-m/2 + nu/2 + 1)/gamma(m/2 + nu/2)

>>> inverse_hankel_transform(ht, k, r, nu)

r**(-m)

696 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> ht = hankel_transform(exp(-a*r), r, k, 0)
>>> ht
a/(k**3*(a**2/k**2 + 1)**(3/2))

>>> inverse_hankel_transform(ht, k, r, 0)
exp(-a*r)

See also:
fourier_transform (page 693), inverse_fourier_transform (page 693),
sine_transform (page 693), inverse_sine_transform (page 694), cosine_transform
(page 694), inverse_cosine_transform (page 695), hankel_transform (page 695),
mellin_transform (page 690), laplace_transform (page 692)

5.13.3 Internals

There is a general method for calculating antiderivatives of elementary functions, called the
Risch algorithm. The Risch algorithm is a decision procedure that can determine whether an
elementary solution exists, and in that case calculate it. It can be extended to handle many
nonelementary functions in addition to the elementary ones.
SymPy currently uses a simplified version of the Risch algorithm, called the Risch-Norman
algorithm. This algorithm is much faster, but may fail to find an antiderivative, although it is
still very powerful. SymPy also uses pattern matching and heuristics to speed up evaluation
of some types of integrals, e.g. polynomials.
For non-elementary definite integrals, SymPy uses so-called Meijer G-functions. Details are
described here:

Computing Integrals using Meijer G-Functions

This text aims do describe in some detail the steps (and subtleties) involved in using Meijer
G-functions for computing definite and indefinite integrals. We shall ignore proofs completely.

Overview

∫ ∫∞
The algorithm to compute f (x)dx or 0
f (x)dx generally consists of three steps:
1. Rewrite the integrand using Meijer G-functions (one or sometimes two).
2. Apply an integration theorem, to get the answer (usually expressed as another G-
function).
3. Expand the result in named special functions.
Step (3) is implemented in the function hyperexpand (q.v.). Steps (1) and (2) are described be-
low. Moreover, G-functions are usually branched. Thus our treatment of branched functions
is described first.
∫∞
Some other integrals (e.g. −∞ ) can also be computed by first recasting them into one of the
above forms. There is a lot of choice involved here, and the algorithm is heuristic at best.

5.13. Symbolic Integrals 697

SymPy Documentation, Release 1.3

Polar Numbers and Branched Functions

Both Meijer G-Functions and Hypergeometric functions are typically branched (possible
branchpoints being 0, ±1, ∞). This is not very important when e.g. expanding a single hyper-
geometric function into named special functions, since sorting out the branches can be left
to the human user. However this algorithm manipulates and transforms G-functions, and to
do this correctly it needs at least some crude understanding of the branchings involved.
To begin, we consider the set S = {(r, θ) : r > 0, θ ∈ R}. We have a map p : S :→ C − {0}, (r, θ) 7→
reiθ . Decreeing this to be a local biholomorphism gives S both a topology and a complex
structure. This Riemann Surface is usually referred to as the Riemann Surface of the loga-
rithm, for the following reason: We can define maps Exp : C → S, (x + iy) 7→ (exp(x), y) and
Log : S → C, (ex , y) 7→ x + iy. These can both be shown to be holomorphic, and are indeed
mutual inverses.
We also sometimes formally attach a point “zero” (0) to S and denote the resulting object
S0 . Notably there is no complex structure defined near 0. A fundamental system of neigh-
bourhoods is given by {Exp(z) : ℜ(z) < k}, which at least defines a topology. Elements of
S0 shall be called polar numbers. We further define functions Arg : S → R, (r, θ) 7→ θ and
|.| : S0 → R>0 , (r, θ) 7→ r. These have evident meaning and are both continuous everywhere.
Using these maps many operations can be extended from C to S. We define Exp(a) Exp(b) =
Exp(a + b) for a, b ∈ C, also for a ∈ S and b ∈ C we define ab = Exp(b Log(a)). It can be checked
easily that using these definitions, many algebraic properties holding for positive reals (e.g.
(ab)c = ac bc ) which hold in C only for some numbers (because of branch cuts) hold indeed for
all polar numbers.
As one peculiarity it should be mentioned that addition of polar numbers is not usually defined.
However, formal sums of polar numbers √ can be used to express
√ branching behaviour. For
example, consider the functions F (z) = 1 + z and G(a, b) = a + b, where a, b, z are polar
numbers. The general rule is that functions of a single polar variable are defined in such a
way that they are continuous on circles, and agree with the usual definition for positive reals.
Thus if S(z) denotes the standard branch of the square root function on C, we are forced to
define


S(p(z)) : |z| < 1
F (z) = S(p(z)) : −π < Arg(z) + 4πn ≤ π for some n ∈ Z .


−S(p(z)) : else

√ are omitting |z| = 1 here, this does not matter for integration.) Finally we define G(a, b) =
(We
aF (b/a).

Representing Branched Functions on the Argand Plane

Suppose f : S → C is a holomorphic function. We wish to define a function F on (part of)

the complex numbers C that represents f as closely as possible. This process is knows as
“introducing branch cuts”. In our situation, there is actually a canonical way of doing this
(which is adhered to in all of SymPy), as follows: Introduce the “cut complex plane” C = C\R≤0 .
Define a function l : C → S via reiθ 7→ r Exp(iθ). Here r > 0 and −π < θ ≤ π. Then l is
holomorphic, and we define G = f ◦ l. This called “lifting to the principal branch” throughout
the SymPy documentation.

698 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Table Lookups and Inverse Mellin Transforms

Suppose we are given an integrand f (x) and are trying to rewrite it as a single G-function.
To do this, we first split f (x) into the form xs g(x) (where g(x) is supposed to be simpler than
f (x)). This is because multiplicative powers can be absorbed into the G-function later. This
splitting is done by _split_mul(f, x). Then we assemble a tuple of functions that occur in
f (e.g. if f (x) = ex cos x, we would assemble the tuple (cos, exp)). This is done by the function
_mytype(f, x). Next we index a lookup table (created using _create_lookup_table()) with
this tuple. This (hopefully) yields a list of Meijer G-function formulae involving these func-
tions, we then pattern-match all of them. If one fits, we were successful, otherwise not and
we have to try something else.
Suppose now we want to rewrite as a product of two G-functions. To do this, we (try to) find
all inequivalent ways of splitting f (x) into a product f1 (x)f2 (x). We could try these splittings
in any order, but it is often a good idea to minimize (a) the number of powers occurring
in fi (x) and (b) the number of different functions occurring in fi (x). Thus given e.g. f (x) =
sin x ex sin 2x we should try f1 (x) = sin x sin 2x, f2 (x) = ex first. All of this is done by the function
_mul_as_two_parts(f).
Finally, we can try a recursive Mellin transform technique. Since the Meijer G-function is
defined essentially as a certain inverse mellin transform, if we want to write a function f (x)
as a G-function, we can compute its mellin transform F (s). If F (s) is in the right form, the
G-function expression can be read off. This technique generalises many standard rewritings,
e.g. eax ebx = e(a+b)x .
One twist is that some functions don’t have mellin transforms, even though they can be written
as G-functions. This is true for example for f (x) = ex sin x (the function grows too rapidly to
have a mellin transform). However if the function is recognised to be analytic, then we can
try to compute the mellin-transform of f (ax) for a parameter a, and deduce the G-function
expression by analytic continuation. (Checking for analyticity is easy. Since we can only
deal with a certain subset of functions anyway, we only have to filter out those which are not
analyitc.)
The function _rewrite_single does the table lookup and recursive mellin transform.
The functions _rewrite1 and _rewrite2 respectively use above-mentioned helpers and
_rewrite_single to rewrite their argument as respectively one or two G-functions.

Applying the Integral Theorems

If the integrand has been recast into G-functions, evaluating the integral is relatively easy.
We first do some substitutions to reduce e.g. the exponent of the argument of the G-function
to unity (see _rewrite_saxena_1 and _rewrite_saxena, respectively, for one or two G-
functions). Next we go through a list of conditions under which the integral theorem applies.
It can fail for basically two reasons: either the integral does not exist, or the manipulations
in deriving the theorem may not be allowed (for more details, see this [BlogPost]).
Sometimes this can be remedied by reducing the argument of the G-functions involved. For
example it is clear that the G-function representing ez is satisfies G(Exp(2πi)z) = G(z) for all
z ∈ S. The function meijerg.get_period() can be used to discover this, and the function
principal_branch(z, period) in functions/elementary/complexes.py can be used to ex-
ploit the information. This is done transparently by the integration code.

5.13. Symbolic Integrals 699

SymPy Documentation, Release 1.3

The G-Function Integration Theorems

This section intends to display in detail the definite integration theorems used in the code.
The following two formulae go back to Meijer (In fact he proved more general formulae;
indeed in the literature formulae are usually staded in more general form. However it is very
easy to deduce the general formulae from the ones we give here. It seemed best to keep the
theorems as simple as possible, since they are very complicated anyway.):
1.
∫ ∞ ( ) ∏m ∏n
a1 , · · · , a p j=1 Γ(bj + 1) Γ(−aj )
Gm,n ηx dx = ∏q ∏p j=1
0
p,q b1 , · · · , bq η j=m+1 Γ(−bj ) j=n+1 Γ(aj + 1)

2.
∫ ∞ ( ) ( ) ( )
c1 , · · · , c u a1 , · · · , ap m+t,n+s a1 , · · · , an , −d1 , · · · , −dv , an+1 , · · · , ap ω
Gs,t m,n
σx Gp,q ωx dx = Gv+p,u+q
0
u,v d1 , · · · , dv b1 , · · · , b q b1 , · · · , bm , −c1 , · · · , −cu , bm+1 , · · · , bq σ

The more interesting question is under what conditions these formulae are valid. Below we
detail the conditions implemented in SymPy. They are an amalgamation of conditions found
in [Prudnikov1990] and [Luke1969]; please let us know if you find any errors.

Conditions of Convergence for Integral (1)

We can without loss of generality assume p ≤ q, since the G-functions of indices m, n, p, q and
of indices n, m, q, p can be related easily (see e.g. [Luke1969], section 5.3). We introduce the
following notation:

ξ =m+n−p
p+q
δ =m+n−
2
C3 : −ℜ(bj ) < 1 for j = 1, . . . , m
0 < −ℜ(aj ) for j = 1, . . . , n
C3∗ : −ℜ(bj ) < 1 for j = 1, . . . , q
0 < −ℜ(aj ) for j = 1, . . . , p
q+1−p
C4 : −ℜ(δ) +
>q−p
2
The convergence conditions will be detailed in several “cases”, numbered one to five. For
later use it will be helpful to separate conditions “at infinity” from conditions “at zero”. By
conditions “at infinity” we mean conditions that only depend on the behaviour of the integrand
for large, positive values of x, whereas by conditions “at zero” we mean conditions that only
depend on the behaviour of the integrand on (0, ϵ) for any ϵ > 0. Since all our conditions are
specified in terms of parameters of the G-functions, this distinction is not immediately visible.
They are, however, of very distinct character mathematically; the conditions at infinity being
in particular much harder to control.
In order for the integral theorem to be valid, conditions n “at zero” and “at infinity” both have
to be fulfilled, for some n.
These are the conditions “at infinity”:

700 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

1.

δ > 0 ∧ | arg(η)| < δπ ∧ (A ∨ B ∨ C),

where

A=1≤n∧p<q∧1≤m

B = 1 ≤ p ∧ 1 ≤ m ∧ q = p + 1 ∧ ¬(n = 0 ∧ m = p + 1)
⌈ ⌉
δ
C = 1 ≤ n ∧ q = p ∧ | arg(η)| ̸= (δ − 2k)π for k = 0, 1, . . . .
2

2.

n = 0 ∧ p + 1 ≤ m ∧ | arg(η)| < δπ

3.

(p < q ∧ 1 ≤ m ∧ δ > 0 ∧ | arg(η)| = δπ) ∨ (p ≤ q − 2 ∧ δ = 0 ∧ arg(η) = 0)

4.
 
∑
p
p = q ∧ δ = 0 ∧ arg(η) = 0 ∧ η ̸= 0 ∧ ℜ  bj − aj  < 0
j=1

5.

δ > 0 ∧ | arg(η)| < δπ

And these are the conditions “at zero”:

1.

η ̸= 0 ∧ C3

2.

C3

3.

C3 ∧ C4

4.

C3

5.

C3

5.13. Symbolic Integrals 701

SymPy Documentation, Release 1.3

Conditions of Convergence for Integral (2)

We introduce the following notation:

u+v
b∗ = s + t −
2
p+q
c∗ = m + n −
2
∑
v ∑
u
u−v
ρ= dj − cj + +1
j=1 j=1
2

∑
q ∑
p
p−q
µ= bj − aj + +1
j=1 j=1
2
u−v
ϕ=q−p− +1
2
η = 1 − (v − u) − µ − ρ
π(q − m − n) + | arg(ω)|
ψ=
q−p
π(v − s − t) + | arg(σ)|)
θ=
v−u
λc = (q − p)|ω|1/(q−p) cos ψ + (v − u)|σ|1/(v−u) cos θ

λs0 (c1 , c2 ) = c1 (q − p)|ω|1/(q−p) sin ψ + c2 (v − u)|σ|1/(v−u) sin θ


λs0 (−1, −1) λs0 (1, 1)


for arg(ω) = 0 ∧ arg(σ) = 0
λ (sign (arg (ω)) , −1) λ (sign (arg (ω)) , 1) for arg(ω) ̸= 0 ∧ arg(σ) = 0
s0 s0
λs =
λs0 (−1, sign (arg (σ))) λs0 (1, sign (arg (σ)))
 for arg(ω) = 0 ∧ arg(σ) ̸= 0)


λs0 (sign (arg (ω)) , sign (arg (σ))) otherwise
ω −iπ(b∗ +c∗ )
e z0 =
σ
σ ∗ ∗
z1 = e−iπ(b +c )
ω
The following conditions will be helpful:

C1 : (ai − bj ∈
/ Z>0 for i = 1, . . . , n, j = 1, . . . , m)
∧(ci − dj ∈
/ Z>0 for i = 1, . . . , t, j = 1, . . . , s)

C2 : ℜ(1 + bi + dj ) > 0 for i = 1, . . . , m, j = 1, . . . , s

C3 : ℜ(ai + cj ) < 1 for i = 1, . . . , n, j = 1, . . . , t

3
C4 : (p − q)ℜ(ci ) − ℜ(µ) > − for i = 1, . . . , t
2
3
C5 : (p − q)ℜ(1 + di ) − ℜ(µ) > − for i = 1, . . . , s
2
3
C6 : (u − v)ℜ(ai ) − ℜ(ρ) > − for i = 1, . . . , n
2
3
C7 : (u − v)ℜ(1 + bi ) − ℜ(ρ) > − for i = 1, . . . , m
2
C8 : 0 < |ϕ| + 2ℜ ((µ − 1) (−u + v) + (−p + q) (ρ − 1) + (−p + q) (−u + v))

702 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

C9 : 0 < |ϕ| − 2ℜ ((µ − 1) (−u + v) + (−p + q) (ρ − 1) + (−p + q) (−u + v))

C10 : |arg (σ)| < πb∗

C11 : |arg (σ)| = πb∗

C12 : | arg(ω)| < c∗ π

C13 : | arg(ω)| = c∗ π
1
C14 : (z0 ̸= 1 ∧ | arg(1 − z0 )| < π) ∨ (z0 = 1 ∧ ℜ(µ + ρ − u + v) < 1)
2
C14 : (z1 ̸= 1 ∧ | arg(1 − z1 )| < π) ∨ (z1 = 1 ∧ ℜ(µ + ρ − p + q) < 1)

C14 : ϕ = 0 ∧ b∗ + c∗ ≤ 1 ∧ (C14
1
∨ C14
2
)

C15 : λc > 0 ∨ (λc = 0 ∧ λs ̸= 0 ∧ ℜ(η) > −1) ∨ (λc = 0 ∧ λs = 0 ∧ ℜ(η) > 0)

∫ ∞
C16 : Gs,t
u,v (σx)dx converges at infinity
0
∫ ∞
C17 : Gm,n
p,q (ωx)dx converges at infinity
0

Note that C16 and C17 are the reason we split the convergence conditions for integral (1).
With this notation established, the implemented convergence conditions can be enumerated
as follows:
1.

mnst ̸= 0 ∧ 0 < b∗ ∧ 0 < c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C10 ∧ C12

2.

u = v ∧ b∗ = 0 ∧ 0 < c∗ ∧ 0 < σ ∧ ℜρ < 1 ∧ C1 ∧ C2 ∧ C3 ∧ C12

3.

p = q ∧ u = v ∧ b∗ = 0 ∧ c∗ = 0 ∧ 0 < σ ∧ 0 < ω ∧ ℜµ < 1 ∧ ℜρ < 1 ∧ σ ̸= ω ∧ C1 ∧ C2 ∧ C3

4.

p = q ∧ u = v ∧ b∗ = 0 ∧ c∗ = 0 ∧ 0 < σ ∧ 0 < ω ∧ ℜ (µ + ρ) < 1 ∧ ω ̸= σ ∧ C1 ∧ C2 ∧ C3

5.

p = q ∧ u = v ∧ b∗ = 0 ∧ c∗ = 0 ∧ 0 < σ ∧ 0 < ω ∧ ℜ (µ + ρ) < 1 ∧ ω ̸= σ ∧ C1 ∧ C2 ∧ C3

6.

q < p ∧ 0 < s ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C5 ∧ C10 ∧ C13

7.

p < q ∧ 0 < t ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C4 ∧ C10 ∧ C13

5.13. Symbolic Integrals 703

SymPy Documentation, Release 1.3

8.

v < u ∧ 0 < m ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ C1 ∧ C2 ∧ C3 ∧ C7 ∧ C11 ∧ C12

9.

u < v ∧ 0 < n ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ C1 ∧ C2 ∧ C3 ∧ C6 ∧ C11 ∧ C12

10.

q < p ∧ u = v ∧ b∗ = 0 ∧ 0 ≤ c∗ ∧ 0 < σ ∧ ℜρ < 1 ∧ C1 ∧ C2 ∧ C3 ∧ C5 ∧ C13

11.

p < q ∧ u = v ∧ b∗ = 0 ∧ 0 ≤ c∗ ∧ 0 < σ ∧ ℜρ < 1 ∧ C1 ∧ C2 ∧ C3 ∧ C4 ∧ C13

12.

p = q ∧ v < u ∧ 0 ≤ b∗ ∧ c∗ = 0 ∧ 0 < ω ∧ ℜµ < 1 ∧ C1 ∧ C2 ∧ C3 ∧ C7 ∧ C11

13.

p = q ∧ u < v ∧ 0 ≤ b∗ ∧ c∗ = 0 ∧ 0 < ω ∧ ℜµ < 1 ∧ C1 ∧ C2 ∧ C3 ∧ C6 ∧ C11

14.

p < q ∧ v < u ∧ 0 ≤ b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C4 ∧ C7 ∧ C11 ∧ C13

15.

q < p ∧ u < v ∧ 0 ≤ b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C5 ∧ C6 ∧ C11 ∧ C13

16.

q < p ∧ v < u ∧ 0 ≤ b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C5 ∧ C7 ∧ C8 ∧ C11 ∧ C13 ∧ C14

17.

p < q ∧ u < v ∧ 0 ≤ b∗ ∧ 0 ≤ c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C4 ∧ C6 ∧ C9 ∧ C11 ∧ C13 ∧ C14

18.

t = 0 ∧ 0 < s ∧ 0 < b∗ ∧ 0 < ϕ ∧ C1 ∧ C2 ∧ C10

19.

s = 0 ∧ 0 < t ∧ 0 < b∗ ∧ ϕ < 0 ∧ C1 ∧ C3 ∧ C10

20.

n = 0 ∧ 0 < m ∧ 0 < c∗ ∧ ϕ < 0 ∧ C1 ∧ C2 ∧ C12

704 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

21.

m = 0 ∧ 0 < n ∧ 0 < c∗ ∧ 0 < ϕ ∧ C1 ∧ C3 ∧ C12

22.

st = 0 ∧ 0 < b∗ ∧ 0 < c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C10 ∧ C12

23.

mn = 0 ∧ 0 < b∗ ∧ 0 < c∗ ∧ C1 ∧ C2 ∧ C3 ∧ C10 ∧ C12

24.

p < m + n ∧ t = 0 ∧ ϕ = 0 ∧ 0 < s ∧ 0 < b∗ ∧ c∗ < 0 ∧ |arg (ω)| < π (m + n − p + 1) ∧ C1 ∧ C2 ∧ C10 ∧ C14 ∧ C15

25.

q < m + n ∧ s = 0 ∧ ϕ = 0 ∧ 0 < t ∧ 0 < b∗ ∧ c∗ < 0 ∧ |arg (ω)| < π (m + n − q + 1) ∧ C1 ∧ C3 ∧ C10 ∧ C14 ∧ C15

26.

p = q − 1 ∧ t = 0 ∧ ϕ = 0 ∧ 0 < s ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ πc∗ < |arg (ω)| ∧ C1 ∧ C2 ∧ C10 ∧ C14 ∧ C15

27.

p = q + 1 ∧ s = 0 ∧ ϕ = 0 ∧ 0 < t ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ πc∗ < |arg (ω)| ∧ C1 ∧ C3 ∧ C10 ∧ C14 ∧ C15

28.

p < q − 1 ∧ t = 0 ∧ ϕ = 0 ∧ 0 < s ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ πc∗ < |arg (ω)| ∧ |arg (ω)| < π (m + n − p + 1) ∧ C1 ∧ C2 ∧ C10 ∧

29.

q + 1 < p ∧ s = 0 ∧ ϕ = 0 ∧ 0 < t ∧ 0 < b∗ ∧ 0 ≤ c∗ ∧ πc∗ < |arg (ω)| ∧ |arg (ω)| < π (m + n − q + 1) ∧ C1 ∧ C3 ∧ C10 ∧

30.

n = 0 ∧ ϕ = 0 ∧ 0 < s + t ∧ 0 < m ∧ 0 < c∗ ∧ b∗ < 0 ∧ |arg (σ)| < π (s + t − u + 1) ∧ C1 ∧ C2 ∧ C12 ∧ C14 ∧ C15

31.

m = 0 ∧ ϕ = 0 ∧ v < s + t ∧ 0 < n ∧ 0 < c∗ ∧ b∗ < 0 ∧ |arg (σ)| < π (s + t − v + 1) ∧ C1 ∧ C3 ∧ C12 ∧ C14 ∧ C15

32.

n = 0 ∧ ϕ = 0 ∧ u = v − 1 ∧ 0 < m ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ πb∗ < |arg (σ)| ∧ |arg (σ)| < π (b∗ + 1) ∧ C1 ∧ C2 ∧ C12 ∧ C14 ∧

33.

m = 0 ∧ ϕ = 0 ∧ u = v + 1 ∧ 0 < n ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ πb∗ < |arg (σ)| ∧ |arg (σ)| < π (b∗ + 1) ∧ C1 ∧ C3 ∧ C12 ∧ C14 ∧

5.13. Symbolic Integrals 705

SymPy Documentation, Release 1.3

34.

n = 0 ∧ ϕ = 0 ∧ u < v − 1 ∧ 0 < m ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ πb∗ < |arg (σ)| ∧ |arg (σ)| < π (s + t − u + 1) ∧ C1 ∧ C2 ∧ C12 ∧

35.

m = 0 ∧ ϕ = 0 ∧ v + 1 < u ∧ 0 < n ∧ 0 < c∗ ∧ 0 ≤ b∗ ∧ πb∗ < |arg (σ)| ∧ |arg (σ)| < π (s + t − v + 1) ∧ C1 ∧ C3 ∧ C12 ∧

36.

C17 ∧ t = 0 ∧ u < s ∧ 0 < b∗ ∧ C10 ∧ C1 ∧ C2 ∧ C3

37.

C17 ∧ s = 0 ∧ v < t ∧ 0 < b∗ ∧ C10 ∧ C1 ∧ C2 ∧ C3

38.

C16 ∧ n = 0 ∧ p < m ∧ 0 < c∗ ∧ C12 ∧ C1 ∧ C2 ∧ C3

39.

C16 ∧ m = 0 ∧ q < n ∧ 0 < c∗ ∧ C12 ∧ C1 ∧ C2 ∧ C3

The Inverse Laplace Transform of a G-function

The inverse laplace transform of a Meijer G-function can be expressed as another G-function.
This is a fairly versatile method for computing this transform. However, I could not find the
details in the literature, so I work them out here. In [Luke1969], section 5.6.3, there is a
formula for the inverse Laplace transform of a G-function of argument bz, and convergence
conditions are also given. However, we need a formula for argument bz a for rational a.
We are asked to compute
∫ c+i∞
1
f (t) = ezt G(bz a )dz,
2πi c−i∞

for positive real t. Three questions arise:

1. When does this integral converge?
2. How can we compute the integral?
3. When is our computation valid?

How to compute the integral

We shall work formally for now. Denote by ∆(s) the product of gamma functions appearing in
the definition of G, so that
∫
1
G(z) = ∆(s)z s ds.
2πi L

706 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Thus
∫ c+i∞ ∫
1
f (t) = ezt ∆(s)bs z as dsdz.
(2πi)2 c−i∞ L

We interchange the order of integration to get

∫ ∫ c+i∞
1 dz
f (t) = bs ∆(s) ezt z as ds.
2πi L c−i∞ 2πi
1 1
The inner integral is easily seen to be Γ(−as) t1+as . (Using Cauchy’s theorem and Jordan’s
lemma deform the contour to run from −∞ to −∞, encircling 0 once in the negative sense.
For as real and greater than one, this contour can be pushed onto the negative real axis
and the integral is recognised as a product of a sine and a gamma function. The formula is
then proved using the functional equation of the gamma function, and extended to the entire
domain of convergence of the original integral by appealing to analytic continuation.) Hence
we find
∫ ( )s
1 1 1 b
f (t) = ∆(s) ds,
t 2πi L Γ(−as) ta
which is a so-called Fox H function (of argument tba ). For rational a, this can be expressed as
a Meijer G-function using the gamma function multiplication theorem.

When this computation is valid

There are a number of obstacles in this computation. Interchange of integrals is only valid
if all integrals involved are absolutely convergent. In particular the inner integral has to
converge. Also, for our identification of the final integral as a Fox H / Meijer G-function to be
correct, the poles of the newly obtained gamma function must be separated properly.
It is easy to check that the inner integral converges absolutely for ℜ(as) < −1. Thus the contour
L has to run left of the line ℜ(as) = −1. Under this condition, the poles of the newly-introduced
gamma function are separated properly.
It remains to observe that the Meijer G-function is an analytic, unbranched function of its
parameters, and of the coefficient b. Hence so is f (t). Thus the final computation remains
valid as long as the initial integral converges, and if there exists a changed set of parameters
where the computation is valid. If we assume w.l.o.g. that a > 0, then the latter condition is
fulfilled if G converges along contours (2) or (3) of [Luke1969], section 5.2, i.e. either δ >= a2
or p ≥ 1, p ≥ q.

When the integral exists

Using [Luke1969], section 5.10, for any given meijer G-function we can find a dominant term
c
of the form z a ebz (although this expression might not be the best possible, because of cancel-
lation).
We must thus investigate
∫ c+iT
c
lim ezt z a ebz dz.
T →∞ c−iT

(This principal value integral is the exact statement used in the Laplace inversion theorem.)
We write z = c + iτ . Then arg(z) → ± π2 , and so ezt ∼ eitτ (where ∼ shall always mean “asymptot-
ically equivalent up to a positive real multiplicative constant”). Also z x+iy ∼ |τ |x eiy log |τ | e±xi 2 .
π

5.13. Symbolic Integrals 707

SymPy Documentation, Release 1.3

Set ω± = be±iℜ(c) 2 . We have three cases:

π

1. b = 0 or ℜ(c) ≤ 0. In this case the integral converges if ℜ(a) ≤ −1.

2. b ̸= 0, ℑ(c) = 0, ℜ(c) > 0. In this case the integral converges if ℜ(ω± ) < 0.
3. b ̸= 0, ℑ(c) = 0, ℜ(c) > 0, ℜ(ω± ) ≤ 0, and at least one of ℜ(ω± ) = 0. Here the same condition
as in (1) applies.

Implemented G-Function Formulae

An important part of the algorithm is a table expressing various functions as Meijer G-

functions. This is essentially a table of Mellin Transforms in disguise. The following auto-
matically generated table shows the formulae currently implemented in SymPy. An entry
“generated” means that the corresponding G-function has a variable number of parameters.
This table is intended to shrink in future, when the algorithm’s capabilities of deriving new
formulae improve. Of course it has to grow whenever a new class of special functions is to
be dealt with.
Elementary functions:
( ) ( )
1 1
a= aG1,0
1,1 z + 0,1
aG1,1 z
0 0
( )
−a −a + 1 zq p
b G1,1
1,1 b
−a 0
(z q p + b) =
Γ (a)
( )
a−1 2,2 0, a zq p
a b G2,2 sin (πa)
−ba + (z q p) 0, a b
=
zq p − b π
(b 1 b )
b 1,2 2 + 2, 2 + 1 zq p
( √ )b a bG2,2
0 b a2
a + z q p + a2 = − √
2 π
(b 1 b )
b 1,2 2 + 2, 2 + 1 zq p
( √ )b a bG2,2
b 0 a2
−a + z q p + a2 = √
2 π
(b 1 b )
( √ )b b−1 1,2 + 2, 2 zq p
a G2,2 2
a + z q p + a2 0 b a2
√ = √
z q p + a2 π
(b 1 b )
( √ )b
a b−1 1,2
G 2 + 2, 2 zq p
−a + z p + aq 2 2,2 b 0 a2
√ = √
z q p + a2 π
(b )
b 2,1 2 + 1 − b
2 + 1 z q
p
( q√ √ )b a 2 bG2,2
0, 21 a
z 2 p + zq p + a = − √
2 π
( b )
2,1 − 2 + 1
b
2 +1 z p
b q

( q√ √ )b a 2 bG
2,2 0, 12 a
−z 2 p + z q p + a = √
2 π

708 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(b )
( )b + 12 − 2b + 1 q
√ a 2 − 2 G2,1
b 1
q √ 2 2 z p
z 2 p + zq p + a 2,2 0, 12 a
√ q = √
z p+a π
( )
( )b − 2b + 12 b
+ 1 q
√ a 2 − 2 G2,1
b 1
√ q 2 2 z p
−z p + zq p + a
2 2,2 0, 12 a
√ q = √
z p+a π
Functions involving |z q p − b|:
( ) ( πa )
−a −a + 1 − a2 + 1 zq p −a
|z q p − b| = 2G1,1 2 sin |b| Γ (−a + 1) , if ℜ(a) < 1
2,2 0 − a2 + 1
2 b 2
Functions involving Chi (z q p):
( 1
)
2, 1 z p
3 2q 2
π 2 G2,0
2,4 1 1 4
0, 0 2, 2
Chi (z q p) = −
2
Functions involving Ci (z q p):
( )
√ 1 z 2q p2
πG2,0
1,3 1 4
0, 0
Ci (z q p) = − 2
2
Functions involving Ei (z q p):
( ) ( ) ( )
1 1 1
q
Ei (z p) = −iπG1,0
1,1 z − G2,0
1,2 z peq iπ
− iπG0,1
1,1 z
0 0, 0 0

Functions involving θ (z q p − b):

) (
a−1 zq p a
(z q p − b) θ (z q p − b) = ba−1 G0,1
1,1 Γ (a) , if b > 0
0 b
( )
a−1 a zq p
(−z q p + b) θ (−z q p + b) = ba−1 G1,0
1,1 0 Γ (a) , if b > 0
b
( ( ) q1 ) ( )
a−1 b a−1 0,1 a zq p
(z p − b)
q
θ z− =b G1,1 Γ (a) , if b > 0
p 0 b
( ( ) q1 ) ( )
a−1 b a−1 1,0 a zq p
q
(−z p + b) θ −z + =b G1,1 Γ (a) , if b > 0
p 0 b
Functions involving θ (−z q p + 1), log (z q p):
n
log (z q p) θ (−z q p + 1) = generated
n
log (z q p) θ (z q p − 1) = generated
Functions involving Shi (z q p):
(1 )
√ z 2q p2 eiπ
z q
πpG1,1 2
1,3 0 − 21 , − 12 4
Shi (z q p) =
4
q
Functions involving Si (z p):
( )
√ 1 z 2q p2
πG1,1
1,3 1 4
0, 0
Si (z q p) = 2
2

5.13. Symbolic Integrals 709

SymPy Documentation, Release 1.3

Functions involving Ia (z q p):

( )
a
2 + 2
1 z 2q p2
q
Ia (z p) = πG1,0
1,3 a
2 − 2 , 2 + 12
a a
4
Functions involving Ja (z q p):
( )
z 2q p2
Ja (z q p) = G1,0
0,2 a
2 − a2 4
Functions involving Ka (z q p):
( )
z 2q p2
G2,0
2,−2
0,2 a a 4
Ka (z q p) =
2
q
Functions involving Ya (z p):
( )
− a2 − 1 z 2q p2
q
Ya (z p) = G2,0 2
2,−2 − a2 −
1,3 a a 1
2 4
Functions involving cos (z q p):
( )
√ z 2q p2
cos (z q p) = πG1,0
0,2 1
0 2 4
Functions involving cosh (z q p):
( )
3
1 z 2q p2
cosh (z q p) = π 2 G1,0
1,3 1 1
2
0 2, 2 4
Functions involving E (z q p):
(1 3
)
G1,2 2, 2 −z p q
2,2 0 0
E (z q p) = −
4
q
Functions involving K (z p):
(1 1
)
G1,2 2, 2 −z pq
2,2 0 0
K (z q p) =
2
q
Functions involving erf (z p):
( )
1
G1,1
1,2 1 z p 2q 2
0
erf (z q p) = 2
√
π
Functions involving erfc (z q p):
( )
1
G2,0 z 2q p2
1,2 0, 12
erfc (z q p) = √
π
Functions involving erfi (z q p):
(1 )
z q pG1,1 2 −z 2q p2
1,2 0 − 12
erfi (z q p) = √
π

710 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

q
peiπ
Functions involving ez :
( )
z q peiπ
e = G1,0
0,1
q
z p
0

Functions involving Ea (z q p):

( )
a
q
Ea (z p) = G2,0 q
z p
1,2 a − 1, 0

Functions involving C (z q p):

( )
1 z 4q π 2 p4
G1,1
1,3 1 3 16
0,
C (z q p) = 4 4
2
Functions involving S (z q p):
( )
1 z 4q π 2 p4
G1,1
1,3 3 1 16
0,
S (z q p) = 4 4
2
Functions involving log (z q p):
n
log (z q p) = generated
( ) ( ) ( )
1 1 1, 1 zq p
log (z q p + a) = G1,0
1,1 z log (a) + G0,1
1,1 z log (a) + G1,2
2,2
0 0 1 0 a
( ) ( ) ( 1 zq p
)
1 1 1,2 1, 1
log (|z p − a|) =
q
G1,0 z log (|a|) + G0,1 z log (|a|) + πG3,3 2
1,1 0 1,1 0 1 0, 21 a
Functions involving sin (z q p):
( )
√ z 2q p2
q
sin (z p) = πG1,0
0,2 1
2 0 4

Functions involving sinc (z q p):

( )
√ z 2q p2
πG1,0
0,2 0 − 12 4
sinc (z q p) =
2
Functions involving sinh (z q p):
( )
3 1 z 2q p2
q
sinh (z p) = π 2 G1,0
1,3 1
2 1, 0 4

5.13.4 API reference

sympy.integrals.integrate(f, var, ...)

Compute definite or indefinite integral of one or more variables using Risch-Norman
algorithm and table lookup. This procedure is able to handle elementary algebraic
and transcendental functions and also a huge class of special functions, including Airy,
Bessel, Whittaker and Lambert.
var can be:

5.13. Symbolic Integrals 711

SymPy Documentation, Release 1.3

• a symbol – indefinite integration

• a tuple (symbol, a) – indefinite integration with result given with a replacing
symbol
• a tuple (symbol, a, b) – definite integration
Several variables can be specified, in which case the result is multiple integration. (If
var is omitted and the integrand is univariate, the indefinite integral in that variable will
be performed.)
Indefinite integrals are returned without terms that are independent of the integration
variables. (see examples)
Definite improper integrals often entail delicate convergence conditions. Pass
conds=’piecewise’, ‘separate’ or ‘none’ to have these returned, respectively, as a Piece-
wise function, as a separate result (i.e. result will be a tuple), or not at all (default is
‘piecewise’).
Strategy
SymPy uses various approaches to definite integration. One method is to find an an-
tiderivative for the integrand, and then use the fundamental theorem of calculus. Various
functions are implemented to integrate polynomial, rational and trigonometric functions,
and integrands containing DiracDelta terms.
SymPy also implements the part of the Risch algorithm, which is a decision procedure
for integrating elementary functions, i.e., the algorithm can either find an elementary
antiderivative, or prove that one does not exist. There is also a (very successful, albeit
somewhat slow) general implementation of the heuristic Risch algorithm. This algorithm
will eventually be phased out as more of the full Risch algorithm is implemented. See the
docstring of Integral._eval_integral() for more details on computing the antiderivative
using algebraic methods.
The option risch=True can be used to use only the (full) Risch algorithm. This is useful
if you want to know if an elementary function has an elementary antiderivative. If the
indefinite Integral returned by this function is an instance of NonElementaryIntegral,
that means that the Risch algorithm has proven that integral to be non-elementary. Note
that by default, additional methods (such as the Meijer G method outlined below) are
tried on these integrals, as they may be expressible in terms of special functions, so if
you only care about elementary answers, use risch=True. Also note that an unevaluated
Integral returned by this function is not necessarily a NonElementaryIntegral, even with
risch=True, as it may just be an indication that the particular part of the Risch algorithm
needed to integrate that function is not yet implemented.
Another family of strategies comes from re-writing the integrand in terms of so-called
Meijer G-functions. Indefinite integrals of a single G-function can always be computed,
and the definite integral of a product of two G-functions can be computed from zero to
infinity. Various strategies are implemented to rewrite integrands as G-functions, and
use this information to compute integrals (see the meijerint module).
The option manual=True can be used to use only an algorithm that tries to mimic in-
tegration by hand. This algorithm does not handle as many integrands as the other
algorithms implemented but may return results in a more familiar form. The manualin-
tegrate module has functions that return the steps used (see the module docstring for
more information).
In general, the algebraic methods work best for computing antiderivatives of (possibly
complicated) combinations of elementary functions. The G-function methods work best

712 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

for computing definite integrals from zero to infinity of moderately complicated combi-
nations of special functions, or indefinite integrals of very simple combinations of special
functions.
The strategy employed by the integration code is as follows:
• If computing a definite integral, and both limits are real, and at least one limit is +-
oo, try the G-function method of definite integration first.
• Try to find an antiderivative, using all available methods, ordered by performance
(that is try fastest method first, slowest last; in particular polynomial integration is
tried first, Meijer G-functions second to last, and heuristic Risch last).
• If still not successful, try G-functions irrespective of the limits.
The option meijerg=True, False, None can be used to, respectively: always use G-
function methods and no others, never use G-function methods, or use all available meth-
ods (in order as described above). It defaults to None.
See also:
Integral (page 714), Integral.doit (page 716)

Examples

>>> from sympy import integrate, log, exp, oo

>>> from sympy.abc import a, x, y

>>> integrate(x*y, x)
x**2*y/2

>>> integrate(log(x), x)
x*log(x) - x

>>> integrate(log(x), (x, 1, a))

a*log(a) - a + 1

>>> integrate(x)
x**2/2

Terms that are independent of x are dropped by indefinite integration:

>>> from sympy import sqrt

>>> integrate(sqrt(1 + x), (x, 0, x))
2*(x + 1)**(3/2)/3 - 2/3
>>> integrate(sqrt(1 + x), x)
2*(x + 1)**(3/2)/3

>>> integrate(x*y)
Traceback (most recent call last):
...
ValueError: specify integration variables to integrate x*y

Note that integrate(x) syntax is meant only for convenience in interactive sessions and
should be avoided in library code.

5.13. Symbolic Integrals 713

SymPy Documentation, Release 1.3

>>> integrate(x**a*exp(-x), (x, 0, oo)) # same as conds='piecewise'

Piecewise((gamma(a + 1), -re(a) < 1),
(Integral(x**a*exp(-x), (x, 0, oo)), True))

>>> integrate(x**a*exp(-x), (x, 0, oo), conds='none')

gamma(a + 1)

>>> integrate(x**a*exp(-x), (x, 0, oo), conds='separate')

(gamma(a + 1), -re(a) < 1)

sympy.integrals.line_integrate(field, Curve, variables)

Compute the line integral.
See also:
integrate (page 711), Integral (page 714)

Examples

>>> from sympy import Curve, line_integrate, E, ln

>>> from sympy.abc import x, y, t
>>> C = Curve([E**t + 1, E**t - 1], (t, 0, ln(2)))
>>> line_integrate(x + y, C, [x, y])
3*sqrt(2)

The class Integral represents an unevaluated integral and has some methods that help in the
integration of an expression.
class sympy.integrals.Integral
Represents unevaluated integral.
is_commutative
Returns whether all the free symbols in the integral are commutative.
as_sum(n=None, method=’midpoint’, evaluate=True)
Approximates a definite integral by a sum.
See also:

Integral.doit (page 716) Perform the integration using any hints

Examples

>>> from sympy import sin, sqrt

>>> from sympy.abc import x, n
>>> from sympy.integrals import Integral
>>> e = Integral(sin(x), (x, 3, 7))
>>> e
Integral(sin(x), (x, 3, 7))

For demonstration purposes, this interval will only be split into 2 regions, bounded
by [3, 5] and [5, 7].
The left-hand rule uses function evaluations at the left of each interval:

714 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> e.as_sum(2, 'left')

2*sin(5) + 2*sin(3)

The midpoint rule uses evaluations at the center of each interval:

>>> e.as_sum(2, 'midpoint')

2*sin(4) + 2*sin(6)

The right-hand rule uses function evaluations at the right of each interval:

>>> e.as_sum(2, 'right')

2*sin(5) + 2*sin(7)

The trapezoid rule uses function evaluations on both sides of the intervals. This is
equivalent to taking the average of the left and right hand rule results:

>>> e.as_sum(2, 'trapezoid')

2*sin(5) + sin(3) + sin(7)
>>> (e.as_sum(2, 'left') + e.as_sum(2, 'right'))/2 == _
True

Here, the discontinuity at x = 0 can be avoided by using the midpoint or right-hand

method:

>>> e = Integral(1/sqrt(x), (x, 0, 1))

>>> e.as_sum(5).n(4)
1.730
>>> e.as_sum(10).n(4)
1.809
>>> e.doit().n(4) # the actual value is 2
2.000

The left- or trapezoid method will encounter the discontinuity and return infinity:

>>> e.as_sum(5, 'left')

zoo

The number of intervals can be symbolic. If omitted, a dummy symbol will be used
for it. >>> e = Integral(x**2, (x, 0, 2)) >>> e.as_sum(n, ‘right’).expand() 8/3 + 4/n
+ 4/(3*n**2)
This shows that the midpoint rule is more accurate, as its error term decays as the
square of n: >>> e.as_sum(method=’midpoint’).expand() 8/3 - 2/(3*_n**2)
A symbolic sum is returned with evaluate=False: >>> e.as_sum(n, ‘midpoint’, eval-
uate=False) 2*Sum((2*_k/n - 1/n)**2, (_k, 1, n))/n

Arguments

n The number of subintervals to use, optional.

method One of: ‘left’, ‘right’, ‘midpoint’, ‘trapezoid’.
evaluate If False, returns an unevaluated Sum expression. The default is True,
evaluate the sum.

5.13. Symbolic Integrals 715

SymPy Documentation, Release 1.3

These methods of approximate integration are described in [1].

[1] https://en.wikipedia.org/wiki/Riemann_sum#Methods
doit(**hints)
Perform the integration using any hints given.
See also:
sympy.integrals.trigonometry.trigintegrate, sympy.integrals.risch.
heurisch, sympy.integrals.rationaltools.ratint
as_sum (page 714) Approximate the integral using a sum

Examples

>>> from sympy import Integral

>>> from sympy.abc import x, i
>>> Integral(x**i, (i, 1, 3)).doit()
Piecewise((x**3/log(x) - x/log(x),
(x > 1) | ((x >= 0) & (x < 1))), (2, True))

free_symbols
This method returns the symbols that will exist when the integral is evaluated. This
is useful if one is trying to determine whether an integral depends on a certain
symbol or not.
See also:
function, limits, variables

Examples

>>> from sympy import Integral

>>> from sympy.abc import x, y
>>> Integral(x, (x, y, 1)).free_symbols
{y}

principal_value(**kwargs)
Compute the Cauchy Principal Value of the definite integral of a real function in
the given interval on the real axis. In mathematics, the Cauchy principal value, is
a method for assigning values to certain improper integrals which would otherwise
be undefined.

References

[R410], [R411]

Examples

716 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Dummy, symbols, integrate, limit, oo

>>> from sympy.integrals.integrals import Integral
>>> from sympy.calculus.singularities import singularities
>>> x = symbols('x')
>>> Integral(x+1, (x, -oo, oo)).principal_value()
oo
>>> f = 1 / (x**3)
>>> Integral(f, (x, -oo, oo)).principal_value()
0
>>> Integral(f, (x, -10, 10)).principal_value()
0
>>> Integral(f, (x, -10, oo)).principal_value() + Integral(f, (x, -oo, 10)).
,→principal_value()

transform(x, u)
Performs a change of variables from x to u using the relationship given by x and u
which will define the transformations f and F (which are inverses of each other) as
follows:
1) If x is a Symbol (which is a variable of integration) then u will be interpreted as
some function, f(u), with inverse F(u). This, in effect, just makes the substitution
of x with f(x).
2) If u is a Symbol then x will be interpreted as some function, F(x), with inverse
f(u). This is commonly referred to as u-substitution.
Once f and F have been identified, the transformation is made as follows:
∫ b ∫ F (b)
d
xdx → f (x)
a F (a) dx

where F (x) is the inverse of f (x) and the limits and integrand have been corrected
so as to retain the same value after integration.
See also:

variables Lists the integration variables

as_dummy Replace integration variables with dummy ones

Notes

The mappings, F(x) or f(u), must lead to a unique integral. Linear or rational linear
expression, 2 ∗ x, 1/x and sqrt(x), will always work; quadratic expressions like x ∗ ∗2 − 1
are acceptable as long as the resulting integrand does not depend on the sign of the
solutions (see examples).
The integral will be returned unchanged if x is not a variable of integration.
x must be (or contain) only one of of the integration variables. If u has more than
one free symbol then it should be sent as a tuple (u, uvar) where uvar identifies which
variable is replacing the integration variable. XXX can it contain another integration
variable?

5.13. Symbolic Integrals 717

SymPy Documentation, Release 1.3

Examples

>>> from sympy.abc import a, b, c, d, x, u, y

>>> from sympy import Integral, S, cos, sqrt

>>> i = Integral(x*cos(x**2 - 1), (x, 0, 1))

transform can change the variable of integration

>>> i.transform(x, u)
Integral(u*cos(u**2 - 1), (u, 0, 1))

transform can perform u-substitution as long as a unique integrand is obtained:

>>> i.transform(x**2 - 1, u)
Integral(cos(u)/2, (u, -1, 0))

This attempt fails because x = +/-sqrt(u + 1) and the sign does not cancel out of the
integrand:

>>> Integral(cos(x**2 - 1), (x, 0, 1)).transform(x**2 - 1, u)

Traceback (most recent call last):
...
ValueError:
The mapping between F(x) and f(u) did not give a unique integrand.

transform can do a substitution. Here, the previous result is transformed back into
the original expression using “u-substitution”:

>>> ui = _
>>> _.transform(sqrt(u + 1), x) == i
True

We can accomplish the same with a regular substitution:

>>> ui.transform(u, x**2 - 1) == i

True

If the x does not contain a symbol of integration then the integral will be returned
unchanged. Integral i does not have an integration variable a so no change is made:

>>> i.transform(a, x) == i
True

When u has more than one free symbol the symbol that is replacing x must be iden-
tified by passing u as a tuple:

>>> Integral(x, (x, 0, 1)).transform(x, (u + a, u))

Integral(a + u, (u, -a, -a + 1))
>>> Integral(x, (x, 0, 1)).transform(x, (u + a, a))
Integral(a + u, (a, -u, -u + 1))

718 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.13.5 TODO and Bugs

There are still lots of functions that SymPy does not know how to integrate. For bugs related
to this module, see https://github.com/sympy/sympy/issues?q=label%3AIntegration

5.14 Numeric Integrals

SymPy has functions to calculate points and weights for Gaussian quadrature of any order
and any precision:
sympy.integrals.quadrature.gauss_legendre(n, n_digits)
Computes the Gauss-Legendre quadrature [R412] points and weights.
The Gauss-Legendre quadrature approximates the integral:
∫ 1 ∑
n
f (x) dx ≈ wi f (xi )
−1 i=1

The nodes xi of an order n quadrature rule are the roots of Pn and the weights wi are
given by:
2
wi = 2
(1 − x2i ) (Pn′ (xi ))
Parameters n : the order of quadrature
n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_laguerre (page 719), gauss_gen_laguerre (page 721), gauss_hermite
(page 720), gauss_chebyshev_t (page 722), gauss_chebyshev_u (page 723),
gauss_jacobi (page 724), gauss_lobatto

References

[R412], [R413]

Examples

>>> from sympy.integrals.quadrature import gauss_legendre

>>> x, w = gauss_legendre(3, 5)
>>> x
[-0.7746, 0, 0.7746]
>>> w
[0.55556, 0.88889, 0.55556]
>>> x, w = gauss_legendre(4, 5)
>>> x
[-0.86114, -0.33998, 0.33998, 0.86114]
>>> w
[0.34785, 0.65215, 0.65215, 0.34785]

5.14. Numeric Integrals 719

SymPy Documentation, Release 1.3

sympy.integrals.quadrature.gauss_laguerre(n, n_digits)
Computes the Gauss-Laguerre quadrature [R414] points and weights.
The Gauss-Laguerre quadrature approximates the integral:
∫ ∞ ∑
n
e−x f (x) dx ≈ wi f (xi )
0 i=1

The nodes xi of an order n quadrature rule are the roots of Ln and the weights wi are
given by:
xi
wi = 2
(n + 1)2 (Ln+1 (xi ))
Parameters n : the order of quadrature
n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_legendre (page 719), gauss_gen_laguerre (page 721), gauss_hermite
(page 720), gauss_chebyshev_t (page 722), gauss_chebyshev_u (page 723),
gauss_jacobi (page 724), gauss_lobatto

References

[R414], [R415]

Examples

>>> from sympy.integrals.quadrature import gauss_laguerre

>>> x, w = gauss_laguerre(3, 5)
>>> x
[0.41577, 2.2943, 6.2899]
>>> w
[0.71109, 0.27852, 0.010389]
>>> x, w = gauss_laguerre(6, 5)
>>> x
[0.22285, 1.1889, 2.9927, 5.7751, 9.8375, 15.983]
>>> w
[0.45896, 0.417, 0.11337, 0.010399, 0.00026102, 8.9855e-7]

sympy.integrals.quadrature.gauss_hermite(n, n_digits)
Computes the Gauss-Hermite quadrature [R416] points and weights.
The Gauss-Hermite quadrature approximates the integral:
∫ ∞ ∑
n
e−x f (x) dx ≈
2
wi f (xi )
−∞ i=1

The nodes xi of an order n quadrature rule are the roots of Hn and the weights wi are
given by:
√
2n−1 n! π
wi = 2
n2 (Hn−1 (xi ))

720 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters n : the order of quadrature

n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_legendre (page 719), gauss_laguerre (page 719), gauss_gen_laguerre
(page 721), gauss_chebyshev_t (page 722), gauss_chebyshev_u (page 723),
gauss_jacobi (page 724), gauss_lobatto

References

[R416], [R417], [R418]

Examples

>>> from sympy.integrals.quadrature import gauss_hermite

>>> x, w = gauss_hermite(3, 5)
>>> x
[-1.2247, 0, 1.2247]
>>> w
[0.29541, 1.1816, 0.29541]

>>> x, w = gauss_hermite(6, 5)
>>> x
[-2.3506, -1.3358, -0.43608, 0.43608, 1.3358, 2.3506]
>>> w
[0.00453, 0.15707, 0.72463, 0.72463, 0.15707, 0.00453]

sympy.integrals.quadrature.gauss_gen_laguerre(n, alpha, n_digits)

Computes the generalized Gauss-Laguerre quadrature [R419] points and weights.
The generalized Gauss-Laguerre quadrature approximates the integral:
∫ ∞ ∑
n
xα e−x f (x) dx ≈ wi f (xi )
0 i=1

The nodes xi of an order n quadrature rule are the roots of Lα

n and the weights wi are
given by:

Γ(α + n)
wi = α+1
nΓ(n)Lα
n−1 (xi )Ln−1 (xi )

Parameters n : the order of quadrature

alpha : the exponent of the singularity, α > −1
n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.

5.14. Numeric Integrals 721

SymPy Documentation, Release 1.3

See also:
gauss_legendre (page 719), gauss_laguerre (page 719), gauss_hermite (page 720),
gauss_chebyshev_t (page 722), gauss_chebyshev_u (page 723), gauss_jacobi
(page 724), gauss_lobatto

References

[R419], [R420]

Examples

>>> from sympy import S

>>> from sympy.integrals.quadrature import gauss_gen_laguerre
>>> x, w = gauss_gen_laguerre(3, -S.Half, 5)
>>> x
[0.19016, 1.7845, 5.5253]
>>> w
[1.4493, 0.31413, 0.00906]

>>> x, w = gauss_gen_laguerre(4, 3*S.Half, 5)

>>> x
[0.97851, 2.9904, 6.3193, 11.712]
>>> w
[0.53087, 0.67721, 0.11895, 0.0023152]

sympy.integrals.quadrature.gauss_chebyshev_t(n, n_digits)
Computes the Gauss-Chebyshev quadrature [R421] points and weights of the first kind.
The Gauss-Chebyshev quadrature of the first kind approximates the integral:
∫ 1 ∑n
1
√ f (x) dx ≈ wi f (xi )
−1 1 − x2 i=1

The nodes xi of an order n quadrature rule are the roots of Tn and the weights wi are
given by:
π
wi =
n
Parameters n : the order of quadrature
n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_legendre (page 719), gauss_laguerre (page 719), gauss_hermite (page 720),
gauss_gen_laguerre (page 721), gauss_chebyshev_u (page 723), gauss_jacobi
(page 724), gauss_lobatto

References

[R421], [R422]

722 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import S

>>> from sympy.integrals.quadrature import gauss_chebyshev_t
>>> x, w = gauss_chebyshev_t(3, 5)
>>> x
[0.86602, 0, -0.86602]
>>> w
[1.0472, 1.0472, 1.0472]

>>> x, w = gauss_chebyshev_t(6, 5)
>>> x
[0.96593, 0.70711, 0.25882, -0.25882, -0.70711, -0.96593]
>>> w
[0.5236, 0.5236, 0.5236, 0.5236, 0.5236, 0.5236]

sympy.integrals.quadrature.gauss_chebyshev_u(n, n_digits)
Computes the Gauss-Chebyshev quadrature [R423] points and weights of the second
kind.
The Gauss-Chebyshev quadrature of the second kind approximates the integral:
∫ 1 √ ∑
n
1 − x2 f (x) dx ≈ wi f (xi )
−1 i=1

The nodes xi of an order n quadrature rule are the roots of Un and the weights wi are
given by:
( )
π 2 i
wi = sin π
n+1 n+1

Parameters n : the order of quadrature

n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_legendre (page 719), gauss_laguerre (page 719), gauss_hermite (page 720),
gauss_gen_laguerre (page 721), gauss_chebyshev_t (page 722), gauss_jacobi
(page 724), gauss_lobatto

References

[R423], [R424]

Examples

>>> from sympy import S

>>> from sympy.integrals.quadrature import gauss_chebyshev_u
>>> x, w = gauss_chebyshev_u(3, 5)
>>> x
(continues on next page)

5.14. Numeric Integrals 723

SymPy Documentation, Release 1.3

(continued from previous page)

[0.70711, 0, -0.70711]
>>> w
[0.3927, 0.7854, 0.3927]

>>> x, w = gauss_chebyshev_u(6, 5)
>>> x
[0.90097, 0.62349, 0.22252, -0.22252, -0.62349, -0.90097]
>>> w
[0.084489, 0.27433, 0.42658, 0.42658, 0.27433, 0.084489]

sympy.integrals.quadrature.gauss_jacobi(n, alpha, beta, n_digits)

Computes the Gauss-Jacobi quadrature [R425] points and weights.
The Gauss-Jacobi quadrature of the first kind approximates the integral:
∫ 1 ∑
n
(1 − x)α (1 + x)β f (x) dx ≈ wi f (xi )
−1 i=1

(α,β)
The nodes xi of an order n quadrature rule are the roots of Pn and the weights wi are
given by:

2n + α + β + 2 Γ(n + α + 1)Γ(n + β + 1) 2α+β

wi = −
n + α + β + 1 Γ(n + α + β + 1)(n + 1)! Pn′ (xi )P (α,β) (xi )
n+1

Parameters n : the order of quadrature

alpha : the first parameter of the Jacobi Polynomial, α > −1
beta : the second parameter of the Jacobi Polynomial, β > −1
n_digits : number of significant digits of the points and weights to return
Returns (x, w) : the x and w are lists of points and weights as Floats.
The points xi and weights wi are returned as (x, w) tuple of lists.
See also:
gauss_legendre (page 719), gauss_laguerre (page 719), gauss_hermite (page 720),
gauss_gen_laguerre (page 721), gauss_chebyshev_t (page 722), gauss_chebyshev_u
(page 723), gauss_lobatto

References

[R425], [R426], [R427]

Examples

>>> from sympy import S

>>> from sympy.integrals.quadrature import gauss_jacobi
>>> x, w = gauss_jacobi(3, S.Half, -S.Half, 5)
>>> x
[-0.90097, -0.22252, 0.62349]
>>> w
[1.7063, 1.0973, 0.33795]

724 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> x, w = gauss_jacobi(6, 1, 1, 5)
>>> x
[-0.87174, -0.5917, -0.2093, 0.2093, 0.5917, 0.87174]
>>> w
[0.050584, 0.22169, 0.39439, 0.39439, 0.22169, 0.050584]

5.15 Integration over Polytopes

The intpoly module in SymPy implements methods to calculate the integral of a polynomial
over 2/3-Polytopes. Uses evaluation techniques as described in Chin et al. (2015) [1].
The input for 2-Polytope or Polygon uses the already existing Polygon data structure in SymPy.
See sympy.geometry.polygon (page 650) for how to create a polygon.
For the 3-Polytope or Polyhedron, the most economical representation is to specify a list of
vertices and then to provide each constituting face(Polygon) as a list of vertex indices.
For example, consider the unit cube. Here is how it would be represented.
unit_cube = [[(0, 0, 0), (0, 0, 1), (0, 1, 0), (0, 1, 1), (1, 0, 0),(1, 0, 1), (1, 1, 0), (
[3, 7, 6, 2], [1, 5, 7, 3], [5, 4, 6, 7], [0, 4, 5, 1], [2, 0, 1, 3], [2,
6, 4, 0]]
Here, the first sublist is the list of vertices. The other smaller lists such as [3, 7, 6, 2]
represent a 2D face of the polyhedra with vertices having index 3, 7, 6 and 2 in the first
sublist(in that order).
Principal method in this module is polytope_integrate() (page 727)
• polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), x) returns the integral of
x over the triangle with vertices (0, 0), (0, 1) and (1, 0)
• polytope_integrate(unit_cube, x + y + z) returns the integral of x + y + z over the
unit cube.

5.15.1 References

[1] : Chin, Eric B., Jean B. Lasserre, and N. Sukumar. “Numerical integration of homogeneous
functions on convex and nonconvex polygons and polyhedra.” Computational Mechanics 56.6
(2015): 967-981
PDF link : http://dilbert.engr.ucdavis.edu/~suku/quadrature/cls-integration.pdf

5.15.2 Examples

5.15.3 For 2D Polygons

Single Polynomial:

>>> from sympy.integrals.intpoly import *

>>> init_printing(use_unicode=False, wrap_line=False)
>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), x)
(continues on next page)

5.15. Integration over Polytopes 725

SymPy Documentation, Release 1.3

(continued from previous page)

1/6
>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), x + x*y + y**2)
7/24

List of specified polynomials:

>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), [3, x*y + y**2, x**4], max_
,→degree=4)

4 2
{3: 3/2, x : 1/30, x*y + y : 1/8}
>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), [1.125, x, x**2, 6.89*x**3,␣
,→x*y + y**2, x**4], max_degree=4)

2 3 689 4 2
{1.125: 9/16, x: 1/6, x : 1/12, 6.89*x : ----, x : 1/30, x*y + y : 1/8}
2000

Computing all monomials up to a maximum degree:

>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)),max_degree=3)

2 3 2 3 ␣
,→2 2
{0: 0, 1: 1/2, x: 1/6, x : 1/12, x : 1/20, y: 1/6, y : 1/12, y : 1/20, x*y: 1/24, x*y␣
,→: 1/60, x *y: 1/60}

5.15.4 For 3-Polytopes/Polyhedra

Single Polynomial:

>>> from sympy.integrals.intpoly import *

>>> cube = [[(0, 0, 0), (0, 0, 5), (0, 5, 0), (0, 5, 5), (5, 0, 0), (5, 0, 5), (5, 5,␣
,→0), (5, 5, 5)], [2, 6, 7, 3], [3, 7, 5, 1], [7, 6, 4, 5], [1, 5, 4, 0], [3, 1, 0,␣

,→2], [0, 4, 6, 2]]

>>> polytope_integrate(cube, x**2 + y**2 + z**2 + x*y + y*z + x*z)

-21875/4
>>> octahedron = [[(S(-1) / sqrt(2), 0, 0), (0, S(1) / sqrt(2), 0), (0, 0, S(-1) /␣
,→sqrt(2)), (0, 0, S(1) / sqrt(2)), (0, S(-1) / sqrt(2), 0), (S(1) / sqrt(2), 0, 0)],␣

,→[3, 4, 5], [3, 5, 1], [3, 1, 0], [3, 0, 4], [4, 0, 2], [4, 2, 5], [2, 0, 1], [5, 2,␣

,→1]]

>>> polytope_integrate(octahedron, x**2 + y**2 + z**2 + x*y + y*z + x*z)

___
\/ 2
-----
20

List of specified polynomials:

>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), [3, x*y + y**2, x**4], max_
,→degree=4)

4 2
{3: 3/2, x : 1/30, x*y + y : 1/8}
>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)), [1.125, x, x**2, 6.89*x**3,␣
,→x*y + y**2, x**4], max_degree=4)

2 3 689 4 2
{1.125: 9/16, x: 1/6, x : 1/12, 6.89*x : ----, x : 1/30, x*y + y : 1/8}
2000

726 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Computing all monomials up to a maximum degree:

>>> polytope_integrate(Polygon((0, 0), (0, 1), (1, 0)),max_degree=3)

2 3 2 3 ␣
,→2 2
{0: 0, 1: 1/2, x: 1/6, x : 1/12, x : 1/20, y: 1/6, y : 1/12, y : 1/20, x*y: 1/24, x*y␣
,→: 1/60, x *y: 1/60}

5.15.5 API reference

sympy.integrals.intpoly.polytope_integrate(poly, expr=None, **kwargs)

Integrates polynomials over 2/3-Polytopes.
This function accepts the polytope in poly and the function in expr (uni/bi/trivariate poly-
nomials are implemented) and returns the exact integral of expr over poly.
Parameters poly : The input Polygon.
expr : The input polynomial.
clockwise : Binary value to sort input points of 2-Polytope clock-
wise.(Optional)
max_degree : The maximum degree of any monomial of the input polyno-
mial.(Optional)

Examples

>>> from sympy.abc import x, y

>>> from sympy.geometry.polygon import Polygon
>>> from sympy.geometry.point import Point
>>> from sympy.integrals.intpoly import polytope_integrate
>>> polygon = Polygon(Point(0,0), Point(0,1), Point(1,1), Point(1,0))
>>> polys = [1, x, y, x*y, x**2*y, x*y**2]
>>> expr = x*y
>>> polytope_integrate(polygon, expr)
1/4
>>> polytope_integrate(polygon, polys, max_degree=3)
{1: 1, x: 1/2, y: 1/2, x*y: 1/4, x*y**2: 1/6, x**2*y: 1/6}

5.16 Lie Algebra Module

class sympy.liealgebras.root_system.RootSystem
Represent the root system of a simple Lie algebra
Every simple Lie algebra has a unique root system. To find the root system, we first con-
sider the Cartan subalgebra of g, which is the maximal abelian subalgebra, and consider
the adjoint action of g on this subalgebra. There is a root system associated with this
action. Now, a root system over a vector space V is a set of finite vectors Φ (called roots),
which satisfy:
1. The roots span V
2. The only scalar multiples of x in Φ are x and -x

5.16. Lie Algebra Module 727

SymPy Documentation, Release 1.3

3. For every x in Φ, the set Φ is closed under reflection through the hyperplane perpen-
dicular to x.
4. If x and y are roots in Φ, then the projection of y onto the line through x is a half-
integral multiple of x.
Now, there is a subset of Φ, which we will call ∆, such that: 1. ∆ is a basis of V 2. Each
root x in Φ can be written x = Σ k_y y for y in ∆
The elements of ∆ are called the simple roots. Therefore, we see that the simple roots
span the root space of a given simple Lie algebra.
References: https://en.wikipedia.org/wiki/Root_system Lie Algebras and Repre-
sentation Theory - Humphreys
add_as_roots(root1, root2)
Add two roots together if and only if their sum is also a root
It takes as input two vectors which should be roots. It then computes their sum and
checks if it is in the list of all possible roots. If it is, it returns the sum. Otherwise it
returns a string saying that the sum is not a root.

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> c.add_as_roots([1, 0, -1, 0], [0, 0, 1, -1])
[1, 0, 0, -1]
>>> c.add_as_roots([1, -1, 0, 0], [0, 0, -1, 1])
'The sum of these two roots is not a root'

add_simple_roots(root1, root2)
Add two simple roots together
The function takes as input two integers, root1 and root2. It then uses these integers
as keys in the dictionary of simple roots, and gets the corresponding simple roots,
and then adds them together.

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> newroot = c.add_simple_roots(1, 2)
>>> newroot
[1, 0, -1, 0]

all_roots()
Generate all the roots of a given root system
The result is a dictionary where the keys are integer numbers. It generates the roots
by getting the dictionary of all positive roots from the bases classes, and then taking
each root, and multiplying it by -1 and adding it to the dictionary. In this way all the
negative roots are generated.
cartan_matrix()
Cartan matrix of Lie algebra associated with this root system

728 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0],
[-1, 2, -1],
[ 0, -1, 2]])

dynkin_diagram()
Dynkin diagram of the Lie algebra associated with this root system

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> print(c.dynkin_diagram())
0---0---0
1 2 3

root_space()
Return the span of the simple roots
The root space is the vector space spanned by the simple roots, i.e. it is a vector
space with a distinguished basis, the simple roots. This method returns a string that
represents the root space as the span of the simple roots, alpha[1],…., alpha[n].

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> c.root_space()
'alpha[1] + alpha[2] + alpha[3]'

simple_roots()
Generate the simple roots of the Lie algebra
The rank of the Lie algebra determines the number of simple roots that it has. This
method obtains the rank of the Lie algebra, and then uses the simple_root method
from the Lie algebra classes to generate all the simple roots.

Examples

>>> from sympy.liealgebras.root_system import RootSystem

>>> c = RootSystem(”A3”)
>>> roots = c.simple_roots()
>>> roots
{1: [1, -1, 0, 0], 2: [0, 1, -1, 0], 3: [0, 0, 1, -1]}

class sympy.liealgebras.type_a.TypeA
This class contains the information about the A series of simple Lie algebras. ====

5.16. Lie Algebra Module 729

SymPy Documentation, Release 1.3

basic_root(i, j)
This is a method just to generate roots with a 1 iin the ith position and a -1 in the jth
position.
basis()
Returns the number of independent generators of A_n
cartan_matrix()
Returns the Cartan matrix for A_n. The Cartan matrix matrix for a Lie algebra is
generated by assigning an ordering to the simple roots, (alpha[1], …., alpha[l]). Then
the ijth entry of the Cartan matrix is (<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('A4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, 0],
[ 0, -1, 2, -1],
[ 0, 0, -1, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A4”)
>>> c.dimension()
5

highest_root()
Returns the highest weight root for A_n
lie_algebra()
Returns the Lie algebra associated with A_n
positive_roots()
This method generates all the positive roots of A_n. This is half of all of the roots of
A_n; by multiplying all the positive roots by -1 we get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots for A_n

730 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

simple_root(i)
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.
In A_n the ith simple root is the root which has a 1 in the ith position, a -1 in the
(i+1)th position, and zeroes elsewhere.
This method returns the ith simple root for the A series.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A4”)
>>> c.simple_root(1)
[1, -1, 0, 0, 0]

class sympy.liealgebras.type_b.TypeB

basic_root(i, j)
This is a method just to generate roots with a 1 iin the ith position and a -1 in the jth
position.
basis()
Returns the number of independent generators of B_n
cartan_matrix()
Returns the Cartan matrix for B_n. The Cartan matrix matrix for a Lie algebra is
generated by assigning an ordering to the simple roots, (alpha[1], …., alpha[l]). Then
the ijth entry of the Cartan matrix is (<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('B4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, 0],
[ 0, -1, 2, -2],
[ 0, 0, -1, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”B3”)
(continues on next page)

5.16. Lie Algebra Module 731

SymPy Documentation, Release 1.3

(continued from previous page)

>>> c.dimension()
3

lie_algebra()
Returns the Lie algebra associated with B_n
positive_roots()
This method generates all the positive roots of A_n. This is half of all of the roots of
B_n; by multiplying all the positive roots by -1 we get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots for B_n”
simple_root(i)
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.
In B_n the first n-1 simple roots are the same as the roots in A_(n-1) (a 1 in the ith
position, a -1 in the (i+1)th position, and zeroes elsewhere). The n-th simple root is
the root with a 1 in the nth position and zeroes elsewhere.
This method returns the ith simple root for the B series.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”B3”)
>>> c.simple_root(2)
[0, 1, -1]

class sympy.liealgebras.type_c.TypeC

basic_root(i, j)
Generate roots with 1 in ith position and a -1 in jth position
basis()
Returns the number of independent generators of C_n
cartan_matrix()
The Cartan matrix for C_n

732 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The Cartan matrix matrix for a Lie algebra is generated by assigning an ordering to
the simple roots, (alpha[1], …., alpha[l]). Then the ijth entry of the Cartan matrix is
(<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('C4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, 0],
[ 0, -1, 2, -1],
[ 0, 0, -2, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”C3”)
>>> c.dimension()
3

lie_algebra()
Returns the Lie algebra associated with C_n”
positive_roots()
Generates all the positive roots of A_n
This is half of all of the roots of C_n; by multiplying all the positive roots by -1 we
get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots for C_n”
simple_root(i)
The ith simple root for the C series
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.

5.16. Lie Algebra Module 733

SymPy Documentation, Release 1.3

In C_n, the first n-1 simple roots are the same as the roots in A_(n-1) (a 1 in the ith
position, a -1 in the (i+1)th position, and zeroes elsewhere). The nth simple root is
the root in which there is a 2 in the nth position and zeroes elsewhere.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”C3”)
>>> c.simple_root(2)
[0, 1, -1]

class sympy.liealgebras.type_d.TypeD

basic_root(i, j)
This is a method just to generate roots with a 1 iin the ith position and a -1 in the jth
position.
basis()
Returns the number of independent generators of D_n
cartan_matrix()
Returns the Cartan matrix for D_n. The Cartan matrix matrix for a Lie algebra is
generated by assigning an ordering to the simple roots, (alpha[1], …., alpha[l]). Then
the ijth entry of the Cartan matrix is (<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('D4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, -1],
[ 0, -1, 2, 0],
[ 0, -1, 0, 2]])

dimension()
Dmension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”D4”)
>>> c.dimension()
4

lie_algebra()
Returns the Lie algebra associated with D_n”
positive_roots()
This method generates all the positive roots of A_n. This is half of all of the roots of
D_n by multiplying all the positive roots by -1 we get the negative roots.

734 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots for D_n”
simple_root(i)
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.
In D_n, the first n-1 simple roots are the same as the roots in A_(n-1) (a 1 in the ith
position, a -1 in the (i+1)th position, and zeroes elsewhere). The nth simple root is
the root in which there 1s in the nth and (n-1)th positions, and zeroes elsewhere.
This method returns the ith simple root for the D series.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”D4”)
>>> c.simple_root(2)
[0, 1, -1, 0]

class sympy.liealgebras.type_e.TypeE

basic_root(i, j)
This is a method just to generate roots with a -1 in the ith position and a 1 in the jth
position.
basis()
Returns the number of independent generators of E_n
cartan_matrix()
Returns the Cartan matrix for G_2 The Cartan matrix matrix for a Lie algebra is
generated by assigning an ordering to the simple roots, (alpha[1], …., alpha[l]). Then
the ijth entry of the Cartan matrix is (<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('A4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, 0],
(continues on next page)

5.16. Lie Algebra Module 735

SymPy Documentation, Release 1.3

(continued from previous page)

[ 0, -1, 2, -1],
[ 0, 0, -1, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”E6”)
>>> c.dimension()
8

positive_roots()
This method generates all the positive roots of A_n. This is half of all of the roots of
E_n; by multiplying all the positive roots by -1 we get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots of E_n
simple_root(i)
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.
This method returns the ith simple root for E_n.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”E6”)
>>> c.simple_root(2)
[1, 1, 0, 0, 0, 0, 0, 0]

class sympy.liealgebras.type_f.TypeF

basic_root(i, j)
Generate roots with 1 in ith position and -1 in jth position
basis()
Returns the number of independent generators of F_4

736 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

cartan_matrix()
The Cartan matrix for F_4
The Cartan matrix matrix for a Lie algebra is generated by assigning an ordering to
the simple roots, (alpha[1], …., alpha[l]). Then the ijth entry of the Cartan matrix is
(<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType('A4')
>>> c.cartan_matrix()
Matrix([
[ 2, -1, 0, 0],
[-1, 2, -1, 0],
[ 0, -1, 2, -1],
[ 0, 0, -1, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”F4”)
>>> c.dimension()
4

positive_roots()
Generate all the positive roots of A_n
This is half of all of the roots of F_4; by multiplying all the positive roots by -1 we
get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

roots()
Returns the total number of roots for F_4
simple_root(i)
The ith simple root of F_4
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.

5.16. Lie Algebra Module 737

SymPy Documentation, Release 1.3

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”F4”)
>>> c.simple_root(3)
[0, 0, 0, 1]

class sympy.liealgebras.type_g.TypeG

basis()
Returns the number of independent generators of G_2
cartan_matrix()
The Cartan matrix for G_2
The Cartan matrix matrix for a Lie algebra is generated by assigning an ordering to
the simple roots, (alpha[1], …., alpha[l]). Then the ijth entry of the Cartan matrix is
(<alpha[i],alpha[j]>).

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”G2”)
>>> c.cartan_matrix()
Matrix([
[ 2, -1],
[-3, 2]])

dimension()
Dimension of the vector space V underlying the Lie algebra

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”G2”)
>>> c.dimension()
3

positive_roots()
Generate all the positive roots of A_n
This is half of all of the roots of A_n; by multiplying all the positive roots by -1 we
get the negative roots.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”A3”)
>>> c.positive_roots()
{1: [1, -1, 0, 0], 2: [1, 0, -1, 0], 3: [1, 0, 0, -1], 4: [0, 1, -1, 0],
5: [0, 1, 0, -1], 6: [0, 0, 1, -1]}

738 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

roots()
Returns the total number of roots of G_2”
simple_root(i)
The ith simple root of G_2
Every lie algebra has a unique root system. Given a root system Q, there is a subset
of the roots such that an element of Q is called a simple root if it cannot be written
as the sum of two elements in Q. If we let D denote the set of simple roots, then it is
clear that every element of Q can be written as a linear combination of elements of
D with all coefficients non-negative.

Examples

>>> from sympy.liealgebras.cartan_type import CartanType

>>> c = CartanType(”G2”)
>>> c.simple_root(1)
[0, 1, -1]

class sympy.liealgebras.weyl_group.WeylGroup
For each semisimple Lie group, we have a Weyl group. It is a subgroup of the isometry
group of the root system. Specifically, it’s the subgroup that is generated by reflections
through the hyperplanes orthogonal to the roots. Therefore, Weyl groups are reflection
groups, and so a Weyl group is a finite Coxeter group.
coxeter_diagram()
This method returns the Coxeter diagram corresponding to a Weyl group. The Cox-
eter diagram can be obtained from a Lie algebra’s Dynkin diagram by deleting all
arrows; the Coxeter diagram is the undirected graph. The vertices of the Coxeter
diagram represent the generating reflections of the Weyl group, , s_i. An edge is
drawn between s_i and s_j if the order m(i, j) of s_i*s_j is greater than two. If there
is one edge, the order m(i, j) is 3. If there are two edges, the order m(i, j) is 4, and
if there are three edges, the order m(i, j) is 6.

Examples

>>> from sympy.liealgebras.weyl_group import WeylGroup

>>> c = WeylGroup(”B3”)
>>> print(c.coxeter_diagram())
0---0===0
1 2 3

delete_doubles(reflections)
This is a helper method for determining the order of an element in the Weyl group of
G2. It takes a Weyl element and if repeated simple reflections in it, it deletes them.
element_order(weylelt)
This method returns the order of a given Weyl group element, which should be spec-
ified by the user in the form of products of the generating reflections, i.e. of the form
r1*r2 etc.
For types A-F, this method current works by taking the matrix form of the specified
element, and then finding what power of the matrix is the identity. It then returns
this power.

5.16. Lie Algebra Module 739

SymPy Documentation, Release 1.3

Examples

>>> from sympy.liealgebras.weyl_group import WeylGroup

>>> b = WeylGroup(”B4”)
>>> b.element_order('r1*r4*r2')
4

generators()
This method creates the generating reflections of the Weyl group for a given Lie
algebra. For a Lie algebra of rank n, there are n different generating reflections.
This function returns them as a list.

Examples

>>> from sympy.liealgebras.weyl_group import WeylGroup

>>> c = WeylGroup(”F4”)
>>> c.generators()
['r1', 'r2', 'r3', 'r4']

group_name()
This method returns some general information about the Weyl group for a given Lie
algebra. It returns the name of the group and the elements it acts on, if relevant.
group_order()
This method returns the order of the Weyl group. For types A, B, C, D, and E the
order depends on the rank of the Lie algebra. For types F and G, the order is fixed.

Examples

>>> from sympy.liealgebras.weyl_group import WeylGroup

>>> c = WeylGroup(”D4”)
>>> c.group_order()
192.0

matrix_form(weylelt)
This method takes input from the user in the form of products of the generating
reflections, and returns the matrix corresponding to the element of the Weyl group.
Since each element of the Weyl group is a reflection of some type, there is a corre-
sponding matrix representation. This method uses the standard representation for
all the generating reflections.

Examples

>>> from sympy.liealgebras.weyl_group import WeylGroup

>>> f = WeylGroup(”F4”)
>>> f.matrix_form('r2*r3')
Matrix([
[1, 0, 0, 0],
[0, 1, 0, 0],
[0, 0, 0, -1],
[0, 0, 1, 0]])

740 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.liealgebras.cartan_type.CartanType_generator
Constructor for actually creating things
class sympy.liealgebras.cartan_type.Standard_Cartan
Concrete base class for Cartan types such as A4, etc
rank()
Returns the rank of the Lie algebra
series()
Returns the type of the Lie algebra
sympy.liealgebras.dynkin_diagram.DynkinDiagram(t)
Display the Dynkin diagram of a given Lie algebra
Works by generating the CartanType for the input, t, and then returning the Dynkin
diagram method from the individual classes.

Examples

>>> from sympy.liealgebras.dynkin_diagram import DynkinDiagram

>>> print(DynkinDiagram(”A3”))
0---0---0
1 2 3

>>> print(DynkinDiagram(”B4”))
0---0---0=>=0
1 2 3 4

sympy.liealgebras.cartan_matrix.CartanMatrix(ct)
Access the Cartan matrix of a specific Lie algebra

Examples

>>> from sympy.liealgebras.cartan_matrix import CartanMatrix

>>> CartanMatrix(”A2”)
Matrix([
[ 2, -1],
[-1, 2]])

>>> CartanMatrix(['C', 3])

Matrix([
[ 2, -1, 0],
[-1, 2, -1],
[ 0, -2, 2]])

This method works by returning the Cartan matrix which corresponds to Cartan type t.

5.16. Lie Algebra Module 741

SymPy Documentation, Release 1.3

5.17 Logic Module

5.17.1 Introduction

The logic module for SymPy allows to form and manipulate logic expressions using symbolic
and Boolean values.

5.17.2 Forming logical expressions

You can build Boolean expressions with the standard python operators & (And), | (Or), ~ (Not):

>>> from sympy import *

>>> x, y = symbols('x,y')
>>> y | (x & y)
y | (x & y)
>>> x | y
x | y
>>> ~x
~x

You can also form implications with >> and <<:

>>> x >> y
Implies(x, y)
>>> x << y
Implies(y, x)

Like most types in SymPy, Boolean expressions inherit from Basic:

>>> (y & x).subs({x: True, y: True})

True
>>> (x | y).atoms()
{x, y}

The logic module also includes the following functions to derive boolean expressions from
their truth tables-
sympy.logic.boolalg.SOPform(variables, minterms, dontcares=None)
The SOPform function uses simplified_pairs and a redundant group- eliminating algo-
rithm to convert the list of all input combos that generate ‘1’ (the minterms) into the
smallest Sum of Products form.
The variables must be given as the first argument.
Return a logical Or function (i.e., the “sum of products” or “SOP” form) that gives the
desired outcome. If there are inputs that can be ignored, pass them as a list, too.
The result will be one of the (perhaps many) functions that satisfy the conditions.

References

[R428]

742 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.logic import SOPform

>>> from sympy import symbols
>>> w, x, y, z = symbols('w x y z')
>>> minterms = [[0, 0, 0, 1], [0, 0, 1, 1],
... [0, 1, 1, 1], [1, 0, 1, 1], [1, 1, 1, 1]]
>>> dontcares = [[0, 0, 0, 0], [0, 0, 1, 0], [0, 1, 0, 1]]
>>> SOPform([w, x, y, z], minterms, dontcares)
(y & z) | (z & ~w)

sympy.logic.boolalg.POSform(variables, minterms, dontcares=None)

The POSform function uses simplified_pairs and a redundant-group eliminating algo-
rithm to convert the list of all input combinations that generate ‘1’ (the minterms) into
the smallest Product of Sums form.
The variables must be given as the first argument.
Return a logical And function (i.e., the “product of sums” or “POS” form) that gives the
desired outcome. If there are inputs that can be ignored, pass them as a list, too.
The result will be one of the (perhaps many) functions that satisfy the conditions.

References

[R429]

Examples

>>> from sympy.logic import POSform

>>> from sympy import symbols
>>> w, x, y, z = symbols('w x y z')
>>> minterms = [[0, 0, 0, 1], [0, 0, 1, 1], [0, 1, 1, 1],
... [1, 0, 1, 1], [1, 1, 1, 1]]
>>> dontcares = [[0, 0, 0, 0], [0, 0, 1, 0], [0, 1, 0, 1]]
>>> POSform([w, x, y, z], minterms, dontcares)
z & (y | ~w)

5.17.3 Boolean functions

class sympy.logic.boolalg.BooleanTrue
SymPy version of True, a singleton that can be accessed via S.true.
This is the SymPy version of True, for use in the logic module. The primary advantage
of using true instead of True is that shorthand boolean operations like ~ and >> will
work as expected on this class, whereas with True they act bitwise on 1. Functions in
the logic module will return this class when they evaluate to true.
See also:
sympy.logic.boolalg.BooleanFalse (page 745)

5.17. Logic Module 743

SymPy Documentation, Release 1.3

Notes

There is liable to be some confusion as to when True should be used and when S.true
should be used in various contexts throughout SymPy. An important thing to remember
is that sympify(True) returns S.true. This means that for the most part, you can just
use True and it will automatically be converted to S.true when necessary, similar to how
you can generally use 1 instead of S.One.
The rule of thumb is:
“If the boolean in question can be replaced by an arbitrary symbolic Boolean, like Or(x,
y) or x > 1, use S.true. Otherwise, use True”
In other words, use S.true only on those contexts where the boolean is being used as a
symbolic representation of truth. For example, if the object ends up in the .args of any
expression, then it must necessarily be S.true instead of True, as elements of .args
must be Basic. On the other hand, == is not a symbolic operation in SymPy, since it
always returns True or False, and does so in terms of structural equality rather than
mathematical, so it should return True. The assumptions system should use True and
False. Aside from not satisfying the above rule of thumb, the assumptions system uses
a three-valued logic (True, False, None), whereas S.true and S.false represent a two-
valued logic. When in doubt, use True.
“S.true == True is True.”
While “S.true is True” is False, “S.true == True” is True, so if there is any doubt
over whether a function or expression will return S.true or True, just use == instead of
is to do the comparison, and it will work in either case. Finally, for boolean flags, it’s
better to just use if x instead of if x is True. To quote PEP 8:
Don’t compare boolean values to True or False using ==.
• Yes: if greeting:
• No: if greeting == True:
• Worse: if greeting is True:

Examples

>>> from sympy import sympify, true, false, Or

>>> sympify(True)
True
>>> _ is True, _ is true
(False, True)

>>> Or(true, false)

True
>>> _ is true
True

Python operators give a boolean result for true but a bitwise result for True

>>> ~true, ~True

(False, -2)
>>> true >> true, True >> True
(True, 0)

744 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Python operators give a boolean result for true but a bitwise result for True

>>> ~true, ~True

(False, -2)
>>> true >> true, True >> True
(True, 0)

class sympy.logic.boolalg.BooleanFalse
SymPy version of False, a singleton that can be accessed via S.false.
This is the SymPy version of False, for use in the logic module. The primary advantage
of using false instead of False is that shorthand boolean operations like ~ and >> will
work as expected on this class, whereas with False they act bitwise on 0. Functions in
the logic module will return this class when they evaluate to false.
See also:
sympy.logic.boolalg.BooleanTrue (page 743)

Notes

See note in :py:class‘sympy.logic.boolalg.BooleanTrue‘

Examples

>>> from sympy import sympify, true, false, Or

>>> sympify(False)
False
>>> _ is False, _ is false
(False, True)

>>> Or(true, false)

True
>>> _ is true
True

Python operators give a boolean result for false but a bitwise result for False

>>> ~false, ~False

(True, -1)
>>> false >> false, False >> False
(True, 0)

class sympy.logic.boolalg.And
Logical AND function.
It evaluates its arguments in order, giving False immediately if any of them are False,
and True if they are all True.

Notes

The & operator is provided as a convenience, but note that its use here is different from
its normal use in Python, which is bitwise and. Hence, And(a, b) and a & b will return
different things if a and b are integers.

5.17. Logic Module 745

SymPy Documentation, Release 1.3

>>> And(x, y).subs(x, 1)

y

Examples

>>> from sympy.core import symbols

>>> from sympy.abc import x, y
>>> from sympy.logic.boolalg import And
>>> x & y
x & y

class sympy.logic.boolalg.Or
Logical OR function
It evaluates its arguments in order, giving True immediately if any of them are True, and
False if they are all False.

Notes

The | operator is provided as a convenience, but note that its use here is different from
its normal use in Python, which is bitwise or. Hence, Or(a, b) and a | b will return
different things if a and b are integers.

>>> Or(x, y).subs(x, 0)

y

Examples

>>> from sympy.core import symbols

>>> from sympy.abc import x, y
>>> from sympy.logic.boolalg import Or
>>> x | y
x | y

class sympy.logic.boolalg.Not
Logical Not function (negation)
Returns True if the statement is False Returns False if the statement is True

Notes

• The ~ operator is provided as a convenience, but note that its use here is different
from its normal use in Python, which is bitwise not. In particular, ~a and Not(a) will
be different if a is an integer. Furthermore, since bools in Python subclass from int,
~True is the same as ~1 which is -2, which has a boolean value of True. To avoid
this issue, use the SymPy boolean types true and false.

746 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import true

>>> ~True
-2
>>> ~true
False

Examples

>>> from sympy.logic.boolalg import Not, And, Or

>>> from sympy.abc import x, A, B
>>> Not(True)
False
>>> Not(False)
True
>>> Not(And(True, False))
True
>>> Not(Or(True, False))
False
>>> Not(And(And(True, x), Or(x, False)))
~x
>>> ~x
~x
>>> Not(And(Or(A, B), Or(~A, ~B)))
~((A | B) & (~A | ~B))

class sympy.logic.boolalg.Xor
Logical XOR (exclusive OR) function.
Returns True if an odd number of the arguments are True and the rest are False.
Returns False if an even number of the arguments are True and the rest are False.

Notes

The ^ operator is provided as a convenience, but note that its use here is different from
its normal use in Python, which is bitwise xor. In particular, a ^ b and Xor(a, b) will
be different if a and b are integers.
>>> Xor(x, y).subs(y, 0)
x

Examples

>>> from sympy.logic.boolalg import Xor

>>> from sympy import symbols
>>> x, y = symbols('x y')
>>> Xor(True, False)
True
>>> Xor(True, True)
False
>>> Xor(True, False, True, True, False)
True
(continues on next page)

5.17. Logic Module 747

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Xor(True, False, True, False)
False
>>> x ^ y
Xor(x, y)

class sympy.logic.boolalg.Nand
Logical NAND function.
It evaluates its arguments in order, giving True immediately if any of them are False, and
False if they are all True.
Returns True if any of the arguments are False Returns False if all arguments are True

Examples

>>> from sympy.logic.boolalg import Nand

>>> from sympy import symbols
>>> x, y = symbols('x y')
>>> Nand(False, True)
True
>>> Nand(True, True)
False
>>> Nand(x, y)
~(x & y)

class sympy.logic.boolalg.Nor
Logical NOR function.
It evaluates its arguments in order, giving False immediately if any of them are True, and
True if they are all False.
Returns False if any argument is True Returns True if all arguments are False

Examples

>>> from sympy.logic.boolalg import Nor

>>> from sympy import symbols
>>> x, y = symbols('x y')

>>> Nor(True, False)

False
>>> Nor(True, True)
False
>>> Nor(False, True)
False
>>> Nor(False, False)
True
>>> Nor(x, y)
~(x | y)

class sympy.logic.boolalg.Implies
Logical implication.
A implies B is equivalent to !A v B

748 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Accepts two Boolean arguments; A and B. Returns False if A is True and B is False Returns
True otherwise.

Notes

The >> and << operators are provided as a convenience, but note that their use here is
different from their normal use in Python, which is bit shifts. Hence, Implies(a, b) and
a >> b will return different things if a and b are integers. In particular, since Python
considers True and False to be integers, True >> True will be the same as 1 >> 1, i.e.,
0, which has a truth value of False. To avoid this issue, use the SymPy objects true and
false.

>>> from sympy import true, false

>>> True >> False
1
>>> true >> false
False

Examples

>>> from sympy.logic.boolalg import Implies

>>> from sympy import symbols
>>> x, y = symbols('x y')

>>> Implies(True, False)

False
>>> Implies(False, False)
True
>>> Implies(True, True)
True
>>> Implies(False, True)
True
>>> x >> y
Implies(x, y)
>>> y << x
Implies(x, y)

class sympy.logic.boolalg.Equivalent
Equivalence relation.
Equivalent(A, B) is True iff A and B are both True or both False
Returns True if all of the arguments are logically equivalent. Returns False otherwise.

Examples

>>> from sympy.logic.boolalg import Equivalent, And

>>> from sympy.abc import x, y
>>> Equivalent(False, False, False)
True
>>> Equivalent(True, False, False)
False
(continues on next page)

5.17. Logic Module 749

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Equivalent(x, And(x, True))
True

class sympy.logic.boolalg.ITE
If then else clause.
ITE(A, B, C) evaluates and returns the result of B if A is true else it returns the result of
C. All args must be Booleans.

Examples

>>> from sympy.logic.boolalg import ITE, And, Xor, Or

>>> from sympy.abc import x, y, z
>>> ITE(True, False, True)
False
>>> ITE(Or(True, False), And(True, True), Xor(True, True))
True
>>> ITE(x, y, z)
ITE(x, y, z)
>>> ITE(True, x, y)
x
>>> ITE(False, x, y)
y
>>> ITE(x, y, y)
y

Trying to use non-Boolean args will generate a TypeError:

>>> ITE(True, [], ())

Traceback (most recent call last):
...
TypeError: expecting bool, Boolean or ITE, not `[]`

The following functions can be used to handle Conjunctive and Disjunctive Normal forms-
sympy.logic.boolalg.to_cnf(expr, simplify=False)
Convert a propositional logical sentence s to conjunctive normal form. That is, of the
form ((A | ~B | …) & (B | C | …) & …) If simplify is True, the expr is evaluated to its
simplest CNF form.

Examples

>>> from sympy.logic.boolalg import to_cnf

>>> from sympy.abc import A, B, D
>>> to_cnf(~(A | B) | D)
(D | ~A) & (D | ~B)
>>> to_cnf((A | B) & (A | ~A), True)
A | B

sympy.logic.boolalg.to_dnf(expr, simplify=False)
Convert a propositional logical sentence s to disjunctive normal form. That is, of the
form ((A & ~B & …) | (B & C & …) | …) If simplify is True, the expr is evaluated to its
simplest DNF form.

750 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.logic.boolalg import to_dnf

>>> from sympy.abc import A, B, C
>>> to_dnf(B & (A | C))
(A & B) | (B & C)
>>> to_dnf((A & B) | (A & ~B) | (B & C) | (~B & C), True)
A | C

sympy.logic.boolalg.is_cnf(expr)
Test whether or not an expression is in conjunctive normal form.

Examples

>>> from sympy.logic.boolalg import is_cnf

>>> from sympy.abc import A, B, C
>>> is_cnf(A | B | C)
True
>>> is_cnf(A & B & C)
True
>>> is_cnf((A & B) | C)
False

sympy.logic.boolalg.is_dnf(expr)
Test whether or not an expression is in disjunctive normal form.

Examples

>>> from sympy.logic.boolalg import is_dnf

>>> from sympy.abc import A, B, C
>>> is_dnf(A | B | C)
True
>>> is_dnf(A & B & C)
True
>>> is_dnf((A & B) | C)
True
>>> is_dnf(A & (B | C))
False

5.17.4 Simplification and equivalence-testing

sympy.logic.boolalg.simplify_logic(expr, form=None, deep=True)

This function simplifies a boolean function to its simplified version in SOP or POS form.
The return type is an Or or And object in SymPy.
Parameters expr : string or boolean expression
form : string (‘cnf’ or ‘dnf’) or None (default).
If ‘cnf’ or ‘dnf’, the simplest expression in the corresponding normal
form is returned; if None, the answer is returned according to the
form with fewest args (in CNF by default).

5.17. Logic Module 751

SymPy Documentation, Release 1.3

deep : boolean (default True)

indicates whether to recursively simplify any non-boolean functions
contained within the input.

Examples

>>> from sympy.logic import simplify_logic

>>> from sympy.abc import x, y, z
>>> from sympy import S
>>> b = (~x & ~y & ~z) | ( ~x & ~y & z)
>>> simplify_logic(b)
~x & ~y

>>> S(b)
(z & ~x & ~y) | (~x & ~y & ~z)
>>> simplify_logic(_)
~x & ~y

SymPy’s simplify() function can also be used to simplify logic expressions to their simplest
forms.
sympy.logic.boolalg.bool_map(bool1, bool2)
Return the simplified version of bool1, and the mapping of variables that makes the two
expressions bool1 and bool2 represent the same logical behaviour for some correspon-
dence between the variables of each. If more than one mappings of this sort exist, one
of them is returned. For example, And(x, y) is logically equivalent to And(a, b) for the
mapping {x: a, y:b} or {x: b, y:a}. If no such mapping exists, return False.

Examples

>>> from sympy import SOPform, bool_map, Or, And, Not, Xor
>>> from sympy.abc import w, x, y, z, a, b, c, d
>>> function1 = SOPform([x, z, y],[[1, 0, 1], [0, 0, 1]])
>>> function2 = SOPform([a, b, c],[[1, 0, 1], [1, 0, 0]])
>>> bool_map(function1, function2)
(y & ~z, {y: a, z: b})

The results are not necessarily unique, but they are canonical. Here, (w, z) could be
(a, d) or (d, a):

>>> eq = Or(And(Not(y), w), And(Not(y), z), And(x, y))

>>> eq2 = Or(And(Not(c), a), And(Not(c), d), And(b, c))
>>> bool_map(eq, eq2)
((x & y) | (w & ~y) | (z & ~y), {w: a, x: b, y: c, z: d})
>>> eq = And(Xor(a, b), c, And(c,d))
>>> bool_map(eq, eq.subs(c, x))
(c & d & (a | b) & (~a | ~b), {a: a, b: b, c: d, d: x})

5.17.5 Inference

This module implements some inference routines in propositional logic.

752 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The function satisfiable will test that a given Boolean expression is satisfiable, that is, you can
assign values to the variables to make the sentence T rue.
For example, the expression x & ~x is not satisfiable, since there are no values for x that
make this sentence True. On the other hand, (x | y) & (x | ~y) & (~x | y) is satisfiable
with both x and y being True.

>>> from sympy.logic.inference import satisfiable

>>> from sympy import Symbol
>>> x = Symbol('x')
>>> y = Symbol('y')
>>> satisfiable(x & ~x)
False
>>> satisfiable((x | y) & (x | ~y) & (~x | y))
{x: True, y: True}

As you see, when a sentence is satisfiable, it returns a model that makes that sentence True.
If it is not satisfiable it will return False.
sympy.logic.inference.satisfiable(expr, algorithm=’dpll2’, all_models=False)
Check satisfiability of a propositional sentence. Returns a model when it succeeds. Re-
turns {true: true} for trivially true expressions.
On setting all_models to True, if given expr is satisfiable then returns a generator of
models. However, if expr is unsatisfiable then returns a generator containing the single
element False.

Examples

>>> from sympy.abc import A, B

>>> from sympy.logic.inference import satisfiable
>>> satisfiable(A & ~B)
{A: True, B: False}
>>> satisfiable(A & ~A)
False
>>> satisfiable(True)
{True: True}
>>> next(satisfiable(A & ~A, all_models=True))
False
>>> models = satisfiable((A >> B) & B, all_models=True)
>>> next(models)
{A: False, B: True}
>>> next(models)
{A: True, B: True}
>>> def use_models(models):
... for model in models:
... if model:
... # Do something with the model.
... print(model)
... else:
... # Given expr is unsatisfiable.
... print(”UNSAT”)
>>> use_models(satisfiable(A >> ~A, all_models=True))
{A: False}
>>> use_models(satisfiable(A ^ A, all_models=True))
UNSAT

5.17. Logic Module 753

SymPy Documentation, Release 1.3

5.18 Matrices

A module that handles matrices.

Includes functions for fast creating matrices like zero, one/eye, random matrix, etc.
Contents:

5.18.1 Matrices (linear algebra)

Creating Matrices

The linear algebra module is designed to be as simple as possible. First, we import and
declare our first Matrix object:
>>> from sympy.interactive.printing import init_printing
>>> init_printing(use_unicode=False, wrap_line=False)
>>> from sympy.matrices import Matrix, eye, zeros, ones, diag, GramSchmidt
>>> M = Matrix([[1,0,0], [0,0,0]]); M
[1 0 0]
[ ]
[0 0 0]
>>> Matrix([M, (0, 0, -1)])
[1 0 0 ]
[ ]
[0 0 0 ]
[ ]
[0 0 -1]
>>> Matrix([[1, 2, 3]])
[1 2 3]
>>> Matrix([1, 2, 3])
[1]
[ ]
[2]
[ ]
[3]

In addition to creating a matrix from a list of appropriately-sized lists and/or matrices, SymPy
also supports more advanced methods of matrix creation including a single list of values and
dimension inputs:
>>> Matrix(2, 3, [1, 2, 3, 4, 5, 6])
[1 2 3]
[ ]
[4 5 6]

More interesting (and useful), is the ability to use a 2-variable function (or lambda) to create
a matrix. Here we create an indicator function which is 1 on the diagonal and then use it to
make the identity matrix:
>>> def f(i,j):
... if i == j:
... return 1
... else:
... return 0
(continues on next page)

754 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

...
>>> Matrix(4, 4, f)
[1 0 0 0]
[ ]
[0 1 0 0]
[ ]
[0 0 1 0]
[ ]
[0 0 0 1]

Finally let’s use lambda to create a 1-line matrix with 1’s in the even permutation entries:

>>> Matrix(3, 4, lambda i,j: 1 - (i+j) % 2)

[1 0 1 0]
[ ]
[0 1 0 1]
[ ]
[1 0 1 0]

There are also a couple of special constructors for quick matrix construction: eye is the
identity matrix, zeros and ones for matrices of all zeros and ones, respectively, and diag to
put matrices or elements along the diagonal:

>>> eye(4)
[1 0 0 0]
[ ]
[0 1 0 0]
[ ]
[0 0 1 0]
[ ]
[0 0 0 1]
>>> zeros(2)
[0 0]
[ ]
[0 0]
>>> zeros(2, 5)
[0 0 0 0 0]
[ ]
[0 0 0 0 0]
>>> ones(3)
[1 1 1]
[ ]
[1 1 1]
[ ]
[1 1 1]
>>> ones(1, 3)
[1 1 1]
>>> diag(1, Matrix([[1, 2], [3, 4]]))
[1 0 0]
[ ]
[0 1 2]
[ ]
[0 3 4]

5.18. Matrices 755

SymPy Documentation, Release 1.3

Basic Manipulation

While learning to work with matrices, let’s choose one where the entries are readily identi-
fiable. One useful thing to know is that while matrices are 2-dimensional, the storage is not
and so it is allowable - though one should be careful - to access the entries as if they were a
1-d list.

>>> M = Matrix(2, 3, [1, 2, 3, 4, 5, 6])

>>> M[4]
5

Now, the more standard entry access is a pair of indices which will always return the value
at the corresponding row and column of the matrix:

>>> M[1, 2]
6
>>> M[0, 0]
1
>>> M[1, 1]
5

Since this is Python we’re also able to slice submatrices; slices always give a matrix in return,
even if the dimension is 1 x 1:

>>> M[0:2, 0:2]

[1 2]
[ ]
[4 5]
>>> M[2:2, 2]
[]
>>> M[:, 2]
[3]
[ ]
[6]
>>> M[:1, 2]
[3]

In the second example above notice that the slice 2:2 gives an empty range. Note also (in
keeping with 0-based indexing of Python) the first row/column is 0.
You cannot access rows or columns that are not present unless they are in a slice:

>>> M[:, 10] # the 10-th column (not there)

Traceback (most recent call last):
...
IndexError: Index out of range: a[[0, 10]]
>>> M[:, 10:11] # the 10-th column (if there)
[]
>>> M[:, :10] # all columns up to the 10-th
[1 2 3]
[ ]
[4 5 6]

Slicing an empty matrix works as long as you use a slice for the coordinate that has no size:

>>> Matrix(0, 3, [])[:, 1]

[]

756 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Slicing gives a copy of what is sliced, so modifications of one object do not affect the other:
>>> M2 = M[:, :]
>>> M2[0, 0] = 100
>>> M[0, 0] == 100
False

Notice that changing M2 didn’t change M. Since we can slice, we can also assign entries:
>>> M = Matrix(([1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]))
>>> M
[1 2 3 4 ]
[ ]
[5 6 7 8 ]
[ ]
[9 10 11 12]
[ ]
[13 14 15 16]
>>> M[2,2] = M[0,3] = 0
>>> M
[1 2 3 0 ]
[ ]
[5 6 7 8 ]
[ ]
[9 10 0 12]
[ ]
[13 14 15 16]

as well as assign slices:

>>> M = Matrix(([1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]))
>>> M[2:,2:] = Matrix(2,2,lambda i,j: 0)
>>> M
[1 2 3 4]
[ ]
[5 6 7 8]
[ ]
[9 10 0 0]
[ ]
[13 14 0 0]

All the standard arithmetic operations are supported:

>>> M = Matrix(([1,2,3],[4,5,6],[7,8,9]))
>>> M - M
[0 0 0]
[ ]
[0 0 0]
[ ]
[0 0 0]
>>> M + M
[2 4 6 ]
[ ]
[8 10 12]
[ ]
[14 16 18]
>>> M * M
[30 36 42 ]
(continues on next page)

5.18. Matrices 757

SymPy Documentation, Release 1.3

(continued from previous page)

[ ]
[66 81 96 ]
[ ]
[102 126 150]
>>> M2 = Matrix(3,1,[1,5,0])
>>> M*M2
[11]
[ ]
[29]
[ ]
[47]
>>> M**2
[30 36 42 ]
[ ]
[66 81 96 ]
[ ]
[102 126 150]

As well as some useful vector operations:

>>> M.row_del(0)
>>> M
[4 5 6]
[ ]
[7 8 9]
>>> M.col_del(1)
>>> M
[4 6]
[ ]
[7 9]
>>> v1 = Matrix([1,2,3])
>>> v2 = Matrix([4,5,6])
>>> v3 = v1.cross(v2)
>>> v1.dot(v2)
32
>>> v2.dot(v3)
0
>>> v1.dot(v3)
0

Recall that the row_del() and col_del() operations don’t return a value - they simply change
the matrix object. We can also ‘’glue’’ together matrices of the appropriate size:

>>> M1 = eye(3)
>>> M2 = zeros(3, 4)
>>> M1.row_join(M2)
[1 0 0 0 0 0 0]
[ ]
[0 1 0 0 0 0 0]
[ ]
[0 0 1 0 0 0 0]
>>> M3 = zeros(4, 3)
>>> M1.col_join(M3)
[1 0 0]
[ ]
[0 1 0]
(continues on next page)

758 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[ ]
[0 0 1]
[ ]
[0 0 0]
[ ]
[0 0 0]
[ ]
[0 0 0]
[ ]
[0 0 0]

Operations on entries

We are not restricted to having multiplication between two matrices:

>>> M = eye(3)
>>> 2*M
[2 0 0]
[ ]
[0 2 0]
[ ]
[0 0 2]
>>> 3*M
[3 0 0]
[ ]
[0 3 0]
[ ]
[0 0 3]

but we can also apply functions to our matrix entries using applyfunc(). Here we’ll declare
a function that double any input number. Then we apply it to the 3x3 identity matrix:

>>> f = lambda x: 2*x

>>> eye(3).applyfunc(f)
[2 0 0]
[ ]
[0 2 0]
[ ]
[0 0 2]

One more useful matrix-wide entry application function is the substitution function. Let’s
declare a matrix with symbolic entries then substitute a value. Remember we can substitute
anything - even another symbol!:

>>> from sympy import Symbol

>>> x = Symbol('x')
>>> M = eye(3) * x
>>> M
[x 0 0]
[ ]
[0 x 0]
[ ]
[0 0 x]
>>> M.subs(x, 4)
(continues on next page)

5.18. Matrices 759

SymPy Documentation, Release 1.3

(continued from previous page)

[4 0 0]
[ ]
[0 4 0]
[ ]
[0 0 4]
>>> y = Symbol('y')
>>> M.subs(x, y)
[y 0 0]
[ ]
[0 y 0]
[ ]
[0 0 y]

Linear algebra

Now that we have the basics out of the way, let’s see what we can do with the actual matrices.
Of course, one of the first things that comes to mind is the determinant:

>>> M = Matrix(( [1, 2, 3], [3, 6, 2], [2, 0, 1] ))

>>> M.det()
-28
>>> M2 = eye(3)
>>> M2.det()
1
>>> M3 = Matrix(( [1, 0, 0], [1, 0, 0], [1, 0, 0] ))
>>> M3.det()
0

Another common operation is the inverse: In SymPy, this is computed by Gaussian elimination
by default (for dense matrices) but we can specify it be done by LU decomposition as well:

>>> M2.inv()
[1 0 0]
[ ]
[0 1 0]
[ ]
[0 0 1]
>>> M2.inv(method=”LU”)
[1 0 0]
[ ]
[0 1 0]
[ ]
[0 0 1]
>>> M.inv(method=”LU”)
[-3/14 1/14 1/2 ]
[ ]
[-1/28 5/28 -1/4]
[ ]
[ 3/7 -1/7 0 ]
>>> M * M.inv(method=”LU”)
[1 0 0]
[ ]
[0 1 0]
[ ]
[0 0 1]

760 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

We can perform a QR factorization which is handy for solving systems:

>>> A = Matrix([[1,1,1],[1,1,3],[2,3,4]])
>>> Q, R = A.QRdecomposition()
>>> Q
[ ___ ___ ___ ]
[\/ 6 -\/ 3 -\/ 2 ]
[----- ------- -------]
[ 6 3 2 ]
[ ]
[ ___ ___ ___ ]
[\/ 6 -\/ 3 \/ 2 ]
[----- ------- ----- ]
[ 6 3 2 ]
[ ]
[ ___ ___ ]
[\/ 6 \/ 3 ]
[----- ----- 0 ]
[ 3 3 ]
>>> R
[ ___ ]
[ ___ 4*\/ 6 ___]
[\/ 6 ------- 2*\/ 6 ]
[ 3 ]
[ ]
[ ___ ]
[ \/ 3 ]
[ 0 ----- 0 ]
[ 3 ]
[ ]
[ ___ ]
[ 0 0 \/ 2 ]
>>> Q*R
[1 1 1]
[ ]
[1 1 3]
[ ]
[2 3 4]

In addition to the solvers in the solver.py file, we can solve the system Ax=b by passing
the b vector to the matrix A’s LUsolve function. Here we’ll cheat a little choose A and x then
multiply to get b. Then we can solve for x and check that it’s correct:

>>> A = Matrix([ [2, 3, 5], [3, 6, 2], [8, 3, 6] ])

>>> x = Matrix(3,1,[3,7,5])
>>> b = A*x
>>> soln = A.LUsolve(b)
>>> soln
[3]
[ ]
[7]
[ ]
[5]

There’s also a nice Gram-Schmidt orthogonalizer which will take a set of vectors and orthog-
onalize them with respect to another. There is an optional argument which specifies whether
or not the output should also be normalized, it defaults to False. Let’s take some vectors and
orthogonalize them - one normalized and one not:

5.18. Matrices 761

SymPy Documentation, Release 1.3

>>> L = [Matrix([2,3,5]), Matrix([3,6,2]), Matrix([8,3,6])]

>>> out1 = GramSchmidt(L)
>>> out2 = GramSchmidt(L, True)

Let’s take a look at the vectors:

>>> for i in out1:
... print(i)
...
Matrix([[2], [3], [5]])
Matrix([[23/19], [63/19], [-47/19]])
Matrix([[1692/353], [-1551/706], [-423/706]])
>>> for i in out2:
... print(i)
...
Matrix([[sqrt(38)/19], [3*sqrt(38)/38], [5*sqrt(38)/38]])
Matrix([[23*sqrt(6707)/6707], [63*sqrt(6707)/6707], [-47*sqrt(6707)/6707]])
Matrix([[12*sqrt(706)/353], [-11*sqrt(706)/706], [-3*sqrt(706)/706]])

We can spot-check their orthogonality with dot() and their normality with norm():
>>> out1[0].dot(out1[1])
0
>>> out1[0].dot(out1[2])
0
>>> out1[1].dot(out1[2])
0
>>> out2[0].norm()
1
>>> out2[1].norm()
1
>>> out2[2].norm()
1

So there is quite a bit that can be done with the module including eigenvalues, eigenvectors,
nullspace calculation, cofactor expansion tools, and so on. From here one might want to look
over the matrices.py file for all functionality.

MatrixBase Class Reference

class sympy.matrices.matrices.MatrixBase
Base class for matrix objects.

Attributes

cols
rows

D
Return Dirac conjugate (if self.rows == 4).
See also:

conjugate By-element conjugation

762 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

H Hermite conjugation

Examples

>>> from sympy import Matrix, I, eye

>>> m = Matrix((0, 1 + I, 2, 3))
>>> m.D
Matrix([[0, 1 - I, -2, -3]])
>>> m = (eye(4) + I*eye(4))
>>> m[0, 3] = 2
>>> m.D
Matrix([
[1 - I, 0, 0, 0],
[ 0, 1 - I, 0, 0],
[ 0, 0, -1 + I, 0],
[ 2, 0, 0, -1 + I]])

If the matrix does not have 4 rows an AttributeError will be raised because this
property is only defined for matrices with 4 rows.

>>> Matrix(eye(2)).D
Traceback (most recent call last):
...
AttributeError: Matrix has no attribute D.

LDLdecomposition()
Returns the LDL Decomposition (L, D) of matrix A, such that L * D * L.H == A This
method eliminates the use of square root. Further this ensures that all the diagonal
entries of L are 1. A must be a Hermitian positive-definite matrix.
See also:
cholesky (page 767), LUdecomposition (page 764), QRdecomposition (page 766)

Examples

>>> from sympy.matrices import Matrix, eye

>>> A = Matrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
>>> L, D = A.LDLdecomposition()
>>> L
Matrix([
[ 1, 0, 0],
[ 3/5, 1, 0],
[-1/5, 1/3, 1]])
>>> D
Matrix([
[25, 0, 0],
[ 0, 9, 0],
[ 0, 0, 9]])
>>> L * D * L.T * A.inv() == eye(A.rows)
True

The matrix can have complex entries:

5.18. Matrices 763

SymPy Documentation, Release 1.3

>>> from sympy import I

>>> A = Matrix(((9, 3*I), (-3*I, 5)))
>>> L, D = A.LDLdecomposition()
>>> L
Matrix([
[ 1, 0],
[-I/3, 1]])
>>> D
Matrix([
[9, 0],
[0, 4]])
>>> L*D*L.H == A
True

LDLsolve(rhs)
Solves Ax = B using LDL decomposition, for a general square and non-singular ma-
trix.
For a non-square matrix with rows > cols, the least squares solution is returned.
See also:
LDLdecomposition (page 763), lower_triangular_solve (page 773), up-
per_triangular_solve (page 778), gauss_jordan_solve (page 770),
cholesky_solve (page 768), diagonal_solve (page 769), LUsolve (page 766),
QRsolve (page 767), pinv_solve (page 774)

Examples

>>> from sympy.matrices import Matrix, eye

>>> A = eye(2)*2
>>> B = Matrix([[1, 2], [3, 4]])
>>> A.LDLsolve(B) == B/2
True

LUdecomposition(iszerofunc=<function _iszero>, simpfunc=None,

rankcheck=False)
Returns (L, U, perm) where L is a lower triangular matrix with unit diagonal, U is an
upper triangular matrix, and perm is a list of row swap index pairs. If A is the original
matrix, then A = (L*U).permuteBkwd(perm), and the row permutation matrix P such
that P*A = L*U can be computed by P=eye(A.row).permuteFwd(perm).
See documentation for LUCombined for details about the keyword argument
rankcheck, iszerofunc, and simpfunc.
See also:
cholesky (page 767), LDLdecomposition (page 763), QRdecomposition (page 766),
LUdecomposition_Simple (page 765), LUdecompositionFF (page 765), LUsolve
(page 766)

Examples

764 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Matrix

>>> a = Matrix([[4, 3], [6, 3]])
>>> L, U, _ = a.LUdecomposition()
>>> L
Matrix([
[ 1, 0],
[3/2, 1]])
>>> U
Matrix([
[4, 3],
[0, -3/2]])

LUdecompositionFF()
Compute a fraction-free LU decomposition.
Returns 4 matrices P, L, D, U such that PA = L D**-1 U. If the elements of the matrix
belong to some integral domain I, then all elements of L, D and U are guaranteed to
belong to I.
Reference
• W. Zhou & D.J. Jeffrey, “Fraction-free matrix factors: new forms for LU and
QR factors”. Frontiers in Computer Science in China, Vol 2, no. 1, pp. 67-80,
2008.
See also:
LUdecomposition (page 764), LUdecomposition_Simple (page 765), LUsolve
(page 766)
LUdecomposition_Simple(iszerofunc=<function _iszero>, simpfunc=None,
rankcheck=False)
Compute an lu decomposition of m x n matrix A, where P*A = L*U
• L is m x m lower triangular with unit diagonal
• U is m x n upper triangular
• P is an m x m permutation matrix
Returns an m x n matrix lu, and an m element list perm where each element of perm
is a pair of row exchange indices.
The factors L and U are stored in lu as follows: The subdiagonal elements of L are
stored in the subdiagonal elements of lu, that is lu[i, j] = L[i, j] whenever i > j. The
elements on the diagonal of L are all 1, and are not explicitly stored. U is stored
in the upper triangular portion of lu, that is lu[i ,j] = U[i, j] whenever i <= j. The
output matrix can be visualized as:
Matrix([ [u, u, u, u], [l, u, u, u], [l, l, u, u], [l, l, l, u]])
where l represents a subdiagonal entry of the L factor, and u represents an entry
from the upper triangular entry of the U factor.
perm is a list row swap index pairs such that if A is the original matrix, then A =
(L*U).permuteBkwd(perm), and the row permutation matrix P such that P*A = L*U
can be computed by P=eye(A.row).permuteFwd(perm).
The keyword argument rankcheck determines if this function raises a ValueError
when passed a matrix whose rank is strictly less than min(num rows, num cols).
The default behavior is to decompose a rank deficient matrix. Pass rankcheck=True
to raise a ValueError instead. (This mimics the previous behavior of this function).

5.18. Matrices 765

SymPy Documentation, Release 1.3

The keyword arguments iszerofunc and simpfunc are used by the pivot search algo-
rithm. iszerofunc is a callable that returns a boolean indicating if its input is zero, or
None if it cannot make the determination. simpfunc is a callable that simplifies its
input. The default is simpfunc=None, which indicate that the pivot search algorithm
should not attempt to simplify any candidate pivots. If simpfunc fails to simplify its
input, then it must return its input instead of a copy.
When a matrix contains symbolic entries, the pivot search algorithm differs from
the case where every entry can be categorized as zero or nonzero. The algorithm
searches column by column through the submatrix whose top left entry coincides
with the pivot position. If it exists, the pivot is the first entry in the current search
column that iszerofunc guarantees is nonzero. If no such candidate exists, then each
candidate pivot is simplified if simpfunc is not None. The search is repeated, with the
difference that a candidate may be the pivot if iszerofunc() cannot guarantee that
it is nonzero. In the second search the pivot is the first candidate that iszerofunc
can guarantee is nonzero. If no such candidate exists, then the pivot is the first
candidate for which iszerofunc returns None. If no such candidate exists, then the
search is repeated in the next column to the right. The pivot search algorithm differs
from the one in rref (), which relies on _find_reasonable_pivot(). Future versions
of LUdecomposition_simple() may use _find_reasonable_pivot().
See also:
LUdecomposition (page 764), LUdecompositionFF (page 765), LUsolve (page 766)
LUsolve(rhs, iszerofunc=<function _iszero>)
Solve the linear system Ax = rhs for x where A = self.
This is for symbolic matrices, for real or complex ones use mpmath.lu_solve or mp-
math.qr_solve.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
gauss_jordan_solve (page 770), cholesky_solve (page 768), diagonal_solve
(page 769), LDLsolve (page 764), QRsolve (page 767), pinv_solve (page 774),
LUdecomposition (page 764)
QRdecomposition()
Return Q, R where A = Q*R, Q is orthogonal and R is upper triangular.
See also:
cholesky (page 767), LDLdecomposition (page 763), LUdecomposition (page 764),
QRsolve (page 767)

Examples

This is the example from wikipedia:

>>> from sympy import Matrix

>>> A = Matrix([[12, -51, 4], [6, 167, -68], [-4, 24, -41]])
>>> Q, R = A.QRdecomposition()
>>> Q
Matrix([
[ 6/7, -69/175, -58/175],
[ 3/7, 158/175, 6/175],
[-2/7, 6/35, -33/35]])
(continues on next page)

766 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> R
Matrix([
[14, 21, -14],
[ 0, 175, -70],
[ 0, 0, 35]])
>>> A == Q*R
True

QR factorization of an identity matrix:

>>> A = Matrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

>>> Q, R = A.QRdecomposition()
>>> Q
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> R
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

QRsolve(b)
Solve the linear system ‘Ax = b’.
‘self’ is the matrix ‘A’, the method argument is the vector ‘b’. The method returns
the solution vector ‘x’. If ‘b’ is a matrix, the system is solved for each column of ‘b’
and the return value is a matrix of the same shape as ‘b’.
This method is slower (approximately by a factor of 2) but more stable for floating-
point arithmetic than the LUsolve method. However, LUsolve usually uses an exact
arithmetic, so you don’t need to use QRsolve.
This is mainly for educational purposes and symbolic matrices, for real (or complex)
matrices use mpmath.qr_solve.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
gauss_jordan_solve (page 770), cholesky_solve (page 768), diagonal_solve
(page 769), LDLsolve (page 764), LUsolve (page 766), pinv_solve (page 774),
QRdecomposition (page 766)
add(b)
Return self + b
cholesky()
Returns the Cholesky decomposition L of a matrix A such that L * L.H = A
A must be a Hermitian positive-definite matrix.
See also:
LDLdecomposition (page 763), LUdecomposition (page 764), QRdecomposition
(page 766)

5.18. Matrices 767

SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import Matrix

>>> A = Matrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
>>> A.cholesky()
Matrix([
[ 5, 0, 0],
[ 3, 3, 0],
[-1, 1, 3]])
>>> A.cholesky() * A.cholesky().T
Matrix([
[25, 15, -5],
[15, 18, 0],
[-5, 0, 11]])

The matrix can have complex entries:

>>> from sympy import I

>>> A = Matrix(((9, 3*I), (-3*I, 5)))
>>> A.cholesky()
Matrix([
[ 3, 0],
[-I, 2]])
>>> A.cholesky() * A.cholesky().H
Matrix([
[ 9, 3*I],
[-3*I, 5]])

cholesky_solve(rhs)
Solves Ax = B using Cholesky decomposition, for a general square non-singular ma-
trix. For a non-square matrix with rows > cols, the least squares solution is returned.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
gauss_jordan_solve (page 770), diagonal_solve (page 769), LDLsolve (page 764),
LUsolve (page 766), QRsolve (page 767), pinv_solve (page 774)
condition_number()
Returns the condition number of a matrix.
This is the maximum singular value divided by the minimum singular value
See also:
singular_values

Examples

>>> from sympy import Matrix, S

>>> A = Matrix([[1, 0, 0], [0, 10, 0], [0, 0, S.One/10]])
>>> A.condition_number()
100

copy()
Returns the copy of a matrix.

768 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Matrix

>>> A = Matrix(2, 2, [1, 2, 3, 4])
>>> A.copy()
Matrix([
[1, 2],
[3, 4]])

cross(b)
Return the cross product of self and b relaxing the condition of compatible dimen-
sions: if each has 3 elements, a matrix of the same type and shape as self will be
returned. If b has the same shape as self then common identities for the cross
product (like a × b = −b × a) will hold.
Parameters b : 3x1 or 1x3 Matrix
See also:
dot (page 769), multiply (page 773), multiply_elementwise
diagonal_solve(rhs)
Solves Ax = B efficiently, where A is a diagonal Matrix, with non-zero diagonal en-
tries.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
gauss_jordan_solve (page 770), cholesky_solve (page 768), LDLsolve (page 764),
LUsolve (page 766), QRsolve (page 767), pinv_solve (page 774)

Examples

>>> from sympy.matrices import Matrix, eye

>>> A = eye(2)*2
>>> B = Matrix([[1, 2], [3, 4]])
>>> A.diagonal_solve(B) == B/2
True

dot(b)
Return the dot product of two vectors of equal length. self must be a Matrix of
size 1 x n or n x 1, and b must be either a matrix of size 1 x n, n x 1, or a list/tuple of
length n. A scalar is returned.
See also:
cross (page 769), multiply (page 773), multiply_elementwise

Examples

>>> from sympy import Matrix

>>> M = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> v = Matrix([1, 1, 1])
>>> M.row(0).dot(v)
6
(continues on next page)

5.18. Matrices 769

SymPy Documentation, Release 1.3

(continued from previous page)

>>> M.col(0).dot(v)
12
>>> v = [3, 2, 1]
>>> M.row(0).dot(v)
10

dual()
Returns the dual of a matrix, which is:
(1/2) ∗ levicivita(i, j, k, l) ∗ M (k, l) summed over indices k and l
Since the levicivita method is anti_symmetric for any pairwise exchange of indices,
the dual of a symmetric matrix is the zero matrix. Strictly speaking the dual defined
here assumes that the ‘matrix’ M is a contravariant anti_symmetric second rank
tensor, so that the dual is a covariant second rank tensor.
exp()
Return the exponentiation of a square matrix.
gauss_jordan_solve(b, freevar=False)
Solves Ax = b using Gauss Jordan elimination.
There may be zero, one, or infinite solutions. If one solution exists, it will be re-
turned. If infinite solutions exist, it will be returned parametrically. If no solutions
exist, It will throw ValueError.
Parameters b : Matrix
The right hand side of the equation to be solved for. Must have the
same number of rows as matrix A.
freevar : List
If the system is underdetermined (e.g. A has more columns than
rows), infinite solutions are possible, in terms of arbitrary values of
free variables. Then the index of the free variables in the solutions
(column Matrix) will be returned by freevar, if the flag f reevar is set
to T rue.
Returns x : Matrix
The matrix that will satisfy Ax = B. Will have as many rows as matrix
A has columns, and as many columns as matrix B.
params : Matrix
If the system is underdetermined (e.g. A has more columns than
rows), infinite solutions are possible, in terms of arbitrary parame-
ters. These arbitrary parameters are returned as params Matrix.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
cholesky_solve (page 768), diagonal_solve (page 769), LDLsolve (page 764), LU-
solve (page 766), QRsolve (page 767), pinv (page 774)

References

[R430]

770 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Matrix

>>> A = Matrix([[1, 2, 1, 1], [1, 2, 2, -1], [2, 4, 0, 6]])
>>> b = Matrix([7, 12, 4])
>>> sol, params = A.gauss_jordan_solve(b)
>>> sol
Matrix([
[-2*tau0 - 3*tau1 + 2],
[ tau0],
[ 2*tau1 + 5],
[ tau1]])
>>> params
Matrix([
[tau0],
[tau1]])

>>> A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 10]])

>>> b = Matrix([3, 6, 9])
>>> sol, params = A.gauss_jordan_solve(b)
>>> sol
Matrix([
[-1],
[ 2],
[ 0]])
>>> params
Matrix(0, 1, [])

inv(method=None, **kwargs)
Return the inverse of a matrix.
CASE 1: If the matrix is a dense matrix.
Return the matrix inverse using the method indicated (default is Gauss elimination).
Parameters method : (‘GE’, ‘LU’, or ‘ADJ’)
Raises ValueError
If the determinant of the matrix is zero.
See also:
inverse_LU (page 772), inverse_GE (page 772), inverse_ADJ (page 772)

Notes

According to the method keyword, it calls the appropriate method:

LDL … inverse_LDL(); default CH …. inverse_CH()

Kwargs

method : (‘CH’, ‘LDL’)

inv_mod(m)
Returns the inverse of the matrix K (mod m), if it exists.

5.18. Matrices 771

SymPy Documentation, Release 1.3

Method to find the matrix inverse of K (mod m) implemented in this function:

• Compute adj(K) = cof(K)t , the adjoint matrix of K.
• Compute r = 1/det(K) (mod m).
• K −1 = r · adj(K) (mod m).

Examples

>>> from sympy import Matrix

>>> A = Matrix(2, 2, [1, 2, 3, 4])
>>> A.inv_mod(5)
Matrix([
[3, 1],
[4, 2]])
>>> A.inv_mod(3)
Matrix([
[1, 1],
[0, 1]])

inverse_ADJ(iszerofunc=<function _iszero>)
Calculates the inverse using the adjugate matrix and a determinant.
See also:
inv (page 771), inverse_LU (page 772), inverse_GE (page 772)
inverse_GE(iszerofunc=<function _iszero>)
Calculates the inverse using Gaussian elimination.
See also:
inv (page 771), inverse_LU (page 772), inverse_ADJ (page 772)
inverse_LU(iszerofunc=<function _iszero>)
Calculates the inverse using LU decomposition.
See also:
inv (page 771), inverse_GE (page 772), inverse_ADJ (page 772)
is_nilpotent()
Checks if a matrix is nilpotent.
A matrix B is nilpotent if for some integer k, B**k is a zero matrix.

Examples

>>> from sympy import Matrix

>>> a = Matrix([[0, 0, 0], [1, 0, 0], [1, 1, 0]])
>>> a.is_nilpotent()
True

>>> a = Matrix([[1, 0, 1], [1, 0, 0], [1, 1, 0]])

>>> a.is_nilpotent()
False

772 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

key2bounds(keys)
Converts a key with potentially mixed types of keys (integer and slice) into a tuple
of ranges and raises an error if any index is out of self’s range.
See also:
key2ij (page 773)
key2ij(key)
Converts key into canonical form, converting integers or indexable items into valid
integers for self’s range or returning slices unchanged.
See also:
key2bounds (page 772)
lower_triangular_solve(rhs)
Solves Ax = B, where A is a lower triangular matrix.
See also:
upper_triangular_solve (page 778), gauss_jordan_solve (page 770),
cholesky_solve (page 768), diagonal_solve (page 769), LDLsolve (page 764),
LUsolve (page 766), QRsolve (page 767), pinv_solve (page 774)
multiply(b)
Returns self*b
See also:
dot (page 769), cross (page 769), multiply_elementwise
norm(ord=None)
Return the Norm of a Matrix or Vector. In the simplest case this is the geometric
size of the vector Other norms can be specified by the ord parameter

ord norm for matrices norm for vectors

None Frobenius norm 2-norm
‘fro’ Frobenius norm
• does not exist

inf maximum row sum max(abs(x))

-inf – min(abs(x))
1 maximum column sum as below
-1 – as below
2 2-norm (largest sing. as below
value)
-2 smallest singular value as below
other sum(abs(x)**ord)**(1./ord)
• does not exist

See also:
normalized (page 774)

5.18. Matrices 773

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Matrix, Symbol, trigsimp, cos, sin, oo

>>> x = Symbol('x', real=True)
>>> v = Matrix([cos(x), sin(x)])
>>> trigsimp( v.norm() )
1
>>> v.norm(10)
(sin(x)**10 + cos(x)**10)**(1/10)
>>> A = Matrix([[1, 1], [1, 1]])
>>> A.norm(1) # maximum sum of absolute values of A is 2
2
>>> A.norm(2) # Spectral norm (max of |Ax|/|x| under 2-vector-norm)
2
>>> A.norm(-2) # Inverse spectral norm (smallest singular value)
0
>>> A.norm() # Frobenius Norm
2
>>> A.norm(oo) # Infinity Norm
2
>>> Matrix([1, -2]).norm(oo)
2
>>> Matrix([-1, 2]).norm(-oo)
1

normalized()
Return the normalized version of self.
See also:
norm (page 773)
pinv()
Calculate the Moore-Penrose pseudoinverse of the matrix.
The Moore-Penrose pseudoinverse exists and is unique for any matrix. If the matrix
is invertible, the pseudoinverse is the same as the inverse.
See also:
inv (page 771), pinv_solve (page 774)

References

[R431]

Examples

>>> from sympy import Matrix

>>> Matrix([[1, 2, 3], [4, 5, 6]]).pinv()
Matrix([
[-17/18, 4/9],
[ -1/9, 1/9],
[ 13/18, -2/9]])

774 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

pinv_solve(B, arbitrary_matrix=None)
Solve Ax = B using the Moore-Penrose pseudoinverse.
There may be zero, one, or infinite solutions. If one solution exists, it will be re-
turned. If infinite solutions exist, one will be returned based on the value of arbi-
trary_matrix. If no solutions exist, the least-squares solution is returned.
Parameters B : Matrix
The right hand side of the equation to be solved for. Must have the
same number of rows as matrix A.
arbitrary_matrix : Matrix
If the system is underdetermined (e.g. A has more columns than
rows), infinite solutions are possible, in terms of an arbitrary matrix.
This parameter may be set to a specific matrix to use for that purpose;
if so, it must be the same shape as x, with as many rows as matrix A
has columns, and as many columns as matrix B. If left as None, an ap-
propriate matrix containing dummy symbols in the form of wn_m will
be used, with n and m being row and column position of each symbol.
Returns x : Matrix
The matrix that will satisfy Ax = B. Will have as many rows as matrix
A has columns, and as many columns as matrix B.
See also:
lower_triangular_solve (page 773), upper_triangular_solve (page 778),
gauss_jordan_solve (page 770), cholesky_solve (page 768), diagonal_solve
(page 769), LDLsolve (page 764), LUsolve (page 766), QRsolve (page 767), pinv
(page 774)

Notes

This may return either exact solutions or least squares solutions. To determine
which, check A * A.pinv() * B == B. It will be True if exact solutions exist, and
False if only a least-squares solution exists. Be aware that the left hand side of that
equation may need to be simplified to correctly compare to the right hand side.

References

[R432]

Examples

>>> from sympy import Matrix

>>> A = Matrix([[1, 2, 3], [4, 5, 6]])
>>> B = Matrix([7, 8])
>>> A.pinv_solve(B)
Matrix([
[ _w0_0/6 - _w1_0/3 + _w2_0/6 - 55/18],
[-_w0_0/3 + 2*_w1_0/3 - _w2_0/3 + 1/9],
[ _w0_0/6 - _w1_0/3 + _w2_0/6 + 59/18]])
(continues on next page)

5.18. Matrices 775

SymPy Documentation, Release 1.3

(continued from previous page)

>>> A.pinv_solve(B, arbitrary_matrix=Matrix([0, 0, 0]))
Matrix([
[-55/18],
[ 1/9],
[ 59/18]])

print_nonzero(symb=’X’)
Shows location of non-zero entries for fast shape lookup.

Examples

>>> from sympy.matrices import Matrix, eye

>>> m = Matrix(2, 3, lambda i, j: i*3+j)
>>> m
Matrix([
[0, 1, 2],
[3, 4, 5]])
>>> m.print_nonzero()
[ XX]
[XXX]
>>> m = eye(4)
>>> m.print_nonzero(”x”)
[x ]
[ x ]
[ x ]
[ x]

project(v)
Return the projection of self onto the line containing v.

Examples

>>> from sympy import Matrix, S, sqrt

>>> V = Matrix([sqrt(3)/2, S.Half])
>>> x = Matrix([[1, 0]])
>>> V.project(x)
Matrix([[sqrt(3)/2, 0]])
>>> V.project(-x)
Matrix([[sqrt(3)/2, 0]])

solve(rhs, method=’GE’)
Return solution to self*soln = rhs using given inversion method.
For a list of possible inversion methods, see the .inv() docstring.
solve_least_squares(rhs, method=’CH’)
Return the least-square fit to the data.
By default the cholesky_solve routine is used (method=’CH’); other methods of ma-
trix inversion can be used. To find out which are available, see the docstring of the
.inv() method.

776 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import Matrix, ones

>>> A = Matrix([1, 2, 3])
>>> B = Matrix([2, 3, 4])
>>> S = Matrix(A.row_join(B))
>>> S
Matrix([
[1, 2],
[2, 3],
[3, 4]])

If each line of S represent coefficients of Ax + By and x and y are [2, 3] then S*xy is:

>>> r = S*Matrix([2, 3]); r

Matrix([
[ 8],
[13],
[18]])

But let’s add 1 to the middle value and then solve for the least-squares value of xy:

>>> xy = S.solve_least_squares(Matrix([8, 14, 18])); xy

Matrix([
[ 5/3],
[10/3]])

The error is given by S*xy - r:

>>> S*xy - r
Matrix([
[1/3],
[1/3],
[1/3]])
>>> _.norm().n(2)
0.58

If a different xy is used, the norm will be higher:

>>> xy += ones(2, 1)/10

>>> (S*xy - r).norm().n(2)
1.5

table(printer, rowstart=’[’, rowend=’]’, rowsep=’\n’, colsep=’, ’, align=’right’)

String form of Matrix as a table.
printer is the printer to use for on the elements (generally something like Str-
Printer())
rowstart is the string used to start each row (by default ‘[‘).
rowend is the string used to end each row (by default ‘]’).
rowsep is the string used to separate rows (by default a newline).
colsep is the string used to separate columns (by default ‘, ‘).
align defines how the elements are aligned. Must be one of ‘left’, ‘right’, or ‘center’.
You can also use ‘<’, ‘>’, and ‘^’ to mean the same thing, respectively.

5.18. Matrices 777

SymPy Documentation, Release 1.3

This is used by the string printer for Matrix.

Examples

>>> from sympy import Matrix

>>> from sympy.printing.str import StrPrinter
>>> M = Matrix([[1, 2], [-33, 4]])
>>> printer = StrPrinter()
>>> M.table(printer)
'[ 1, 2]\n[-33, 4]'
>>> print(M.table(printer))
[ 1, 2]
[-33, 4]
>>> print(M.table(printer, rowsep=',\n'))
[ 1, 2],
[-33, 4]
>>> print('[%s]' % M.table(printer, rowsep=',\n'))
[[ 1, 2],
[-33, 4]]
>>> print(M.table(printer, colsep=' '))
[ 1 2]
[-33 4]
>>> print(M.table(printer, align='center'))
[ 1 , 2]
[-33, 4]
>>> print(M.table(printer, rowstart='{', rowend='}'))
{ 1, 2}
{-33, 4}

upper_triangular_solve(rhs)
Solves Ax = B, where A is an upper triangular matrix.
See also:
lower_triangular_solve (page 773), gauss_jordan_solve (page 770),
cholesky_solve (page 768), diagonal_solve (page 769), LDLsolve (page 764),
LUsolve (page 766), QRsolve (page 767), pinv_solve (page 774)
vech(diagonal=True, check_symmetry=True)
Return the unique elements of a symmetric Matrix as a one column matrix by stack-
ing the elements in the lower triangle.
Arguments: diagonal – include the diagonal cells of self or not check_symmetry –
checks symmetry of self but not completely reliably
See also:
vec

Examples

>>> from sympy import Matrix

>>> m=Matrix([[1, 2], [2, 3]])
>>> m
Matrix([
[1, 2],
(continues on next page)

778 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[2, 3]])
>>> m.vech()
Matrix([
[1],
[2],
[3]])
>>> m.vech(diagonal=False)
Matrix([[2]])

Matrix Exceptions Reference

class sympy.matrices.matrices.MatrixError
class sympy.matrices.matrices.ShapeError
Wrong matrix shape
class sympy.matrices.matrices.NonSquareMatrixError

Matrix Functions Reference

sympy.matrices.dense.matrix_multiply_elementwise(A, B)
Return the Hadamard product (elementwise product) of A and B
>>> from sympy.matrices import matrix_multiply_elementwise
>>> from sympy.matrices import Matrix
>>> A = Matrix([[0, 1, 2], [3, 4, 5]])
>>> B = Matrix([[1, 10, 100], [100, 10, 1]])
>>> matrix_multiply_elementwise(A, B)
Matrix([
[ 0, 10, 200],
[300, 40, 5]])

See also:
__mul__
sympy.matrices.dense.zeros(*args, **kwargs)
Returns a matrix of zeros with rows rows and cols columns; if cols is omitted a square
matrix will be returned.
See also:
ones (page 779), eye (page 779), diag (page 780)
sympy.matrices.dense.ones(*args, **kwargs)
Returns a matrix of ones with rows rows and cols columns; if cols is omitted a square
matrix will be returned.
See also:
zeros (page 779), eye (page 779), diag (page 780)
sympy.matrices.dense.eye(*args, **kwargs)
Create square identity matrix n x n
See also:
diag (page 780), zeros (page 779), ones (page 779)

5.18. Matrices 779

SymPy Documentation, Release 1.3

sympy.matrices.dense.diag(*values, **kwargs)
Create a sparse, diagonal matrix from a list of diagonal values.
See also:
eye (page 779)

Notes

When arguments are matrices they are fitted in resultant matrix.

The returned matrix is a mutable, dense matrix. To make it a different type, send the
desired class for keyword cls.

Examples

>>> from sympy.matrices import diag, Matrix, ones

>>> diag(1, 2, 3)
Matrix([
[1, 0, 0],
[0, 2, 0],
[0, 0, 3]])
>>> diag(*[1, 2, 3])
Matrix([
[1, 0, 0],
[0, 2, 0],
[0, 0, 3]])

The diagonal elements can be matrices; diagonal filling will continue on the diagonal
from the last element of the matrix:

>>> from sympy.abc import x, y, z

>>> a = Matrix([x, y, z])
>>> b = Matrix([[1, 2], [3, 4]])
>>> c = Matrix([[5, 6]])
>>> diag(a, 7, b, c)
Matrix([
[x, 0, 0, 0, 0, 0],
[y, 0, 0, 0, 0, 0],
[z, 0, 0, 0, 0, 0],
[0, 7, 0, 0, 0, 0],
[0, 0, 1, 2, 0, 0],
[0, 0, 3, 4, 0, 0],
[0, 0, 0, 0, 5, 6]])

When diagonal elements are lists, they will be treated as arguments to Matrix:

>>> diag([1, 2, 3], 4)

Matrix([
[1, 0],
[2, 0],
[3, 0],
[0, 4]])
>>> diag([[1, 2, 3]], 4)
Matrix([
(continues on next page)

780 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[1, 2, 3, 0],
[0, 0, 0, 4]])

A given band off the diagonal can be made by padding with a vertical or horizontal “kern-
ing” vector:

>>> hpad = ones(0, 2)

>>> vpad = ones(2, 0)
>>> diag(vpad, 1, 2, 3, hpad) + diag(hpad, 4, 5, 6, vpad)
Matrix([
[0, 0, 4, 0, 0],
[0, 0, 0, 5, 0],
[1, 0, 0, 0, 6],
[0, 2, 0, 0, 0],
[0, 0, 3, 0, 0]])

The type is mutable by default but can be made immutable by setting the mutable flag
to False:

>>> type(diag(1))
<class 'sympy.matrices.dense.MutableDenseMatrix'>
>>> from sympy.matrices import ImmutableMatrix
>>> type(diag(1, cls=ImmutableMatrix))
<class 'sympy.matrices.immutable.ImmutableDenseMatrix'>

sympy.matrices.dense.jordan_cell(eigenval, n)
Create a Jordan block:

Examples

>>> from sympy.matrices import jordan_cell

>>> from sympy.abc import x
>>> jordan_cell(x, 4)
Matrix([
[x, 1, 0, 0],
[0, x, 1, 0],
[0, 0, x, 1],
[0, 0, 0, x]])

sympy.matrices.dense.hessian(f, varlist, constraints=[])

Compute Hessian matrix for a function f wrt parameters in varlist which may be given
as a sequence or a row/column vector. A list of constraints may optionally be given.
See also:
sympy.matrices.mutable.Matrix.jacobian, wronskian (page 782)

References

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

5.18. Matrices 781

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, hessian, pprint

>>> from sympy.abc import x, y
>>> f = Function('f')(x, y)
>>> g1 = Function('g')(x, y)
>>> g2 = x**2 + 3*y
>>> pprint(hessian(f, (x, y), [g1, g2]))
[ d d ]
[ 0 0 --(g(x, y)) --(g(x, y)) ]
[ dx dy ]
[ ]
[ 0 0 2*x 3 ]
[ ]
[ 2 2 ]
[d d d ]
[--(g(x, y)) 2*x ---(f(x, y)) -----(f(x, y))]
[dx 2 dy dx ]
[ dx ]
[ ]
[ 2 2 ]
[d d d ]
[--(g(x, y)) 3 -----(f(x, y)) ---(f(x, y)) ]
[dy dy dx 2 ]
[ dy ]

sympy.matrices.dense.GramSchmidt(vlist, orthonormal=False)
Apply the Gram-Schmidt process to a set of vectors.
see: http://en.wikipedia.org/wiki/Gram%E2%80%93Schmidt_process
sympy.matrices.dense.wronskian(functions, var, method=’bareiss’)
Compute Wronskian for [] of functions

| f1 f2 ... fn |
| f1' f2' ... fn' |
| . . . . |
W(f1, ..., fn) = | . . . . |
| . . . . |
| (n) (n) (n) |
| D (f1) D (f2) ... D (fn) |

see: http://en.wikipedia.org/wiki/Wronskian
See also:
sympy.matrices.mutable.Matrix.jacobian, hessian (page 781)
sympy.matrices.dense.casoratian(seqs, n, zero=True)
Given linear difference operator L of order ‘k’ and homogeneous equation Ly = 0 we
want to compute kernel of L, which is a set of ‘k’ sequences: a(n), b(n), … z(n).
Solutions of L are linearly independent iff their Casoratian, denoted as C(a, b, …, z), do
not vanish for n = 0.
Casoratian is defined by k x k determinant:

+ a(n) b(n) . . . z(n) +

| a(n+1) b(n+1) . . . z(n+1) |
(continues on next page)

782 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

| . . . . |
| . . . . |
| . . . . |
+ a(n+k-1) b(n+k-1) . . . z(n+k-1) +

It proves very useful in rsolve_hyper() where it is applied to a generating set of a recur-

rence to factor out linearly dependent solutions and return a basis:

>>> from sympy import Symbol, casoratian, factorial

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

Exponential and factorial are linearly independent:

>>> casoratian([2**n, factorial(n)], n) != 0

True

sympy.matrices.dense.randMatrix(r, c=None, min=0, max=99, seed=None, symmet-

ric=False, percent=100, prng=None)
Create random matrix with dimensions r x c. If c is omitted the matrix will be square.
If symmetric is True the matrix must be square. If percent is less than 100 then only
approximately the given percentage of elements will be non-zero.
The pseudo-random number generator used to generate matrix is chosen in the following
way.
• If prng is supplied, it will be used as random number generator. It should be an
instance of random.Random, or at least have randint and shuffle methods with
same signatures.
• if prng is not supplied but seed is supplied, then new random.Random with given
seed will be created;
• otherwise, a new random.Random with default seed will be used.

Examples

>>> from sympy.matrices import randMatrix

>>> randMatrix(3) # doctest:+SKIP
[25, 45, 27]
[44, 54, 9]
[23, 96, 46]
>>> randMatrix(3, 2) # doctest:+SKIP
[87, 29]
[23, 37]
[90, 26]
>>> randMatrix(3, 3, 0, 2) # doctest:+SKIP
[0, 2, 0]
[2, 0, 1]
[0, 0, 1]
>>> randMatrix(3, symmetric=True) # doctest:+SKIP
[85, 26, 29]
[26, 71, 43]
[29, 43, 57]
>>> A = randMatrix(3, seed=1)
>>> B = randMatrix(3, seed=2)
(continues on next page)

5.18. Matrices 783

SymPy Documentation, Release 1.3

(continued from previous page)

>>> A == B # doctest:+SKIP
False
>>> A == randMatrix(3, seed=1)
True
>>> randMatrix(3, symmetric=True, percent=50) # doctest:+SKIP
[77, 70, 0],
[70, 0, 0],
[ 0, 0, 88]

Numpy Utility Functions Reference

sympy.matrices.dense.list2numpy(l, dtype=<class ’object’>)

Converts python list of SymPy expressions to a NumPy array.
See also:
matrix2numpy (page 784)
sympy.matrices.dense.matrix2numpy(m, dtype=<class ’object’>)
Converts SymPy’s matrix to a NumPy array.
See also:
list2numpy (page 784)
sympy.matrices.dense.symarray(prefix, shape, **kwargs)
Create a numpy ndarray of symbols (as an object array).
The created symbols are named prefix_i1_i2_… You should thus provide a non-empty
prefix if you want your symbols to be unique for different output arrays, as SymPy sym-
bols with identical names are the same object.
Parameters prefix : string
A prefix prepended to the name of every symbol.
shape : int or tuple
Shape of the created array. If an int, the array is one-dimensional; for
more than one dimension the shape must be a tuple.
**kwargs : dict
keyword arguments passed on to Symbol

Examples

These doctests require numpy.

>>> from sympy import symarray

>>> symarray('', 3)
[_0 _1 _2]

If you want multiple symarrays to contain distinct symbols, you must provide unique
prefixes:

784 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> a = symarray('', 3)
>>> b = symarray('', 3)
>>> a[0] == b[0]
True
>>> a = symarray('a', 3)
>>> b = symarray('b', 3)
>>> a[0] == b[0]
False

Creating symarrays with a prefix:

>>> symarray('a', 3)
[a_0 a_1 a_2]

For more than one dimension, the shape must be given as a tuple:

>>> symarray('a', (2, 3))

[[a_0_0 a_0_1 a_0_2]
[a_1_0 a_1_1 a_1_2]]
>>> symarray('a', (2, 3, 2))
[[[a_0_0_0 a_0_0_1]
[a_0_1_0 a_0_1_1]
[a_0_2_0 a_0_2_1]]
<BLANKLINE>
[[a_1_0_0 a_1_0_1]
[a_1_1_0 a_1_1_1]
[a_1_2_0 a_1_2_1]]]

For setting assumptions of the underlying Symbols:

>>> [s.is_real for s in symarray('a', 2, real=True)]

[True, True]

sympy.matrices.dense.rot_axis1(theta)
Returns a rotation matrix for a rotation of theta (in radians) about the 1-axis.
See also:

rot_axis2 (page 786) Returns a rotation matrix for a rotation of theta (in radians)
about the 2-axis
rot_axis3 (page 786) Returns a rotation matrix for a rotation of theta (in radians)
about the 3-axis

Examples

>>> from sympy import pi

>>> from sympy.matrices import rot_axis1

A rotation of pi/3 (60 degrees):

>>> theta = pi/3

>>> rot_axis1(theta)
Matrix([
[1, 0, 0],
(continues on next page)

5.18. Matrices 785

SymPy Documentation, Release 1.3

(continued from previous page)

[0, 1/2, sqrt(3)/2],
[0, -sqrt(3)/2, 1/2]])

If we rotate by pi/2 (90 degrees):

>>> rot_axis1(pi/2)
Matrix([
[1, 0, 0],
[0, 0, 1],
[0, -1, 0]])

sympy.matrices.dense.rot_axis2(theta)
Returns a rotation matrix for a rotation of theta (in radians) about the 2-axis.
See also:

rot_axis1 (page 785) Returns a rotation matrix for a rotation of theta (in radians)
about the 1-axis
rot_axis3 (page 786) Returns a rotation matrix for a rotation of theta (in radians)
about the 3-axis

Examples

>>> from sympy import pi

>>> from sympy.matrices import rot_axis2

A rotation of pi/3 (60 degrees):

>>> theta = pi/3

>>> rot_axis2(theta)
Matrix([
[ 1/2, 0, -sqrt(3)/2],
[ 0, 1, 0],
[sqrt(3)/2, 0, 1/2]])

If we rotate by pi/2 (90 degrees):

>>> rot_axis2(pi/2)
Matrix([
[0, 0, -1],
[0, 1, 0],
[1, 0, 0]])

sympy.matrices.dense.rot_axis3(theta)
Returns a rotation matrix for a rotation of theta (in radians) about the 3-axis.
See also:

rot_axis1 (page 785) Returns a rotation matrix for a rotation of theta (in radians)
about the 1-axis
rot_axis2 (page 786) Returns a rotation matrix for a rotation of theta (in radians)
about the 2-axis

786 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import pi

>>> from sympy.matrices import rot_axis3

A rotation of pi/3 (60 degrees):

>>> theta = pi/3
>>> rot_axis3(theta)
Matrix([
[ 1/2, sqrt(3)/2, 0],
[-sqrt(3)/2, 1/2, 0],
[ 0, 0, 1]])

If we rotate by pi/2 (90 degrees):

>>> rot_axis3(pi/2)
Matrix([
[ 0, 1, 0],
[-1, 0, 0],
[ 0, 0, 1]])

sympy.matrices.matrices.a2idx(j, n=None)

5.18.2 Dense Matrices

Matrix Class Reference

class sympy.matrices.dense.MutableDenseMatrix

Attributes

cols
rows

col_del(i)
Delete the given column.
See also:
col, row_del (page 789)

Examples

>>> from sympy.matrices import eye

>>> M = eye(3)
>>> M.col_del(1)
>>> M
Matrix([
[1, 0],
[0, 0],
[0, 1]])

5.18. Matrices 787

SymPy Documentation, Release 1.3

col_op(j, f)
In-place operation on col j using two-arg functor whose args are interpreted as
(self[i, j], i).
See also:
col, row_op (page 790)

Examples

>>> from sympy.matrices import eye

>>> M = eye(3)
>>> M.col_op(1, lambda v, i: v + 2*M[i, 0]); M
Matrix([
[1, 2, 0],
[0, 1, 0],
[0, 0, 1]])

col_swap(i, j)
Swap the two given columns of the matrix in-place.
See also:
col, row_swap (page 790)

Examples

>>> from sympy.matrices import Matrix

>>> M = Matrix([[1, 0], [1, 0]])
>>> M
Matrix([
[1, 0],
[1, 0]])
>>> M.col_swap(0, 1)
>>> M
Matrix([
[0, 1],
[0, 1]])

copyin_list(key, value)
Copy in elements from a list.
Parameters key : slice
The section of this matrix to replace.
value : iterable
The iterable to copy values from.
See also:
copyin_matrix (page 789)

788 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import eye

>>> I = eye(3)
>>> I[:2, 0] = [1, 2] # col
>>> I
Matrix([
[1, 0, 0],
[2, 1, 0],
[0, 0, 1]])
>>> I[1, :2] = [[3, 4]]
>>> I
Matrix([
[1, 0, 0],
[3, 4, 0],
[0, 0, 1]])

copyin_matrix(key, value)
Copy in values from a matrix into the given bounds.
Parameters key : slice
The section of this matrix to replace.
value : Matrix
The matrix to copy values from.
See also:
copyin_list (page 788)

Examples

>>> from sympy.matrices import Matrix, eye

>>> M = Matrix([[0, 1], [2, 3], [4, 5]])
>>> I = eye(3)
>>> I[:3, :2] = M
>>> I
Matrix([
[0, 1, 0],
[2, 3, 0],
[4, 5, 1]])
>>> I[0, 1] = M
>>> I
Matrix([
[0, 0, 1],
[2, 2, 3],
[4, 4, 5]])

fill(value)
Fill the matrix with the scalar value.
See also:
zeros (page 779), ones (page 779)
row_del(i)
Delete the given row.

5.18. Matrices 789

SymPy Documentation, Release 1.3

See also:
row, col_del (page 787)

Examples

>>> from sympy.matrices import eye

>>> M = eye(3)
>>> M.row_del(1)
>>> M
Matrix([
[1, 0, 0],
[0, 0, 1]])

row_op(i, f)
In-place operation on row i using two-arg functor whose args are interpreted as
(self[i, j], j).
See also:
row, zip_row_op (page 791), col_op (page 787)

Examples

>>> from sympy.matrices import eye

>>> M = eye(3)
>>> M.row_op(1, lambda v, j: v + 2*M[0, j]); M
Matrix([
[1, 0, 0],
[2, 1, 0],
[0, 0, 1]])

row_swap(i, j)
Swap the two given rows of the matrix in-place.
See also:
row, col_swap (page 788)

Examples

>>> from sympy.matrices import Matrix

>>> M = Matrix([[0, 1], [1, 0]])
>>> M
Matrix([
[0, 1],
[1, 0]])
>>> M.row_swap(0, 1)
>>> M
Matrix([
[1, 0],
[0, 1]])

790 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

simplify(ratio=1.7, measure=<function count_ops>, rational=False, in-

verse=False)
Applies simplify to the elements of a matrix in place.
This is a shortcut for M.applyfunc(lambda x: simplify(x, ratio, measure))
See also:
sympy.simplify.simplify.simplify (page 1185)
zip_row_op(i, k, f)
In-place operation on row i using two-arg functor whose args are interpreted as
(self[i, j], self[k, j]).
See also:
row, row_op (page 790), col_op (page 787)

Examples

>>> from sympy.matrices import eye

>>> M = eye(3)
>>> M.zip_row_op(1, 0, lambda v, u: v + 2*u); M
Matrix([
[1, 0, 0],
[2, 1, 0],
[0, 0, 1]])

ImmutableMatrix Class Reference

class sympy.matrices.immutable.ImmutableDenseMatrix
Create an immutable version of a matrix.

Examples

>>> from sympy import eye

>>> from sympy.matrices import ImmutableMatrix
>>> ImmutableMatrix(eye(3))
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> _[0, 0] = 42
Traceback (most recent call last):
...
TypeError: Cannot set values of ImmutableDenseMatrix

is_zero
Checks if a matrix is a zero matrix.
A matrix is zero if every element is zero. A matrix need not be square to be consid-
ered zero. The empty matrix is zero by the principle of vacuous truth. For a matrix
that may or may not be zero (e.g. contains a symbol), this will be None

5.18. Matrices 791

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Matrix, zeros

>>> from sympy.abc import x
>>> a = Matrix([[0, 0], [0, 0]])
>>> b = zeros(3, 4)
>>> c = Matrix([[0, 1], [0, 0]])
>>> d = Matrix([])
>>> e = Matrix([[x, 0], [0, 0]])
>>> a.is_zero
True
>>> b.is_zero
True
>>> c.is_zero
False
>>> d.is_zero
True
>>> e.is_zero

5.18.3 Sparse Matrices

SparseMatrix Class Reference

class sympy.matrices.sparse.SparseMatrix
A sparse matrix (a matrix with a large number of zero elements).
See also:
sympy.matrices.dense.Matrix

Examples

>>> from sympy.matrices import SparseMatrix

>>> SparseMatrix(2, 2, range(4))
Matrix([
[0, 1],
[2, 3]])
>>> SparseMatrix(2, 2, {(1, 1): 2})
Matrix([
[0, 0],
[0, 2]])

Attributes

cols
rows

CL
Alternate faster representation

792 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

LDLdecomposition()
Returns the LDL Decomposition (matrices L and D) of matrix A, such that L * D *
L.T == A. A must be a square, symmetric, positive-definite and non-singular.
This method eliminates the use of square root and ensures that all the diagonal
entries of L are 1.

Examples

>>> from sympy.matrices import SparseMatrix

>>> A = SparseMatrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
>>> L, D = A.LDLdecomposition()
>>> L
Matrix([
[ 1, 0, 0],
[ 3/5, 1, 0],
[-1/5, 1/3, 1]])
>>> D
Matrix([
[25, 0, 0],
[ 0, 9, 0],
[ 0, 0, 9]])
>>> L * D * L.T == A
True

RL
Alternate faster representation
applyfunc(f)
Apply a function to each element of the matrix.

Examples

>>> from sympy.matrices import SparseMatrix

>>> m = SparseMatrix(2, 2, lambda i, j: i*2+j)
>>> m
Matrix([
[0, 1],
[2, 3]])
>>> m.applyfunc(lambda i: 2*i)
Matrix([
[0, 2],
[4, 6]])

as_immutable()
Returns an Immutable version of this Matrix.
as_mutable()
Returns a mutable version of this matrix.

Examples

5.18. Matrices 793

SymPy Documentation, Release 1.3

>>> from sympy import ImmutableMatrix

>>> X = ImmutableMatrix([[1, 2], [3, 4]])
>>> Y = X.as_mutable()
>>> Y[1, 1] = 5 # Can set values in Y
>>> Y
Matrix([
[1, 2],
[3, 5]])

cholesky()
Returns the Cholesky decomposition L of a matrix A such that L * L.T = A
A must be a square, symmetric, positive-definite and non-singular matrix

Examples

>>> from sympy.matrices import SparseMatrix

>>> A = SparseMatrix(((25,15,-5),(15,18,0),(-5,0,11)))
>>> A.cholesky()
Matrix([
[ 5, 0, 0],
[ 3, 3, 0],
[-1, 1, 3]])
>>> A.cholesky() * A.cholesky().T == A
True

col_list()
Returns a column-sorted list of non-zero elements of the matrix.
See also:
col_op, row_list (page 795)

Examples

>>> from sympy.matrices import SparseMatrix

>>> a=SparseMatrix(((1, 2), (3, 4)))
>>> a
Matrix([
[1, 2],
[3, 4]])
>>> a.CL
[(0, 0, 1), (1, 0, 3), (0, 1, 2), (1, 1, 4)]

liupc()
Liu’s algorithm, for pre-determination of the Elimination Tree of the given matrix,
used in row-based symbolic Cholesky factorization.

References

Symbolic Sparse Cholesky Factorization using Elimination Trees, Jeroen Van Gron-
delle (1999) http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.39.7582

794 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import SparseMatrix

>>> S = SparseMatrix([
... [1, 0, 3, 2],
... [0, 0, 1, 0],
... [4, 0, 0, 5],
... [0, 6, 7, 0]])
>>> S.liupc()
([[0], [], [0], [1, 2]], [4, 3, 4, 4])

nnz()
Returns the number of non-zero elements in Matrix.
row_list()
Returns a row-sorted list of non-zero elements of the matrix.
See also:
row_op, col_list (page 794)

Examples

>>> from sympy.matrices import SparseMatrix

>>> a = SparseMatrix(((1, 2), (3, 4)))
>>> a
Matrix([
[1, 2],
[3, 4]])
>>> a.RL
[(0, 0, 1), (0, 1, 2), (1, 0, 3), (1, 1, 4)]

row_structure_symbolic_cholesky()
Symbolic cholesky factorization, for pre-determination of the non-zero structure of
the Cholesky factororization.

References

Symbolic Sparse Cholesky Factorization using Elimination Trees, Jeroen Van Gron-
delle (1999) http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.39.7582

Examples

>>> from sympy.matrices import SparseMatrix

>>> S = SparseMatrix([
... [1, 0, 3, 2],
... [0, 0, 1, 0],
... [4, 0, 0, 5],
... [0, 6, 7, 0]])
>>> S.row_structure_symbolic_cholesky()
[[0], [], [0], [1, 2]]

5.18. Matrices 795

SymPy Documentation, Release 1.3

scalar_multiply(scalar)
Scalar element-wise multiplication
solve(rhs, method=’LDL’)
Return solution to self*soln = rhs using given inversion method.
For a list of possible inversion methods, see the .inv() docstring.
solve_least_squares(rhs, method=’LDL’)
Return the least-square fit to the data.
By default the cholesky_solve routine is used (method=’CH’); other methods of ma-
trix inversion can be used. To find out which are available, see the docstring of the
.inv() method.

Examples

>>> from sympy.matrices import SparseMatrix, Matrix, ones

>>> A = Matrix([1, 2, 3])
>>> B = Matrix([2, 3, 4])
>>> S = SparseMatrix(A.row_join(B))
>>> S
Matrix([
[1, 2],
[2, 3],
[3, 4]])

If each line of S represent coefficients of Ax + By and x and y are [2, 3] then S*xy is:

>>> r = S*Matrix([2, 3]); r

Matrix([
[ 8],
[13],
[18]])

But let’s add 1 to the middle value and then solve for the least-squares value of xy:

>>> xy = S.solve_least_squares(Matrix([8, 14, 18])); xy

Matrix([
[ 5/3],
[10/3]])

The error is given by S*xy - r:

>>> S*xy - r
Matrix([
[1/3],
[1/3],
[1/3]])
>>> _.norm().n(2)
0.58

If a different xy is used, the norm will be higher:

>>> xy += ones(2, 1)/10

>>> (S*xy - r).norm().n(2)
1.5

796 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.matrices.sparse.MutableSparseMatrix

Attributes

cols
rows

col_del(k)
Delete the given column of the matrix.
See also:
row_del (page 799)

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix([[0, 0], [0, 1]])
>>> M
Matrix([
[0, 0],
[0, 1]])
>>> M.col_del(0)
>>> M
Matrix([
[0],
[1]])

col_join(other)
Returns B augmented beneath A (row-wise joining):

[A]
[B]

Examples

>>> from sympy import SparseMatrix, Matrix, ones

>>> A = SparseMatrix(ones(3))
>>> A
Matrix([
[1, 1, 1],
[1, 1, 1],
[1, 1, 1]])
>>> B = SparseMatrix.eye(3)
>>> B
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> C = A.col_join(B); C
Matrix([
(continues on next page)

5.18. Matrices 797

SymPy Documentation, Release 1.3

(continued from previous page)

[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> C == A.col_join(Matrix(B))
True

Joining along columns is the same as appending rows at the end of the matrix:

>>> C == A.row_insert(A.rows, Matrix(B))

True

col_op(j, f)
In-place operation on col j using two-arg functor whose args are interpreted as
(self[i, j], i) for i in range(self.rows).

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix.eye(3)*2
>>> M[1, 0] = -1
>>> M.col_op(1, lambda v, i: v + 2*M[i, 0]); M
Matrix([
[ 2, 4, 0],
[-1, 0, 0],
[ 0, 0, 2]])

col_swap(i, j)
Swap, in place, columns i and j.

Examples

>>> from sympy.matrices import SparseMatrix

>>> S = SparseMatrix.eye(3); S[2, 1] = 2
>>> S.col_swap(1, 0); S
Matrix([
[0, 1, 0],
[1, 0, 0],
[2, 0, 1]])

fill(value)
Fill self with the given value.

Notes

Unless many values are going to be deleted (i.e. set to zero) this will create a matrix
that is slower than a dense matrix in operations.

798 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix.zeros(3); M
Matrix([
[0, 0, 0],
[0, 0, 0],
[0, 0, 0]])
>>> M.fill(1); M
Matrix([
[1, 1, 1],
[1, 1, 1],
[1, 1, 1]])

row_del(k)
Delete the given row of the matrix.
See also:
col_del (page 797)

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix([[0, 0], [0, 1]])
>>> M
Matrix([
[0, 0],
[0, 1]])
>>> M.row_del(0)
>>> M
Matrix([[0, 1]])

row_join(other)
Returns B appended after A (column-wise augmenting):
[A B]

Examples

>>> from sympy import SparseMatrix, Matrix

>>> A = SparseMatrix(((1, 0, 1), (0, 1, 0), (1, 1, 0)))
>>> A
Matrix([
[1, 0, 1],
[0, 1, 0],
[1, 1, 0]])
>>> B = SparseMatrix(((1, 0, 0), (0, 1, 0), (0, 0, 1)))
>>> B
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> C = A.row_join(B); C
(continues on next page)

5.18. Matrices 799

SymPy Documentation, Release 1.3

(continued from previous page)

Matrix([
[1, 0, 1, 1, 0, 0],
[0, 1, 0, 0, 1, 0],
[1, 1, 0, 0, 0, 1]])
>>> C == A.row_join(Matrix(B))
True

Joining at row ends is the same as appending columns at the end of the matrix:

>>> C == A.col_insert(A.cols, B)
True

row_op(i, f)
In-place operation on row i using two-arg functor whose args are interpreted as
(self[i, j], j).
See also:
row, zip_row_op (page 800), col_op (page 798)

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix.eye(3)*2
>>> M[0, 1] = -1
>>> M.row_op(1, lambda v, j: v + 2*M[0, j]); M
Matrix([
[2, -1, 0],
[4, 0, 0],
[0, 0, 2]])

row_swap(i, j)
Swap, in place, columns i and j.

Examples

>>> from sympy.matrices import SparseMatrix

>>> S = SparseMatrix.eye(3); S[2, 1] = 2
>>> S.row_swap(1, 0); S
Matrix([
[0, 1, 0],
[1, 0, 0],
[0, 2, 1]])

zip_row_op(i, k, f)
In-place operation on row i using two-arg functor whose args are interpreted as
(self[i, j], self[k, j]).
See also:
row, row_op (page 800), col_op (page 798)

800 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.matrices import SparseMatrix

>>> M = SparseMatrix.eye(3)*2
>>> M[0, 1] = -1
>>> M.zip_row_op(1, 0, lambda v, u: v + 2*u); M
Matrix([
[2, -1, 0],
[4, 0, 0],
[0, 0, 2]])

ImmutableSparseMatrix Class Reference

class sympy.matrices.immutable.ImmutableSparseMatrix
Create an immutable version of a sparse matrix.

Examples

>>> from sympy import eye

>>> from sympy.matrices.immutable import ImmutableSparseMatrix
>>> ImmutableSparseMatrix(1, 1, {})
Matrix([[0]])
>>> ImmutableSparseMatrix(eye(3))
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> _[0, 0] = 42
Traceback (most recent call last):
...
TypeError: Cannot set values of ImmutableSparseMatrix
>>> _.shape
(3, 3)

Attributes

cols
rows

5.18.4 Immutable Matrices

The standard Matrix class in SymPy is mutable. This is important for performance reasons
but means that standard matrices cannot interact well with the rest of SymPy. This is because
the Basic object, from which most SymPy classes inherit, is immutable.
The mission of the ImmutableDenseMatrix class, which is aliased as ImmutableMatrix for
short, is to bridge the tension between performance/mutability and safety/immutability. Im-
mutable matrices can do almost everything that normal matrices can do but they inherit from
Basic and can thus interact more naturally with the rest of SymPy. ImmutableMatrix also

5.18. Matrices 801

SymPy Documentation, Release 1.3

inherits from MatrixExpr, allowing it to interact freely with SymPy’s Matrix Expression mod-
ule.
You can turn any Matrix-like object into an ImmutableMatrix by calling the constructor

>>> from sympy import Matrix, ImmutableMatrix

>>> M = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> M[1, 1] = 0
>>> IM = ImmutableMatrix(M)
>>> IM
Matrix([
[1, 2, 3],
[4, 0, 6],
[7, 8, 9]])
>>> IM[1, 1] = 5
Traceback (most recent call last):
...
TypeError: Can not set values in Immutable Matrix. Use Matrix instead.

ImmutableMatrix Class Reference

class sympy.matrices.immutable.ImmutableDenseMatrix
Create an immutable version of a matrix.

Examples

>>> from sympy import eye

>>> from sympy.matrices import ImmutableMatrix
>>> ImmutableMatrix(eye(3))
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])
>>> _[0, 0] = 42
Traceback (most recent call last):
...
TypeError: Cannot set values of ImmutableDenseMatrix

is_zero
Checks if a matrix is a zero matrix.
A matrix is zero if every element is zero. A matrix need not be square to be consid-
ered zero. The empty matrix is zero by the principle of vacuous truth. For a matrix
that may or may not be zero (e.g. contains a symbol), this will be None

Examples

>>> from sympy import Matrix, zeros

>>> from sympy.abc import x
>>> a = Matrix([[0, 0], [0, 0]])
>>> b = zeros(3, 4)
>>> c = Matrix([[0, 1], [0, 0]])
(continues on next page)

802 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> d = Matrix([])
>>> e = Matrix([[x, 0], [0, 0]])
>>> a.is_zero
True
>>> b.is_zero
True
>>> c.is_zero
False
>>> d.is_zero
True
>>> e.is_zero

5.18.5 Matrix Expressions

The Matrix expression module allows users to write down statements like

>>> from sympy import MatrixSymbol, Matrix

>>> X = MatrixSymbol('X', 3, 3)
>>> Y = MatrixSymbol('Y', 3, 3)
>>> (X.T*X).I*Y
X^-1*X.T^-1*Y

>>> Matrix(X)
Matrix([
[X[0, 0], X[0, 1], X[0, 2]],
[X[1, 0], X[1, 1], X[1, 2]],
[X[2, 0], X[2, 1], X[2, 2]]])

>>> (X*Y)[1, 2]
X[1, 0]*Y[0, 2] + X[1, 1]*Y[1, 2] + X[1, 2]*Y[2, 2]

where X and Y are MatrixSymbol (page 805)’s rather than scalar symbols.

Matrix Expressions Core Reference

class sympy.matrices.expressions.MatrixExpr
Superclass for Matrix Expressions
MatrixExprs represent abstract matrices, linear transformations represented within a
particular basis.

Examples

>>> from sympy import MatrixSymbol

>>> A = MatrixSymbol('A', 3, 3)
>>> y = MatrixSymbol('y', 3, 1)
>>> x = (A.T*A).I * A * y

5.18. Matrices 803

SymPy Documentation, Release 1.3

Attributes

is_Identity

T
Matrix transposition.
as_coeff_Mul(rational=False)
Efficiently extract the coefficient of a product.
as_explicit()
Returns a dense Matrix with elements represented explicitly
Returns an object of type ImmutableDenseMatrix.
See also:

as_mutable (page 804) returns mutable Matrix type

Examples

>>> from sympy import Identity

>>> I = Identity(3)
>>> I
I
>>> I.as_explicit()
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

as_mutable()
Returns a dense, mutable matrix with elements represented explicitly
See also:

as_explicit (page 804) returns ImmutableDenseMatrix

Examples

>>> from sympy import Identity

>>> I = Identity(3)
>>> I
I
>>> I.shape
(3, 3)
>>> I.as_mutable()
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

equals(other)
Test elementwise equality between matrices, potentially of different types

804 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Identity, eye

>>> Identity(3).equals(eye(3))
True

static from_index_summation(expr, first_index=None, last_index=None, dimen-

sions=None)
Parse expression of matrices with explicitly summed indices into a matrix expression
without indices, if possible.
This transformation expressed in mathematical notation:
∑N −1
j=0 Ai,j Bj,k =⇒ A · B

Optional parameter first_index: specify which free index to use as the index start-
ing the expression.

Examples

>>> from sympy import MatrixSymbol, MatrixExpr, Sum, Symbol

>>> from sympy.abc import i, j, k, l, N
>>> A = MatrixSymbol(”A”, N, N)
>>> B = MatrixSymbol(”B”, N, N)
>>> expr = Sum(A[i, j]*B[j, k], (j, 0, N-1))
>>> MatrixExpr.from_index_summation(expr)
A*B

Transposition is detected:

>>> expr = Sum(A[j, i]*B[j, k], (j, 0, N-1))

>>> MatrixExpr.from_index_summation(expr)
A.T*B

Detect the trace:

>>> expr = Sum(A[i, i], (i, 0, N-1))

>>> MatrixExpr.from_index_summation(expr)
Trace(A)

More complicated expressions:

>>> expr = Sum(A[i, j]*B[k, j]*A[l, k], (j, 0, N-1), (k, 0, N-1))
>>> MatrixExpr.from_index_summation(expr)
A*B.T*A.T

class sympy.matrices.expressions.MatrixSymbol
Symbolic representation of a Matrix object
Creates a SymPy Symbol to represent a Matrix. This matrix has a shape and can be
included in Matrix Expressions

>>> from sympy import MatrixSymbol, Identity

>>> A = MatrixSymbol('A', 3, 4) # A 3 by 4 Matrix
>>> B = MatrixSymbol('B', 4, 3) # A 4 by 3 Matrix
>>> A.shape
(3, 4)
>>> 2*A*B + Identity(3)
I + 2*A*B

5.18. Matrices 805

SymPy Documentation, Release 1.3

Attributes

is_Identity

class sympy.matrices.expressions.MatAdd
A Sum of Matrix Expressions
MatAdd inherits from and operates like SymPy Add
>>> from sympy import MatAdd, MatrixSymbol
>>> A = MatrixSymbol('A', 5, 5)
>>> B = MatrixSymbol('B', 5, 5)
>>> C = MatrixSymbol('C', 5, 5)
>>> MatAdd(A, B, C)
A + B + C

Attributes

is_Identity

class sympy.matrices.expressions.MatMul
A product of matrix expressions

Examples

>>> from sympy import MatMul, MatrixSymbol

>>> A = MatrixSymbol('A', 5, 4)
>>> B = MatrixSymbol('B', 4, 3)
>>> C = MatrixSymbol('C', 3, 6)
>>> MatMul(A, B, C)
A*B*C

Attributes

is_Identity

class sympy.matrices.expressions.MatPow

Attributes

is_Identity

class sympy.matrices.expressions.Inverse
The multiplicative inverse of a matrix expression
This is a symbolic object that simply stores its argument without evaluating it. To actually
compute the inverse, use the .inverse() method of matrices.

806 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import MatrixSymbol, Inverse

>>> A = MatrixSymbol('A', 3, 3)
>>> B = MatrixSymbol('B', 3, 3)
>>> Inverse(A)
A^-1
>>> A.inverse() == Inverse(A)
True
>>> (A*B).inverse()
B^-1*A^-1
>>> Inverse(A*B)
(A*B)^-1

Attributes

is_Identity

class sympy.matrices.expressions.Transpose
The transpose of a matrix expression.
This is a symbolic object that simply stores its argument without evaluating it. To actually
compute the transpose, use the transpose() function, or the .T attribute of matrices.

Examples

>>> from sympy.matrices import MatrixSymbol, Transpose

>>> from sympy.functions import transpose
>>> A = MatrixSymbol('A', 3, 5)
>>> B = MatrixSymbol('B', 5, 3)
>>> Transpose(A)
A.T
>>> A.T == transpose(A) == Transpose(A)
True
>>> Transpose(A*B)
(A*B).T
>>> transpose(A*B)
B.T*A.T

Attributes

is_Identity

class sympy.matrices.expressions.Trace
Matrix Trace
Represents the trace of a matrix expression.

5.18. Matrices 807

SymPy Documentation, Release 1.3

>>> from sympy import MatrixSymbol, Trace, eye

>>> A = MatrixSymbol('A', 3, 3)
>>> Trace(A)
Trace(A)

See Also: trace

class sympy.matrices.expressions.FunctionMatrix
Represents a Matrix using a function (Lambda)
This class is an alternative to SparseMatrix

>>> from sympy import FunctionMatrix, symbols, Lambda, MatMul, Matrix

>>> i, j = symbols('i,j')
>>> X = FunctionMatrix(3, 3, Lambda((i, j), i + j))
>>> Matrix(X)
Matrix([
[0, 1, 2],
[1, 2, 3],
[2, 3, 4]])

>>> Y = FunctionMatrix(1000, 1000, Lambda((i, j), i + j))

>>> isinstance(Y*Y, MatMul) # this is an expression object

True

>>> (Y**2)[10,10] # So this is evaluated lazily

342923500

Attributes

is_Identity

class sympy.matrices.expressions.Identity
The Matrix Identity I - multiplicative identity

>>> from sympy.matrices import Identity, MatrixSymbol

>>> A = MatrixSymbol('A', 3, 5)
>>> I = Identity(3)
>>> I*A
A

class sympy.matrices.expressions.ZeroMatrix
The Matrix Zero 0 - additive identity

>>> from sympy import MatrixSymbol, ZeroMatrix

>>> A = MatrixSymbol('A', 3, 5)
>>> Z = ZeroMatrix(3, 5)
>>> A+Z
A
>>> Z*A.T
0

808 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

is_Identity

Block Matrices

Block matrices allow you to construct larger matrices out of smaller sub-blocks. They can
work with MatrixExpr (page 803) or ImmutableMatrix objects.
class sympy.matrices.expressions.blockmatrix.BlockMatrix
A BlockMatrix is a Matrix composed of other smaller, submatrices
The submatrices are stored in a SymPy Matrix object but accessed as part of a Matrix
Expression

>>> from sympy import (MatrixSymbol, BlockMatrix, symbols,

... Identity, ZeroMatrix, block_collapse)
>>> n,m,l = symbols('n m l')
>>> X = MatrixSymbol('X', n, n)
>>> Y = MatrixSymbol('Y', m ,m)
>>> Z = MatrixSymbol('Z', n, m)
>>> B = BlockMatrix([[X, Z], [ZeroMatrix(m,n), Y]])
>>> print(B)
Matrix([
[X, Z],
[0, Y]])

>>> C = BlockMatrix([[Identity(n), Z]])

>>> print(C)
Matrix([[I, Z]])

>>> print(block_collapse(C*B))
Matrix([[X, Z*Y + Z]])

transpose()
Return transpose of matrix.

Examples

>>> from sympy import MatrixSymbol, BlockMatrix, ZeroMatrix

>>> from sympy.abc import l, m, n
>>> X = MatrixSymbol('X', n, n)
>>> Y = MatrixSymbol('Y', m ,m)
>>> Z = MatrixSymbol('Z', n, m)
>>> B = BlockMatrix([[X, Z], [ZeroMatrix(m,n), Y]])
>>> B.transpose()
Matrix([
[X.T, 0],
[Z.T, Y.T]])
>>> _.transpose()
Matrix([
[X, Z],
[0, Y]])

5.18. Matrices 809

SymPy Documentation, Release 1.3

class sympy.matrices.expressions.blockmatrix.BlockDiagMatrix
A BlockDiagMatrix is a BlockMatrix with matrices only along the diagonal

>>> from sympy import MatrixSymbol, BlockDiagMatrix, symbols, Identity

>>> n,m,l = symbols('n m l')
>>> X = MatrixSymbol('X', n, n)
>>> Y = MatrixSymbol('Y', m ,m)
>>> BlockDiagMatrix(X, Y)
Matrix([
[X, 0],
[0, Y]])

sympy.matrices.expressions.blockmatrix.block_collapse(expr)
Evaluates a block matrix expression

>>> from sympy import MatrixSymbol, BlockMatrix, symbols, ␣

,→ Identity, Matrix, ZeroMatrix, block_collapse
>>> n,m,l = symbols('n m l')
>>> X = MatrixSymbol('X', n, n)
>>> Y = MatrixSymbol('Y', m ,m)
>>> Z = MatrixSymbol('Z', n, m)
>>> B = BlockMatrix([[X, Z], [ZeroMatrix(m, n), Y]])
>>> print(B)
Matrix([
[X, Z],
[0, Y]])

>>> C = BlockMatrix([[Identity(n), Z]])

>>> print(C)
Matrix([[I, Z]])

>>> print(block_collapse(C*B))
Matrix([[X, Z*Y + Z]])

5.19 Polynomials Manipulation Module

Computations with polynomials are at the core of computer algebra and having a fast and ro-
bust polynomials manipulation module is a key for building a powerful symbolic manipulation
system. SymPy has a dedicated module sympy.polys for computing in polynomial algebras
over various coefficient domains.
There is a vast number of methods implemented, ranging from simple tools like polynomial
division, to advanced concepts including Gröbner bases and multivariate factorization over
algebraic number domains.

5.19.1 Contents

Basic functionality of the module

810 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Introduction

This tutorial tries to give an overview of the functionality concerning polynomials within
SymPy. All code examples assume:

>>> from sympy import *

>>> x, y, z = symbols('x,y,z')
>>> init_printing(use_unicode=False, wrap_line=False)

Basic concepts

Polynomials

Given a family (xi ) of symbols, or other suitable objects, including numbers, expressions de-
rived from them by repeated addition, subtraction and multiplication are called polynomial
expressions in the generators xi .
By the distributive law it is possible to perform multiplications before additions and subtrac-
tions. The products of generators thus obtained are called monomials. They are usually
written in the form xν11 xν22 · · · xνnn where the exponents νi are nonnegative integers. It is often
convenient to write this briefly as xν where x = (x1 , x2 , . . . , xn ) denotes the family of generators
and ν = (ν1 , ν2 , . . . , νn ) is the family of exponents.
When all monomials having the same exponents are combined, the polynomial expression
becomes a sum of products cν xν , called the terms of the polynomial, where the coefficients cν
are integers. If some of the xi are manifest numbers, they are incorporated in the coefficients
and not regarded as generators. Such coefficients are typically rational, real or complex
numbers. Some symbolic numbers, e.g., pi, can be either coefficients or generators.
A polynomial expression that is a sum of terms with different monomials is uniquely deter-
mined by its family of coefficients (cν ). Such an expression is customarily called a polynomial,
though, more properly, that name does stand for the coefficient family once the generators
are given. SymPy implements polynomials by default as dictionaries with monomials as keys
and coefficients as values. Another implementation consists of nested lists of coefficients.
The set of all polynomials with integer coefficients in the generators xi is a ring, i.e., the
sums, differences and products of its elements are again polynomials in the same generators.
This ring is denoted Z[x1 , x2 , . . . , xn ], or Z[(xi )], and called the ring of polynomials in the xi with
integer coefficients.
More generally, the coefficients of a polynomial can be elements of any commutative ring A,
and the corresponding polynomial ring is then denoted A[x1 , x2 , . . . , xn ]. The ring A can also be
a polynomial ring. In SymPy, the coefficient ring is called the domain of the polynomial ring,
and it can be given as a keyword parameter. By default, it is determined by the coefficients
of the polynomial arguments.
Polynomial expressions can be transformed into polynomials by the method as_poly():

>>> e = (x + y)*(y - 2*z)

>>> e.as_poly()
Poly(x*y - 2*x*z + y**2 - 2*y*z, x, y, z, domain='ZZ')

If a polynomial expression contains numbers that are not integers, they are regarded as co-
efficients and the coefficient ring is extended accordingly. In particular, division by integers
leads to rational coefficients:

5.19. Polynomials Manipulation Module 811

SymPy Documentation, Release 1.3

>>> e = (3*x/2 + y)*(z - 1)

>>> e.as_poly()
Poly(3/2*x*z - 3/2*x + y*z - y, x, y, z, domain='QQ')

Symbolic numbers are considered generators unless they are explicitly excluded, in which
case they are adjoined to the coefficient ring:

>>> e = (x + 2*pi)*y
>>> e.as_poly()
Poly(x*y + 2*y*pi, x, y, pi, domain='ZZ')
>>> e.as_poly(x, y)
Poly(x*y + 2*pi*y, x, y, domain='ZZ[pi]')

Alternatively, the coefficient domain can be specified by means of a keyword argument:

>>> e = (x + 2*pi)*y
>>> e.as_poly(domain=ZZ[pi])
Poly(x*y + 2*pi*y, x, y, domain='ZZ[pi]')

Note that the ring Z[π][x, y] of polynomials in x and y with coefficients in Z[π] is mathematically
equivalent to Z[π, x, y], only their implementations differ.
If an expression contains functions of the generators, other than their positive integer powers,
these are interpreted as new generators:

>>> e = x*sin(y) - y
>>> e.as_poly()
Poly(x*(sin(y)) - y, x, y, sin(y), domain='ZZ')

Since y and sin(y) are algebraically independent they can both appear as generators in a poly-
nomial. However, polynomial expressions must not contain negative powers of generators:

>>> e = x - 1/x
>>> e.as_poly()
Poly(x - (1/x), x, 1/x, domain='ZZ')

It is important to realize that the generators x and 1/x = x−1 are treated as algebraically
independent variables. In particular, their product is not equal to 1. Hence generators in de-
nominators should be avoided even if they raise no error in the current implementation. This
behavior is undesirable and may change in the future.
√ Similar problems emerge with rational
powers of generators. So, for example, x and x = x1/2 are not recognized as algebraically
dependent.
If there are algebraic numbers in an expression, it is possible to adjoin them to the coefficient
ring by setting the keyword extension:

>>> e = x + sqrt(2)
>>> e.as_poly()
Poly(x + (sqrt(2)), x, sqrt(2), domain='ZZ')
>>> e.as_poly(extension=True)
Poly(x + sqrt(2), x, domain='QQ<sqrt(2)>')
√
With the default setting extension=False, both x and 2 are incorrectly √ considered alge-
braically independent variables. With coefficients in the extension field Q( 2) the square root
is treated properly as an algebraic number. Setting extension=True whenever algebraic
numbers are involved is definitely recommended even though it is not forced in the current
implementation.

812 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Divisibility

The fourth rational operation, division, or inverted multiplication, is not generally possible in
rings. If a and b are two elements of a ring A, then there may exist a third element q in A such
that a = bq. In fact, there may exist several such elements.
If also a = bq ′ for some q ′ in A, then b(q − q ′ ) = 0. Hence either b or q − q ′ is zero, or they are
both zero divisors, nonzero elements whose product is zero.

Integral domains

Commutative rings with no zero divisors are called integral domains. Most of the commonly
encountered rings, the ring of integers, fields, and polynomial rings over integral domains
are integral domains.
Assume now that A is an integral domain, and consider the set P of its nonzero elements,
which is closed under multiplication. If a and b are in P , and there exists an element q in P
such that a = bq, then q is unique and called the quotient, a/b, of a by b. Moreover, it is said
that
• a is divisible by b,
• b is a divisor of a,
• a is a multiple of b,
• b is a factor of a.
An element a of P is a divisor of 1 if and only if it is invertible in A, with the inverse a−1 = 1/a.
Such elements are called units. The units of the ring of integers are 1 and −1. The invertible
elements in a polynomial ring over a field are the nonzero constant polynomials.
If two elements of P , a and b, are divisible by each other, then the quotient a/b is invertible with
inverse b/a, or equivalently, b = ua where u is a unit. Such elements are said to be associated
with, or associates of, each other. The associates of an integer n are n and −n. In a polynomial
ring over a field the associates of a polynomial are its constant multiples.
Each element of P is divisible by its associates and the units. An element is irreducible if it
has no other divisors and is not a unit. The irreducible elements in the ring of integers are
the prime numbers p and their opposites −p. In a field, every nonzero element is invertible
and there are no irreducible elements.

Factorial domains

In the ring of integers, each nonzero element can be represented as a product of irreducible
elements and optionally a unit ±1. Moreover, any two such products have the same number of
irreducible factors which are associated with each other in a suitable order. Integral domains
having this property are called factorial, or unique factorization domains. In addition to the
ring of integers, all polynomial rings over a field are factorial, and so are more generally
polynomial rings over any factorial domain. Fields are trivially factorial since there are only
units. The irreducible elements of a factorial domain are usually called primes.
A family of integers has only a finite number of common divisors and the greatest of them is
divisible by all of them. More generally, given a family of nonzero elements (ai ) in an integral
domain, a common divisor d of the elements is called a greatest common divisor, abbreviated
gcd, of the family if it is a multiple of all common divisors. A greatest common divisor, if it

5.19. Polynomials Manipulation Module 813

SymPy Documentation, Release 1.3

exists, is not unique in general; all of its associates have the same property. It is denoted by
d = gcd(a1 , . . . , an ) if there is no danger of confusion. A least common multiple, or lcm, of a
family (ai ) is defined analogously as a common multiple m that divides all common multiples.
It is denoted by m = lcm(a1 , . . . , an ).
In a factorial domain, greatest common divisors always exists. They can be found, at least in
principle, by factoring each element of a family into a product of prime powers and an optional
unit, and, for each prime, taking the least power that appears in the factorizations. The
product of these prime powers is then a greatest common divisor. A least common multiple
can be obtained from the same factorizations as the product of the greatest powers for each
prime.

Euclidean domains

A practical algorithm for computing a greatest common divisor can be implemented in Eu-
clidean domains. They are integral domains that can be endowed with a function w assigning
a nonnegative integer to each nonzero element of the domain and having the following prop-
erty:
if a and b are nonzero, there are q and r that satisfy the division identity
a = qb + r
such that either r = 0 or w(r) < w(b).
The ring of integers and all univariate polynomial rings over fields are Euclidean domains
with w(a) = |a| resp. w(a) = deg(a).
The division identity for integers is implemented in Python as the built-in function divmod()
that can also be applied to SymPy Integers:

>>> divmod(Integer(53), Integer(7))

(7, 4)

For polynomials the division identity is given in SymPy by the function div():

>>> f = 5*x**2 + 10*x + 3

>>> g = 2*x + 2

>>> q, r = div(f, g, domain='QQ')

>>> q
5*x 5
--- + -
2 2
>>> r
-2
>>> (q*g + r).expand()
2
5*x + 10*x + 3

The division identity can be used to determine the divisibility of elements in a Euclidean
domain. If r = 0 in the division identity, then a is divisible by b. Conversely, if a = cb for some
element c, then (c − q)b = r. It follows that c = q and r = 0 if w has the additional property:
if a and b are nonzero, then w(ab) ≥ w(b).
This is satisfied by the functions given above. (And it is always possible to redefine w(a) by
taking the minimum of the values w(xa) for x ̸= 0.)

814 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The principal application of the division identity is the efficient computation of a greatest com-
mon divisor by means of the Euclidean algorithm. It applies to two elements of a Euclidean
domain. A gcd of several elements can be obtained by iteration.
The function for computing the greatest common divisor of integers in SymPy is currently
igcd():

>>> igcd(2, 4)
2
>>> igcd(5, 10, 15)
5

For univariate polynomials over a field the function has its common name gcd(), and the
returned polynomial is monic:

>>> f = 4*x**2 - 1
>>> g = 8*x**3 + 1
>>> gcd(f, g, domain=QQ)
x + 1/2

Divisibility of polynomials

The ring A = Z[x] of univariate polynomials over the ring of integers is not Euclidean but it is
still factorial. To see this, consider the divisibility in A.
Let f and g be two nonzero polynomials in A. If f is divisible by g in A, then it is also divisible
in the ring B = Q[x] of polynomials with rational coefficients. Since B is Euclidean, this can
be determined by means of the division identity.
Assume, conversely, that f = gh for some polynomial h in B. Then f is divisible by g in A if
and only if the coefficients of h are integers. To find out when this is true it is necessary to
consider the divisibility of the coefficients.
For a polynomial f in A, let c be the greatest common divisor of its coefficients. Then f is
divisible by the constant polynomial c in A, and the quotient f /c = p is a polynomial whose
coefficients are integers that have no common divisor apart from the units. Such polynomials
are called primitive. A polynomial with rational coefficients can also be written as f = cp,
where c is a rational number and p is a primitive polynomial. The constant c is called the
content of f , and p is its primitive part. These components can be found by the method
as_content_primitive():

>>> f = 6*x**2 - 3*x + 9

>>> c, p = f.as_content_primitive()
>>> c, p
2
(3, 2*x - x + 3)
>>> f = x**2/3 - x/2 + 1
>>> c, p = f.as_content_primitive()
>>> c, p
2
(1/6, 2*x - 3*x + 6)

Let f , f ′ be polynomials with contents c, c′ and primitive parts p, p′ . Then f f ′ = (cc′ )(pp′ ) where
the product pp′ is primitive by Gauss’s lemma. It follows that
the content of a product of polynomials is the product of their contents and the
primitive part of the product is the product of the primitive parts.

5.19. Polynomials Manipulation Module 815

SymPy Documentation, Release 1.3

Returning to the divisibility in the ring Z[x], assume that f and g are two polynomials with
integer coefficients such that the division identity in Q[x] yields the equality f = gh for some
polynomial h with rational coefficients. Then the content of f is equal to the content of g
multiplied by the content of h. As h has integer coefficients if and only if its content is an
integer, we get the following criterion:
f is divisible by g in the ring Z[x] if and only if
i. f is divisible by g in Q[x], and
ii. the content of f is divisible by the content of g in Z.
If f = cp is irreducible in Z[x], then either c or p must be a unit. If p is not a unit, it must be
irreducible also in Q[x]. For if it is a product of two polynomials, it is also the product of their
primitive parts, and one of them must be a unit. Hence there are two kinds of irreducible
elements in Z[x]:
i. prime numbers of Z, and
ii. primitive polynomials that are irreducible in Q[x].
It follows that each polynomial in Z[x] is a product of irreducible elements. It suffices to factor
its content and primitive part separately. These products are essentially unique; hence Z[x] is
also factorial.
Another important consequence is that a greatest common divisor of two polynomials in Z[x]
can be found efficiently by applying the Euclidean algorithm separately to their contents and
primitive parts in the Euclidean domains Z and Q[x]. This is also implemented in SymPy:
>>> f = 4*x**2 - 1
>>> g = 8*x**3 + 1
>>> gcd(f, g)
2*x + 1
>>> gcd(6*f, 3*g)
6*x + 3

Basic functionality

These functions provide different algorithms dealing with polynomials in the form of SymPy
expression, like symbols, sums etc.

Division

The function div() provides division of polynomials with remainder. That is, for polynomials
f and g, it computes q and r, such that f = g · q + r and deg(r) < q. For polynomials in one
variables with coefficients in a field, say, the rational numbers, q and r are uniquely defined
this way:
>>> f = 5*x**2 + 10*x + 3
>>> g = 2*x + 2

>>> q, r = div(f, g, domain='QQ')

>>> q
5*x 5
--- + -
2 2
(continues on next page)

816 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> r
-2
>>> (q*g + r).expand()
2
5*x + 10*x + 3

As you can see, q has a non-integer coefficient. If you want to do division only in the ring of
polynomials with integer coefficients, you can specify an additional parameter:
>>> q, r = div(f, g, domain='ZZ')
>>> q
0
>>> r
2
5*x + 10*x + 3

But be warned, that this ring is no longer Euclidean and that the degree of the remainder
doesn’t need to be smaller than that of f. Since 2 doesn’t divide 5, 2x doesn’t divide 5x2 , even
if the degree is smaller. But:
>>> g = 5*x + 1

>>> q, r = div(f, g, domain='ZZ')

>>> q
x
>>> r
9*x + 3
>>> (q*g + r).expand()
2
5*x + 10*x + 3

This also works for polynomials with multiple variables:

>>> f = x*y + y*z
>>> g = 3*x + 3*z

>>> q, r = div(f, g, domain='QQ')

>>> q
y
-
3
>>> r
0

In the last examples, all of the three variables x, y and z are assumed to be variables of
the polynomials. But if you have some unrelated constant as coefficient, you can specify the
variables explicitly:
>>> a, b, c = symbols('a,b,c')
>>> f = a*x**2 + b*x + c
>>> g = 3*x + 2
>>> q, r = div(f, g, domain='QQ')
>>> q
a*x 2*a b
--- - --- + -
3 9 3
(continues on next page)

5.19. Polynomials Manipulation Module 817

SymPy Documentation, Release 1.3

(continued from previous page)

>>> r
4*a 2*b
--- - --- + c
9 3

GCD and LCM

With division, there is also the computation of the greatest common divisor and the least
common multiple.
When the polynomials have integer coefficients, the contents’ gcd is also considered:

>>> f = (12*x + 12)*x

>>> g = 16*x**2
>>> gcd(f, g)
4*x

But if the polynomials have rational coefficients, then the returned polynomial is monic:

>>> f = 3*x**2/2
>>> g = 9*x/4
>>> gcd(f, g)
x

It also works with multiple variables. In this case, the variables are ordered alphabetically,
be default, which has influence on the leading coefficient:

>>> f = x*y/2 + y**2

>>> g = 3*x + 6*y

>>> gcd(f, g)
x + 2*y

The lcm is connected with the gcd and one can be computed using the other:

>>> f = x*y**2 + x**2*y

>>> g = x**2*y**2
>>> gcd(f, g)
x*y
>>> lcm(f, g)
3 2 2 3
x *y + x *y
>>> (f*g).expand()
4 3 3 4
x *y + x *y
>>> (gcd(f, g, x, y)*lcm(f, g, x, y)).expand()
4 3 3 4
x *y + x *y

818 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Square-free factorization

The square-free factorization of a univariate polynomial is the product of all factors (not nec-
essarily irreducible) of degree 1, 2 etc.:
>>> f = 2*x**2 + 5*x**3 + 4*x**4 + x**5

>>> sqf_list(f)
(1, [(x + 2, 1), (x, 2), (x + 1, 2)])

>>> sqf(f)
2 2
x *(x + 1) *(x + 2)

Factorization

This function provides factorization of univariate and multivariate polynomials with rational
coefficients:
>>> factor(x**4/2 + 5*x**3/12 - x**2/3)
2
x *(2*x - 1)*(3*x + 4)
----------------------
12

>>> factor(x**2 + 4*x*y + 4*y**2)

2
(x + 2*y)

Groebner bases

Buchberger’s algorithm is implemented, supporting various monomial orders:

>>> groebner([x**2 + 1, y**4*x + x**3], x, y, order='lex')
/[ 2 4 ] \
GroebnerBasis\[x + 1, y - 1], x, y, domain=ZZ, order=lex/

>>> groebner([x**2 + 1, y**4*x + x**3, x*y*z**3], x, y, z, order='grevlex')

/[ 4 3 2 ] \
GroebnerBasis\[y - 1, z , x + 1], x, y, z, domain=ZZ, order=grevlex/

Solving Equations

We have (incomplete) methods to find the complex or even symbolic roots of polynomials and
to solve some systems of polynomial equations:
>>> from sympy import roots, solve_poly_system

>>> solve(x**3 + 2*x + 3, x)

____ ____
(continues on next page)

5.19. Polynomials Manipulation Module 819

SymPy Documentation, Release 1.3

(continued from previous page)

1 \/ 11 *I 1 \/ 11 *I
[-1, - - --------, - + --------]
2 2 2 2

>>> p = Symbol('p')
>>> q = Symbol('q')

>>> solve(x**2 + p*x + q, x)

__________ __________
/ 2 / 2
p \/ p - 4*q p \/ p - 4*q
[- - - -------------, - - + -------------]
2 2 2 2

>>> solve_poly_system([y - x, x - 5], x, y)

[(5, 5)]

>>> solve_poly_system([y**2 - x**3 + 1, y*x], x, y)

___ ___
1 \/ 3 *I 1 \/ 3 *I
[(0, -I), (0, I), (1, 0), (- - - -------, 0), (- - + -------, 0)]
2 2 2 2

Examples from Wester’s Article

Introduction

In this tutorial we present examples from Wester’s article concerning comparison and critique
of mathematical abilities of several computer algebra systems (see [Wester1999]). All the
examples are related to polynomial and algebraic computations and SymPy specific remarks
were added to all of them.

Examples

All examples in this tutorial are computable, so one can just copy and paste them into a Python
shell and do something useful with them. All computations were done using the following
setup:

>>> from sympy import *

>>> init_printing(use_unicode=True, wrap_line=False)

>>> var('x,y,z,s,c,n')
(x, y, z, s, c, n)

Simple univariate polynomial factorization

To obtain a factorization of a polynomial use factor() function. By default factor() returns

the result in unevaluated form, so the content of the input polynomial is left unexpanded, as
in the following example:

820 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> factor(6*x - 10)

2⋅(3⋅x - 5)

To achieve the same effect in a more systematic way use primitive() function, which returns
the content and the primitive part of the input polynomial:

>>> primitive(6*x - 10)

(2, 3⋅x - 5)

Note: The content and the primitive part can be computed only over a ring. To simplify
coefficients of a polynomial over a field use monic().

Univariate GCD, resultant and factorization

Consider univariate polynomials f, g and h over integers:

>>> f = 64*x**34 - 21*x**47 - 126*x**8 - 46*x**5 - 16*x**60 - 81

>>> g = 72*x**60 - 25*x**25 - 19*x**23 - 22*x**39 - 83*x**52 + 54*x**10 + 81
>>> h = 34*x**19 - 25*x**16 + 70*x**7 + 20*x**3 - 91*x - 86

We can compute the greatest common divisor (GCD) of two polynomials using gcd() function:

>>> gcd(f, g)
1

We see that f and g have no common factors. However, f*h and g*h have an obvious factor
h:

>>> gcd(expand(f*h), expand(g*h)) - h

0

The same can be verified using the resultant of univariate polynomials:

>>> resultant(expand(f*h), expand(g*h))

0

Factorization of large univariate polynomials (of degree 120 in this case) over integers is also
possible:

>>> factor(expand(f*g))
⎛ 60 47 34 8 5 ⎞ ⎛ 60 52 39 25 ␣
,→ 23 10 ⎞
-⎝16⋅x + 21⋅x - 64⋅x + 126⋅x + 46⋅x + 81⎠⋅⎝72⋅x - 83⋅x - 22⋅x - 25⋅x -␣
,→19⋅x + 54⋅x + 81⎠

Multivariate GCD and factorization

What can be done in univariate case, can be also done for multivariate polynomials. Consider
the following polynomials f, g and h in Z[x, y, z]:

5.19. Polynomials Manipulation Module 821

SymPy Documentation, Release 1.3

>>> f = 24*x*y**19*z**8 - 47*x**17*y**5*z**8 + 6*x**15*y**9*z**2 - 3*x**22 + 5

>>> g = 34*x**5*y**8*z**13 + 20*x**7*y**7*z**7 + 12*x**9*y**16*z**4 + 80*y**14*z
>>> h = 11*x**12*y**7*z**13 - 23*x**2*y**8*z**10 + 47*x**17*y**5*z**8

As previously, we can verify that f and g have no common factors:

>>> gcd(f, g)
1

However, f*h and g*h have an obvious factor h:

>>> gcd(expand(f*h), expand(g*h)) - h

0

Multivariate factorization of large polynomials is also possible:

>>> factor(expand(f*g))
7 ⎛ 9 9 3 7 6 5 12 7⎞ ⎛ 22 17 5 8 15 ␣
,→9 2 19 8 ⎞
-2⋅y ⋅z⋅⎝6⋅x ⋅y ⋅z + 10⋅x ⋅z + 17⋅x ⋅y⋅z + 40⋅y ⎠⋅⎝3⋅x + 47⋅x ⋅y ⋅z - 6⋅x ⋅y␣
,→⋅z - 24⋅x⋅y ⋅z - 5⎠

Support for symbols in exponents

Polynomial manipulation functions provided by sympy.polys are mostly used with integer
exponents. However, it’s perfectly valid to compute with symbolic exponents, e.g.:

>>> gcd(2*x**(n + 4) - x**(n + 2), 4*x**(n + 1) + 3*x**n)

n
x

Testing if polynomials have common zeros

To test if two polynomials have a root in common we can use resultant() function. The
theory says that the resultant of two polynomials vanishes if there is a common zero of those
polynomials. For example:

>>> resultant(3*x**4 + 3*x**3 + x**2 - x - 2, x**3 - 3*x**2 + x + 5)

0

We can visualize this fact by factoring the polynomials:

>>> factor(3*x**4 + 3*x**3 + x**2 - x - 2)

⎛ 3 ⎞
(x + 1)⋅⎝3⋅x + x - 2⎠

>>> factor(x**3 - 3*x**2 + x + 5)

⎛ 2 ⎞
(x + 1)⋅⎝x - 4⋅x + 5⎠

In both cases we obtained the factor x + 1 which tells us that the common root is x = −1.

822 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Normalizing simple rational functions

To remove common factors from the numerator and the denominator of a rational function
the elegant way, use cancel() function. For example:

>>> cancel((x**2 - 4)/(x**2 + 4*x + 4))

x - 2
─────
x + 2

Expanding expressions and factoring back

One can work easily we expressions in both expanded and factored forms. Consider a poly-
nomial f in expanded form. We differentiate it and factor the result back:

>>> f = expand((x + 1)**20)

>>> g = diff(f, x)

>>> factor(g)
19
20⋅(x + 1)

The same can be achieved in factored form:

>>> diff((x + 1)**20, x)

19
20⋅(x + 1)

Factoring in terms of cyclotomic polynomials

SymPy can very efficiently decompose polynomials of the form xn ± 1 in terms of cyclotomic
polynomials:

>>> factor(x**15 - 1)
⎛ 2 ⎞ ⎛ 4 3 2 ⎞ ⎛ 8 7 5 4 3 ⎞
(x - 1)⋅⎝x + x + 1⎠⋅⎝x + x + x + x + 1⎠⋅⎝x - x + x - x + x - x + 1⎠

The original Wester‘s example was x100 − 1, but was truncated for readability purpose. Note
that this is not a big struggle for factor() to decompose polynomials of degree 1000 or
greater.

Univariate factoring over Gaussian numbers

Consider a univariate polynomial f with integer coefficients:

>>> f = 4*x**4 + 8*x**3 + 77*x**2 + 18*x + 153

We want to obtain a factorization of f over Gaussian numbers. To do this we use factor() as

previously, but this time we set gaussian keyword to True:

5.19. Polynomials Manipulation Module 823

SymPy Documentation, Release 1.3

>>> factor(f, gaussian=True)

⎛ 3⋅i⎞ ⎛ 3⋅i⎞
4⋅⎜x - ───⎟⋅⎜x + ───⎟⋅(x + 1 - 4⋅i)⋅(x + 1 + 4⋅i)
⎝ 2 ⎠ ⎝ 2 ⎠

As the result we got a splitting factorization of f with monic factors (this is a general rule
when computing in a field with SymPy). The gaussian keyword is useful for improving code
readability, however the same result can be computed using more general syntax:

>>> factor(f, extension=I)

⎛ 3⋅i⎞ ⎛ 3⋅i⎞
4⋅⎜x - ───⎟⋅⎜x + ───⎟⋅(x + 1 - 4⋅i)⋅(x + 1 + 4⋅i)
⎝ 2 ⎠ ⎝ 2 ⎠

Computing with automatic field extensions

Consider two univariate polynomials f and g:

>>> f = x**3 + (sqrt(2) - 2)*x**2 - (2*sqrt(2) + 3)*x - 3*sqrt(2)

>>> g = x**2 - 2

We would like to reduce degrees of the numerator and the denominator of a rational function
f/g. To do this we employ cancel() function:

>>> cancel(f/g)
3 2 2
x - 2⋅x + √2⋅x - 3⋅x - 2⋅√2⋅x - 3⋅√2
───────────────────────────────────────
2
x - 2
√
Unfortunately nothing interesting happened. This is because by default SymPy treats 2 as a
generator, obtaining a bivariate
√ polynomial for the numerator. To make cancel() recognize
algebraic properties of 2, one needs to use extension keyword:

>>> cancel(f/g, extension=True)

2
x - 2⋅x - 3
────────────
x - √2

Setting extension=True tells cancel() to find minimal algebraic

√ number domain for the co-
efficients of f/g. The automatically inferred domain is Q( 2). If one doesn’t want to rely on
automatic inference, the same result can be obtained by setting the extension keyword with
an explicit algebraic number:

>>> cancel(f/g, extension=sqrt(2))

2
x - 2⋅x - 3
────────────
x - √2

824 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Univariate factoring over various domains

Consider a univariate polynomial f with integer coefficients:

>>> f = x**4 - 3*x**2 + 1

With sympy.polys we can obtain factorizations of f over different domains, which includes:
• rationals:
>>> factor(f)
⎛ 2 ⎞ ⎛ 2 ⎞
⎝x - x - 1⎠⋅⎝x + x - 1⎠

• finite fields:
>>> factor(f, modulus=5)
2 2
(x - 2) ⋅(x + 2)

• algebraic numbers:
>>> alg = AlgebraicNumber((sqrt(5) - 1)/2, alias='alpha')

>>> factor(f, extension=alg)

(x - α)⋅(x + α)⋅(x - 1 - α)⋅(x + α + 1)

Factoring polynomials into linear factors

Currently SymPy can factor polynomials into irreducibles over various domains, which can re-
sult in a splitting factorization (into linear factors). However, there is currently no systematic
way to infer a splitting field (algebraic number field) automatically. In future the following
syntax will be implemented:
>>> factor(x**3 + x**2 - 7, split=True)
Traceback (most recent call last):
...
NotImplementedError: 'split' option is not implemented yet

Note this is different from extension=True, because the later only tells how expression pars-
ing should be done, not what should be the domain of computation. One can simulate the
split keyword for several classes of polynomials using solve() function.

Advanced factoring over finite fields

Consider a univariate polynomial f with integer coefficients:

>>> f = x**11 + x + 1

We can factor f over a large finite field F65537 :

>>> factor(f, modulus=65537)
⎛ 2 ⎞ ⎛ 9 8 6 5 3 2 ⎞
⎝x + x + 1⎠⋅⎝x - x + x - x + x - x + 1⎠

5.19. Polynomials Manipulation Module 825

SymPy Documentation, Release 1.3

and expand the resulting factorization back:

>>> expand(_)
11
x + x + 1

obtaining polynomial f. This was done using symmetric polynomial representation over finite
fields The same thing can be done using non-symmetric representation:

>>> factor(f, modulus=65537, symmetric=False)

⎛ 2 ⎞ ⎛ 9 8 6 5 3 2 ⎞
⎝x + x + 1⎠⋅⎝x + 65536⋅x + x + 65536⋅x + x + 65536⋅x + 1⎠

As with symmetric representation we can expand the factorization to get the input polynomial
back. This time, however, we need to truncate coefficients of the expanded polynomial modulo
65537:

>>> trunc(expand(_), 65537)

11
x + x + 1

Working with expressions as polynomials

Consider a multivariate polynomial f in Z[x, y, z]:

>>> f = expand((x - 2*y**2 + 3*z**3)**20)

We want to compute factorization of f. To do this we use factor as usually, however we

note that the polynomial in consideration is already in expanded form, so we can tell the
factorization routine to skip expanding f:

>>> factor(f, expand=False)

20
⎛ 2 3⎞
⎝x - 2⋅y + 3⋅z ⎠

The default in sympy.polys is to expand all expressions given as arguments to polynomial

manipulation functions and Poly class. If we know that expanding is unnecessary, then by
setting expand=False we can save quite a lot of time for complicated inputs. This can be
really important when computing with expressions like:

>>> g = expand((sin(x) - 2*cos(y)**2 + 3*tan(z)**3)**20)

>>> factor(g, expand=False)

20
⎛ 2 3 ⎞
⎝-sin(x) + 2⋅cos (y) - 3⋅tan (z)⎠

Computing reduced Gröbner bases

To compute a reduced Gröbner basis for a set of polynomials use groebner() function. The
function accepts various monomial orderings, e.g.: lex, grlex and grevlex, or a user de-
fined one, via order keyword. The lex ordering is the most interesting because it has elim-

826 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ination property, which means that if the system of polynomial equations to groebner() is
zero-dimensional (has finite number of solutions) the last element of the basis is a univariate
polynomial. Consider the following example:

>>> f = expand((1 - c**2)**5 * (1 - s**2)**5 * (c**2 + s**2)**10)

>>> groebner([f, c**2 + s**2 - 1])

⎛⎡ 2 2 20 18 16 14 12 10⎤ ␣
,→ ⎞
GroebnerBasis⎝⎣c + s - 1, c - 5⋅c + 10⋅c - 10⋅c + 5⋅c - c ⎦, s, c,␣
,→domain=ℤ, order=lex⎠

The result is an ordinary Python list, so we can easily apply a function to all its elements, for
example we can factor those elements:

>>> list(map(factor, _))

⎡ 2 2 10 5 5⎤
⎣c + s - 1, c ⋅(c - 1) ⋅(c + 1) ⎦

From the above we can easily find all solutions of the system of polynomial equations. Or we
can use solve() to achieve this in a more systematic way:

>>> solve([f, s**2 + c**2 - 1], c, s)

[(-1, 0), (0, -1), (0, 1), (1, 0)]

Multivariate factoring over algebraic numbers

Computing with multivariate polynomials over various domains √ is as simple as in univariate

case. For example consider the following factorization over Q( −3):

>>> factor(x**3 + y**3, extension=sqrt(-3))

⎛ ⎛ 1 √3⋅i⎞⎞ ⎛ ⎛ 1 √3⋅i⎞⎞
(x + y)⋅⎜x + y⋅⎜- ─ - ────⎟⎟⋅⎜x + y⋅⎜- ─ + ────⎟⎟
⎝ ⎝ 2 2 ⎠⎠ ⎝ ⎝ 2 2 ⎠⎠

Note: Currently multivariate polynomials over finite fields aren’t supported.

Partial fraction decomposition

Consider a univariate rational function f with integer coefficients:

>>> f = (x**2 + 2*x + 3)/(x**3 + 4*x**2 + 5*x + 2)

To decompose f into partial fractions use apart() function:

>>> apart(f)
3 2 2
───── - ───── + ────────
x + 2 x + 1 2
(x + 1)

5.19. Polynomials Manipulation Module 827

SymPy Documentation, Release 1.3

To return from partial fractions to the rational function use a composition of together() and
cancel():

>>> cancel(together(_))
2
x + 2⋅x + 3
───────────────────
3 2
x + 4⋅x + 5⋅x + 2

Literature

Polynomials Manipulation Module Reference

Basic polynomial manipulation functions

sympy.polys.polytools.poly(expr, *gens, **args)

Efficiently transform an expression into a polynomial.

Examples

>>> from sympy import poly

>>> from sympy.abc import x

>>> poly(x*(x**2 + x - 1)**2)

Poly(x**5 + 2*x**4 - x**3 - 2*x**2 + x, x, domain='ZZ')

sympy.polys.polytools.poly_from_expr(expr, *gens, **args)

Construct a polynomial from an expression.
sympy.polys.polytools.parallel_poly_from_expr(exprs, *gens, **args)
Construct polynomials from expressions.
sympy.polys.polytools.degree(f, gen=0)
Return the degree of f in the given variable.
The degree of 0 is negative infinity.
See also:
total_degree, degree_list (page 829)

Examples

>>> from sympy import degree

>>> from sympy.abc import x, y

>>> degree(x**2 + y*x + 1, gen=x)

2
>>> degree(x**2 + y*x + 1, gen=y)
1
(continues on next page)

828 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> degree(0, x)
-oo

sympy.polys.polytools.degree_list(f, *gens, **args)

Return a list of degrees of f in all variables.

Examples

>>> from sympy import degree_list

>>> from sympy.abc import x, y

>>> degree_list(x**2 + y*x + 1)

(2, 1)

sympy.polys.polytools.LC(f, *gens, **args)

Return the leading coefficient of f.

Examples

>>> from sympy import LC

>>> from sympy.abc import x, y

>>> LC(4*x**2 + 2*x*y**2 + x*y + 3*y)

4

sympy.polys.polytools.LM(f, *gens, **args)

Return the leading monomial of f.

Examples

>>> from sympy import LM

>>> from sympy.abc import x, y

>>> LM(4*x**2 + 2*x*y**2 + x*y + 3*y)

x**2

sympy.polys.polytools.LT(f, *gens, **args)

Return the leading term of f.

Examples

>>> from sympy import LT

>>> from sympy.abc import x, y

>>> LT(4*x**2 + 2*x*y**2 + x*y + 3*y)

4*x**2

5.19. Polynomials Manipulation Module 829

SymPy Documentation, Release 1.3

sympy.polys.polytools.pdiv(f, g, *gens, **args)

Compute polynomial pseudo-division of f and g.

Examples

>>> from sympy import pdiv

>>> from sympy.abc import x

>>> pdiv(x**2 + 1, 2*x - 4)

(2*x + 4, 20)

sympy.polys.polytools.prem(f, g, *gens, **args)

Compute polynomial pseudo-remainder of f and g.

Examples

>>> from sympy import prem

>>> from sympy.abc import x

>>> prem(x**2 + 1, 2*x - 4)

20

sympy.polys.polytools.pquo(f, g, *gens, **args)

Compute polynomial pseudo-quotient of f and g.

Examples

>>> from sympy import pquo

>>> from sympy.abc import x

>>> pquo(x**2 + 1, 2*x - 4)

2*x + 4
>>> pquo(x**2 - 1, 2*x - 1)
2*x + 1

sympy.polys.polytools.pexquo(f, g, *gens, **args)

Compute polynomial exact pseudo-quotient of f and g.

Examples

>>> from sympy import pexquo

>>> from sympy.abc import x

>>> pexquo(x**2 - 1, 2*x - 2)

2*x + 2

830 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> pexquo(x**2 + 1, 2*x - 4)

Traceback (most recent call last):
...
ExactQuotientFailed: 2*x - 4 does not divide x**2 + 1

sympy.polys.polytools.div(f, g, *gens, **args)

Compute polynomial division of f and g.

Examples

>>> from sympy import div, ZZ, QQ

>>> from sympy.abc import x

>>> div(x**2 + 1, 2*x - 4, domain=ZZ)

(0, x**2 + 1)
>>> div(x**2 + 1, 2*x - 4, domain=QQ)
(x/2 + 1, 5)

sympy.polys.polytools.rem(f, g, *gens, **args)

Compute polynomial remainder of f and g.

Examples

>>> from sympy import rem, ZZ, QQ

>>> from sympy.abc import x

>>> rem(x**2 + 1, 2*x - 4, domain=ZZ)

x**2 + 1
>>> rem(x**2 + 1, 2*x - 4, domain=QQ)
5

sympy.polys.polytools.quo(f, g, *gens, **args)

Compute polynomial quotient of f and g.

Examples

>>> from sympy import quo

>>> from sympy.abc import x

>>> quo(x**2 + 1, 2*x - 4)

x/2 + 1
>>> quo(x**2 - 1, x - 1)
x + 1

sympy.polys.polytools.exquo(f, g, *gens, **args)

Compute polynomial exact quotient of f and g.

5.19. Polynomials Manipulation Module 831

SymPy Documentation, Release 1.3

Examples

>>> from sympy import exquo

>>> from sympy.abc import x

>>> exquo(x**2 - 1, x - 1)
x + 1

>>> exquo(x**2 + 1, 2*x - 4)

Traceback (most recent call last):
...
ExactQuotientFailed: 2*x - 4 does not divide x**2 + 1

sympy.polys.polytools.half_gcdex(f, g, *gens, **args)

Half extended Euclidean algorithm of f and g.
Returns (s, h) such that h = gcd(f, g) and s*f = h (mod g).

Examples

>>> from sympy import half_gcdex

>>> from sympy.abc import x

>>> half_gcdex(x**4 - 2*x**3 - 6*x**2 + 12*x + 15, x**3 + x**2 - 4*x - 4)

(-x/5 + 3/5, x + 1)

sympy.polys.polytools.gcdex(f, g, *gens, **args)

Extended Euclidean algorithm of f and g.
Returns (s, t, h) such that h = gcd(f, g) and s*f + t*g = h.

Examples

>>> from sympy import gcdex

>>> from sympy.abc import x

>>> gcdex(x**4 - 2*x**3 - 6*x**2 + 12*x + 15, x**3 + x**2 - 4*x - 4)

(-x/5 + 3/5, x**2/5 - 6*x/5 + 2, x + 1)

sympy.polys.polytools.invert(f, g, *gens, **args)

Invert f modulo g when possible.
See also:
sympy.core.numbers.mod_inverse

Examples

>>> from sympy import invert, S

>>> from sympy.core.numbers import mod_inverse
>>> from sympy.abc import x

832 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> invert(x**2 - 1, 2*x - 1)

-4/3

>>> invert(x**2 - 1, x - 1)
Traceback (most recent call last):
...
NotInvertible: zero divisor

For more efficient inversion of Rationals, use the mod_inverse function:

>>> mod_inverse(3, 5)
2
>>> (S(2)/5).invert(S(7)/3)
5/2

sympy.polys.polytools.subresultants(f, g, *gens, **args)

Compute subresultant PRS of f and g.

Examples

>>> from sympy import subresultants

>>> from sympy.abc import x

>>> subresultants(x**2 + 1, x**2 - 1)

[x**2 + 1, x**2 - 1, -2]

sympy.polys.polytools.resultant(f, g, *gens, **args)

Compute resultant of f and g.

Examples

>>> from sympy import resultant

>>> from sympy.abc import x

>>> resultant(x**2 + 1, x**2 - 1)

4

sympy.polys.polytools.discriminant(f, *gens, **args)

Compute discriminant of f.

Examples

>>> from sympy import discriminant

>>> from sympy.abc import x

>>> discriminant(x**2 + 2*x + 3)

-8

sympy.polys.dispersion.dispersion(p, q=None, *gens, **args)

Compute the dispersion of polynomials.

5.19. Polynomials Manipulation Module 833

SymPy Documentation, Release 1.3

For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion dis(f, g) is
defined as:
dis(f, g) := max{J(f, g) ∪ {0}}
= max{{a ∈ N| gcd(f (x), g(x + a)) ̸= 1} ∪ {0}}

and for a single polynomial dis(f ) := dis(f, f ). Note that we make the definition max{} :=
−∞.
See also:
dispersionset (page 835)

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)

>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

Note that the definition of the dispersion is not symmetric:

>>> fp = poly(x**4 - 3*x**2 + 1, x)

>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

The maximum of an empty set is defined to be −∞ as seen in this example.

Computing the dispersion also works over field extensions:

834 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 + 2*a)*x, x)
>>> sorted(dispersionset(fp))
[0, 1]

sympy.polys.dispersion.dispersionset(p, q=None, *gens, **args)

Compute the dispersion set of two polynomials.
For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion set J(f, g) is
defined as:
J(f, g) := {a ∈ N0 | gcd(f (x), g(x + a)) ̸= 1}
= {a ∈ N0 | deg gcd(f (x), g(x + a)) ≥ 1}

For a single polynomial one defines J(f ) := J(f, f ).

See also:
dispersion (page 833)

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)

>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

5.19. Polynomials Manipulation Module 835

SymPy Documentation, Release 1.3

Note that the definition of the dispersion is not symmetric:

>>> fp = poly(x**4 - 3*x**2 + 1, x)

>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

Computing the dispersion also works over field extensions:

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 + 2*a)*x, x)
>>> sorted(dispersionset(fp))
[0, 1]

sympy.polys.polytools.terms_gcd(f, *gens, **args)

Remove GCD of terms from f.
If the deep flag is True, then the arguments of f will have terms_gcd applied to them.
If a fraction is factored out of f and f is an Add, then an unevaluated Mul will be returned
so that automatic simplification does not redistribute it. The hint clear, when set to
False, can be used to prevent such factoring when all coefficients are not fractions.
See also:
sympy.core.exprtools.gcd_terms (page 206), sympy.core.exprtools.factor_terms
(page 207)

Examples

>>> from sympy import terms_gcd, cos

>>> from sympy.abc import x, y
>>> terms_gcd(x**6*y**2 + x**3*y, x, y)
x**3*y*(x**3*y + 1)

The default action of polys routines is to expand the expression given to them. terms_gcd
follows this behavior:

>>> terms_gcd((3+3*x)*(x+x*y))
3*x*(x*y + x + y + 1)

836 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If this is not desired then the hint expand can be set to False. In this case the expression
will be treated as though it were comprised of one or more terms:

>>> terms_gcd((3+3*x)*(x+x*y), expand=False)

(3*x + 3)*(x*y + x)

In order to traverse factors of a Mul or the arguments of other functions, the deep hint
can be used:

>>> terms_gcd((3 + 3*x)*(x + x*y), expand=False, deep=True)

3*x*(x + 1)*(y + 1)
>>> terms_gcd(cos(x + x*y), deep=True)
cos(x*(y + 1))

Rationals are factored out by default:

>>> terms_gcd(x + y/2)

(2*x + y)/2

Only the y-term had a coefficient that was a fraction; if one does not want to factor out
the 1/2 in cases like this, the flag clear can be set to False:

>>> terms_gcd(x + y/2, clear=False)

x + y/2
>>> terms_gcd(x*y/2 + y**2, clear=False)
y*(x/2 + y)

The clear flag is ignored if all coefficients are fractions:

>>> terms_gcd(x/3 + y/2, clear=False)

(2*x + 3*y)/6

sympy.polys.polytools.cofactors(f, g, *gens, **args)

Compute GCD and cofactors of f and g.
Returns polynomials (h, cff, cfg) such that h = gcd(f, g), and cff = quo(f, h)
and cfg = quo(g, h) are, so called, cofactors of f and g.

Examples

>>> from sympy import cofactors

>>> from sympy.abc import x

>>> cofactors(x**2 - 1, x**2 - 3*x + 2)

(x - 1, x + 1, x - 2)

sympy.polys.polytools.gcd(f, g=None, *gens, **args)

Compute GCD of f and g.

Examples

>>> from sympy import gcd

>>> from sympy.abc import x

5.19. Polynomials Manipulation Module 837

SymPy Documentation, Release 1.3

>>> gcd(x**2 - 1, x**2 - 3*x + 2)

x - 1

sympy.polys.polytools.gcd_list(seq, *gens, **args)

Compute GCD of a list of polynomials.

Examples

>>> from sympy import gcd_list

>>> from sympy.abc import x

>>> gcd_list([x**3 - 1, x**2 - 1, x**2 - 3*x + 2])

x - 1

sympy.polys.polytools.lcm(f, g=None, *gens, **args)

Compute LCM of f and g.

Examples

>>> from sympy import lcm

>>> from sympy.abc import x

>>> lcm(x**2 - 1, x**2 - 3*x + 2)

x**3 - 2*x**2 - x + 2

sympy.polys.polytools.lcm_list(seq, *gens, **args)

Compute LCM of a list of polynomials.

Examples

>>> from sympy import lcm_list

>>> from sympy.abc import x

>>> lcm_list([x**3 - 1, x**2 - 1, x**2 - 3*x + 2])

x**5 - x**4 - 2*x**3 - x**2 + x + 2

sympy.polys.polytools.trunc(f, p, *gens, **args)

Reduce f modulo a constant p.

Examples

>>> from sympy import trunc

>>> from sympy.abc import x

>>> trunc(2*x**3 + 3*x**2 + 5*x + 7, 3)

-x**3 - x + 1

sympy.polys.polytools.monic(f, *gens, **args)

Divide all coefficients of f by LC(f).

838 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import monic

>>> from sympy.abc import x

>>> monic(3*x**2 + 4*x + 2)

x**2 + 4*x/3 + 2/3

sympy.polys.polytools.content(f, *gens, **args)

Compute GCD of coefficients of f.

Examples

>>> from sympy import content

>>> from sympy.abc import x

>>> content(6*x**2 + 8*x + 12)

2

sympy.polys.polytools.primitive(f, *gens, **args)

Compute content and the primitive form of f.

Examples

>>> from sympy.polys.polytools import primitive

>>> from sympy.abc import x

>>> primitive(6*x**2 + 8*x + 12)

(2, 3*x**2 + 4*x + 6)

>>> eq = (2 + 2*x)*x + 2

Expansion is performed by default:

>>> primitive(eq)
(2, x**2 + x + 1)

Set expand to False to shut this off. Note that the extraction will not be recursive; use
the as_content_primitive method for recursive, non-destructive Rational extraction.

>>> primitive(eq, expand=False)

(1, x*(2*x + 2) + 2)

>>> eq.as_content_primitive()
(2, x*(x + 1) + 1)

sympy.polys.polytools.compose(f, g, *gens, **args)

Compute functional composition f(g).

5.19. Polynomials Manipulation Module 839

SymPy Documentation, Release 1.3

Examples

>>> from sympy import compose

>>> from sympy.abc import x

>>> compose(x**2 + x, x - 1)
x**2 - x

sympy.polys.polytools.decompose(f, *gens, **args)

Compute functional decomposition of f.

Examples

>>> from sympy import decompose

>>> from sympy.abc import x

>>> decompose(x**4 + 2*x**3 - x - 1)

[x**2 - x - 1, x**2 + x]

sympy.polys.polytools.sturm(f, *gens, **args)

Compute Sturm sequence of f.

Examples

>>> from sympy import sturm

>>> from sympy.abc import x

>>> sturm(x**3 - 2*x**2 + x - 3)

[x**3 - 2*x**2 + x - 3, 3*x**2 - 4*x + 1, 2*x/9 + 25/9, -2079/4]

sympy.polys.polytools.gff_list(f, *gens, **args)

Compute a list of greatest factorial factors of f.
Note that the input to ff() and rf() should be Poly instances to use the definitions here.

Examples

>>> from sympy import gff_list, ff, Poly

>>> from sympy.abc import x

>>> f = Poly(x**5 + 2*x**4 - x**3 - 2*x**2, x)

>>> gff_list(f)
[(Poly(x, x, domain='ZZ'), 1), (Poly(x + 2, x, domain='ZZ'), 4)]

>>> (ff(Poly(x), 1)*ff(Poly(x + 2), 4)).expand() == f

True

840 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> f = Poly(x**12 + 6*x**11 - 11*x**10 - 56*x**9 + 220*x**8 + 208*x**7 - ␣

,→1401*x**6 + 1090*x**5 + 2715*x**4 - 6720*x**3 - 1092*x**2 + 5040*x, x)

>>> gff_list(f)
[(Poly(x**3 + 7, x, domain='ZZ'), 2), (Poly(x**2 + 5*x, x, domain='ZZ'), 3)]

>>> ff(Poly(x**3 + 7, x), 2)*ff(Poly(x**2 + 5*x, x), 3) == f

True

sympy.polys.polytools.gff(f, *gens, **args)

Compute greatest factorial factorization of f.
sympy.polys.polytools.sqf_norm(f, *gens, **args)
Compute square-free norm of f.
Returns s, f, r, such that g(x) = f(x-sa) and r(x) = Norm(g(x)) is a square-free poly-
nomial over K, where a is the algebraic extension of the ground domain.

Examples

>>> from sympy import sqf_norm, sqrt

>>> from sympy.abc import x

>>> sqf_norm(x**2 + 1, extension=[sqrt(3)])

(1, x**2 - 2*sqrt(3)*x + 4, x**4 - 4*x**2 + 16)

sympy.polys.polytools.sqf_part(f, *gens, **args)

Compute square-free part of f.

Examples

>>> from sympy import sqf_part

>>> from sympy.abc import x

>>> sqf_part(x**3 - 3*x - 2)

x**2 - x - 2

sympy.polys.polytools.sqf_list(f, *gens, **args)

Compute a list of square-free factors of f.

Examples

>>> from sympy import sqf_list

>>> from sympy.abc import x

>>> sqf_list(2*x**5 + 16*x**4 + 50*x**3 + 76*x**2 + 56*x + 16)

(2, [(x + 1, 2), (x + 2, 3)])

sympy.polys.polytools.sqf(f, *gens, **args)

Compute square-free factorization of f.

5.19. Polynomials Manipulation Module 841

SymPy Documentation, Release 1.3

Examples

>>> from sympy import sqf

>>> from sympy.abc import x

>>> sqf(2*x**5 + 16*x**4 + 50*x**3 + 76*x**2 + 56*x + 16)

2*(x + 1)**2*(x + 2)**3

sympy.polys.polytools.factor_list(f, *gens, **args)

Compute a list of irreducible factors of f.

Examples

>>> from sympy import factor_list

>>> from sympy.abc import x, y

>>> factor_list(2*x**5 + 2*x**4*y + 4*x**3 + 4*x**2*y + 2*x + 2*y)

(2, [(x + y, 1), (x**2 + 1, 2)])

sympy.polys.polytools.factor(f, *gens, **args)

Compute the factorization of expression, f, into irreducibles. (To factor an integer into
primes, use factorint.)
There two modes implemented: symbolic and formal. If f is not an instance of Poly
(page 847) and generators are not specified, then the former mode is used. Otherwise,
the formal mode is used.
In symbolic mode, factor() (page 842) will traverse the expression tree and factor its
components without any prior expansion, unless an instance of Add is encountered (in
this case formal factorization is used). This way factor() (page 842) can handle large
or symbolic exponents.
By default, the factorization is computed over the rationals. To factor over other domain,
e.g. an algebraic or finite field, use appropriate options: extension, modulus or domain.
See also:
sympy.ntheory.factor_.factorint (page 319)

Examples

>>> from sympy import factor, sqrt

>>> from sympy.abc import x, y

>>> factor(2*x**5 + 2*x**4*y + 4*x**3 + 4*x**2*y + 2*x + 2*y)

2*(x + y)*(x**2 + 1)**2

>>> factor(x**2 + 1)
x**2 + 1
>>> factor(x**2 + 1, modulus=2)
(x + 1)**2
>>> factor(x**2 + 1, gaussian=True)
(x - I)*(x + I)

842 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> factor(x**2 - 2, extension=sqrt(2))

(x - sqrt(2))*(x + sqrt(2))

>>> factor((x**2 - 1)/(x**2 + 4*x + 4))

(x - 1)*(x + 1)/(x + 2)**2
>>> factor((x**2 + 4*x + 4)**10000000*(x**2 + 1))
(x + 2)**20000000*(x**2 + 1)

By default, factor deals with an expression as a whole:

>>> eq = 2**(x**2 + 2*x + 1)

>>> factor(eq)
2**(x**2 + 2*x + 1)

If the deep flag is True then subexpressions will be factored:

>>> factor(eq, deep=True)

2**((x + 1)**2)

sympy.polys.polytools.intervals(F, all=False, eps=None, inf=None, sup=None,

strict=False, fast=False, sqf=False)
Compute isolating intervals for roots of f.

Examples

>>> from sympy import intervals

>>> from sympy.abc import x

>>> intervals(x**2 - 3)
[((-2, -1), 1), ((1, 2), 1)]
>>> intervals(x**2 - 3, eps=1e-2)
[((-26/15, -19/11), 1), ((19/11, 26/15), 1)]

sympy.polys.polytools.refine_root(f, s, t, eps=None, steps=None, fast=False,

check_sqf=False)
Refine an isolating interval of a root to the given precision.

Examples

>>> from sympy import refine_root

>>> from sympy.abc import x

>>> refine_root(x**2 - 3, 1, 2, eps=1e-2)

(19/11, 26/15)

sympy.polys.polytools.count_roots(f, inf=None, sup=None)

Return the number of roots of f in [inf, sup] interval.
If one of inf or sup is complex, it will return the number of roots in the complex rectangle
with corners at inf and sup.

5.19. Polynomials Manipulation Module 843

SymPy Documentation, Release 1.3

Examples

>>> from sympy import count_roots, I

>>> from sympy.abc import x

>>> count_roots(x**4 - 4, -3, 3)

2
>>> count_roots(x**4 - 4, 0, 1 + 3*I)
1

sympy.polys.polytools.real_roots(f, multiple=True)
Return a list of real roots with multiplicities of f.

Examples

>>> from sympy import real_roots

>>> from sympy.abc import x

>>> real_roots(2*x**3 - 7*x**2 + 4*x + 4)

[-1/2, 2, 2]

sympy.polys.polytools.nroots(f, n=15, maxsteps=50, cleanup=True)

Compute numerical approximations of roots of f.

Examples

>>> from sympy import nroots

>>> from sympy.abc import x

>>> nroots(x**2 - 3, n=15)

[-1.73205080756888, 1.73205080756888]
>>> nroots(x**2 - 3, n=30)
[-1.73205080756887729352744634151, 1.73205080756887729352744634151]

sympy.polys.polytools.ground_roots(f, *gens, **args)

Compute roots of f by factorization in the ground domain.

Examples

>>> from sympy import ground_roots

>>> from sympy.abc import x

>>> ground_roots(x**6 - 4*x**4 + 4*x**3 - x**2)

{0: 2, 1: 2}

sympy.polys.polytools.nth_power_roots_poly(f, n, *gens, **args)

Construct a polynomial with n-th powers of roots of f.

844 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import nth_power_roots_poly, factor, roots

>>> from sympy.abc import x

>>> f = x**4 - x**2 + 1

>>> g = factor(nth_power_roots_poly(f, 2))

>>> g
(x**2 - x + 1)**2

>>> R_f = [ (r**2).expand() for r in roots(f) ]

>>> R_g = roots(g).keys()

>>> set(R_f) == set(R_g)

True

sympy.polys.polytools.cancel(f, *gens, **args)

Cancel common factors in a rational function f.

Examples

>>> from sympy import cancel, sqrt, Symbol

>>> from sympy.abc import x
>>> A = Symbol('A', commutative=False)

>>> cancel((2*x**2 - 2)/(x**2 - 2*x + 1))

(2*x + 2)/(x - 1)
>>> cancel((sqrt(3) + sqrt(15)*A)/(sqrt(2) + sqrt(10)*A))
sqrt(6)/2

sympy.polys.polytools.reduced(f, G, *gens, **args)

Reduces a polynomial f modulo a set of polynomials G.
Given a polynomial f and a set of polynomials G = (g_1, ..., g_n), computes a set of
quotients q = (q_1, ..., q_n) and the remainder r such that f = q_1*g_1 + ... +
q_n*g_n + r, where r vanishes or r is a completely reduced polynomial with respect to
G.

Examples

>>> from sympy import reduced

>>> from sympy.abc import x, y

>>> reduced(2*x**4 + y**2 - x**2 + y**3, [x**3 - x, y**3 - y])

([2*x, 1], x**2 + y**2 + y)

sympy.polys.polytools.groebner(F, *gens, **args)

Computes the reduced Groebner basis for a set of polynomials.

5.19. Polynomials Manipulation Module 845

SymPy Documentation, Release 1.3

Use the order argument to set the monomial ordering that will be used to compute the
basis. Allowed orders are lex, grlex and grevlex. If no order is specified, it defaults to
lex.
For more information on Groebner bases, see the references and the docstring of
solvep olys ystem().

References

1. [Buchberger01]
2. [Cox97]

[Buchberger01], [Cox97]

Examples

Example taken from [1].

>>> from sympy import groebner

>>> from sympy.abc import x, y

>>> F = [x*y - 2*y, 2*y**2 - x**2]

>>> groebner(F, x, y, order='lex')

GroebnerBasis([x**2 - 2*y**2, x*y - 2*y, y**3 - 2*y], x, y,
domain='ZZ', order='lex')
>>> groebner(F, x, y, order='grlex')
GroebnerBasis([y**3 - 2*y, x**2 - 2*y**2, x*y - 2*y], x, y,
domain='ZZ', order='grlex')
>>> groebner(F, x, y, order='grevlex')
GroebnerBasis([y**3 - 2*y, x**2 - 2*y**2, x*y - 2*y], x, y,
domain='ZZ', order='grevlex')

By default, an improved implementation of the Buchberger algorithm is used. Optionally,

an implementation of the F5B algorithm can be used. The algorithm can be set using
method flag or with the setup() function from sympy.polys.polyconfig:

>>> F = [x**2 - x - 1, (2*x - 1) * y - (x**10 - (1 - x)**10)]

>>> groebner(F, x, y, method='buchberger')

GroebnerBasis([x**2 - x - 1, y - 55], x, y, domain='ZZ', order='lex')
>>> groebner(F, x, y, method='f5b')
GroebnerBasis([x**2 - x - 1, y - 55], x, y, domain='ZZ', order='lex')

sympy.polys.polytools.is_zero_dimensional(F, *gens, **args)

Checks if the ideal generated by a Groebner basis is zero-dimensional.
The algorithm checks if the set of monomials not divisible by the leading monomial of
any element of F is bounded.

846 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

David A. Cox, John B. Little, Donal O’Shea. Ideals, Varieties and Algorithms, 3rd edition,
p. 230
class sympy.polys.polytools.Poly
Generic class for representing and operating on polynomial expressions. Subclasses
Expr class.
See also:
sympy.core.expr.Expr (page 115)

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

Create a univariate polynomial:

>>> Poly(x*(x**2 + x - 1)**2)

Poly(x**5 + 2*x**4 - x**3 - 2*x**2 + x, x, domain='ZZ')

Create a univariate polynomial with specific domain:

>>> from sympy import sqrt

>>> Poly(x**2 + 2*x + sqrt(3), domain='R')
Poly(1.0*x**2 + 2.0*x + 1.73205080756888, x, domain='RR')

Create a multivariate polynomial:

>>> Poly(y*x**2 + x*y + 1)

Poly(x**2*y + x*y + 1, x, y, domain='ZZ')

Create a univariate polynomial, where y is a constant:

>>> Poly(y*x**2 + x*y + 1,x)

Poly(y*x**2 + y*x + 1, x, domain='ZZ[y]')

You can evaluate the above polynomial as a function of y:

>>> Poly(y*x**2 + x*y + 1,x).eval(2)

6*y + 1

EC(order=None)
Returns the last non-zero coefficient of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x**2 + 3*x, x).EC()

3

5.19. Polynomials Manipulation Module 847

SymPy Documentation, Release 1.3

EM(order=None)
Returns the last non-zero monomial of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(4*x**2 + 2*x*y**2 + x*y + 3*y, x, y).EM()

x**0*y**1

ET(order=None)
Returns the last non-zero term of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(4*x**2 + 2*x*y**2 + x*y + 3*y, x, y).ET()

(x**0*y**1, 3)

LC(order=None)
Returns the leading coefficient of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(4*x**3 + 2*x**2 + 3*x, x).LC()

4

LM(order=None)
Returns the leading monomial of f.
The Leading monomial signifies the monomial having the highest power of the prin-
cipal generator in the expression f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(4*x**2 + 2*x*y**2 + x*y + 3*y, x, y).LM()

x**2*y**0

848 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

LT(order=None)
Returns the leading term of f.
The Leading term signifies the term having the highest power of the principal gen-
erator in the expression f along with its coefficient.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(4*x**2 + 2*x*y**2 + x*y + 3*y, x, y).LT()

(x**2*y**0, 4)

TC()
Returns the trailing coefficient of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x**2 + 3*x, x).TC()

0

abs()
Make all coefficients in f positive.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).abs()

Poly(x**2 + 1, x, domain='ZZ')

add(g)
Add two polynomials f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).add(Poly(x - 2, x))

Poly(x**2 + x - 1, x, domain='ZZ')

>>> Poly(x**2 + 1, x) + Poly(x - 2, x)

Poly(x**2 + x - 1, x, domain='ZZ')

5.19. Polynomials Manipulation Module 849

SymPy Documentation, Release 1.3

add_ground(coeff)
Add an element of the ground domain to f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x + 1).add_ground(2)

Poly(x + 3, x, domain='ZZ')

all_coeffs()
Returns all coefficients from a univariate polynomial f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x - 1, x).all_coeffs()

[1, 0, 2, -1]

all_monoms()
Returns all monomials from a univariate polynomial f.
See also:
all_terms (page 851)

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x - 1, x).all_monoms()

[(3,), (2,), (1,), (0,)]

all_roots(multiple=True, radicals=True)
Return a list of real and complex roots with multiplicities.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**3 - 7*x**2 + 4*x + 4).all_roots()

[-1/2, 2, 2]
>>> Poly(x**3 + x + 1).all_roots()
[CRootOf(x**3 + x + 1, 0),
(continues on next page)

850 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

CRootOf(x**3 + x + 1, 1),
CRootOf(x**3 + x + 1, 2)]

all_terms()
Returns all terms from a univariate polynomial f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x - 1, x).all_terms()

[((3,), 1), ((2,), 0), ((1,), 2), ((0,), -1)]

args
Don’t mess up with the core.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).args

(x**2 + 1,)

as_dict(native=False, zero=False)
Switch to a dict representation.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 2*x*y**2 - y, x, y).as_dict()

{(0, 1): -1, (1, 2): 2, (2, 0): 1}

as_expr(*gens)
Convert a Poly instance to an Expr instance.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = Poly(x**2 + 2*x*y**2 - y, x, y)

5.19. Polynomials Manipulation Module 851

SymPy Documentation, Release 1.3

>>> f.as_expr()
x**2 + 2*x*y**2 - y
>>> f.as_expr({x: 5})
10*y**2 - y + 25
>>> f.as_expr(5, 6)
379

as_list(native=False)
Switch to a list representation.
cancel(g, include=False)
Cancel common factors in a rational function f/g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**2 - 2, x).cancel(Poly(x**2 - 2*x + 1, x))

(1, Poly(2*x + 2, x, domain='ZZ'), Poly(x - 1, x, domain='ZZ'))

>>> Poly(2*x**2 - 2, x).cancel(Poly(x**2 - 2*x + 1, x), include=True)

(Poly(2*x + 2, x, domain='ZZ'), Poly(x - 1, x, domain='ZZ'))

clear_denoms(convert=False)
Clear denominators, but keep the ground domain.

Examples

>>> from sympy import Poly, S, QQ

>>> from sympy.abc import x

>>> f = Poly(x/2 + S(1)/3, x, domain=QQ)

>>> f.clear_denoms()
(6, Poly(3*x + 2, x, domain='QQ'))
>>> f.clear_denoms(convert=True)
(6, Poly(3*x + 2, x, domain='ZZ'))

coeff_monomial(monom)
Returns the coefficient of monom in f if there, else None.
See also:

nth (page 874) more efficient query using exponents of the monomial’s generators

Examples

>>> from sympy import Poly, exp

>>> from sympy.abc import x, y

852 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> p = Poly(24*x*y*exp(8) + 23*x, x, y)

>>> p.coeff_monomial(x)
23
>>> p.coeff_monomial(y)
0
>>> p.coeff_monomial(x*y)
24*exp(8)

Note that Expr.coeff() behaves differently, collecting terms if possible; the Poly
must be converted to an Expr to use that method, however:

>>> p.as_expr().coeff(x)
24*y*exp(8) + 23
>>> p.as_expr().coeff(y)
24*x*exp(8)
>>> p.as_expr().coeff(x*y)
24*exp(8)

coeffs(order=None)
Returns all non-zero coefficients from f in lex order.
See also:
all_coeffs (page 850), coeff_monomial (page 852), nth (page 874)

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 + 2*x + 3, x).coeffs()

[1, 2, 3]

cofactors(g)
Returns the GCD of f and g and their cofactors.
Returns polynomials (h, cff, cfg) such that h = gcd(f, g), and cff = quo(f,
h) and cfg = quo(g, h) are, so called, cofactors of f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).cofactors(Poly(x**2 - 3*x + 2, x))

(Poly(x - 1, x, domain='ZZ'),
Poly(x + 1, x, domain='ZZ'),
Poly(x - 2, x, domain='ZZ'))

compose(g)
Computes the functional composition of f and g.

5.19. Polynomials Manipulation Module 853

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + x, x).compose(Poly(x - 1, x))

Poly(x**2 - x, x, domain='ZZ')

content()
Returns the GCD of polynomial coefficients.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(6*x**2 + 8*x + 12, x).content()

2

count_roots(inf=None, sup=None)
Return the number of roots of f in [inf, sup] interval.

Examples

>>> from sympy import Poly, I

>>> from sympy.abc import x

>>> Poly(x**4 - 4, x).count_roots(-3, 3)

2
>>> Poly(x**4 - 4, x).count_roots(0, 1 + 3*I)
1

decompose()
Computes a functional decomposition of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**4 + 2*x**3 - x - 1, x, domain='ZZ').decompose()

[Poly(x**2 - x - 1, x, domain='ZZ'), Poly(x**2 + x, x, domain='ZZ')]

deflate()
Reduce degree of f by mapping x_i**m to y_i.

854 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**6*y**2 + x**3 + 1, x, y).deflate()

((3, 2), Poly(x**2*y + x + 1, x, y, domain='ZZ'))

degree(gen=0)
Returns degree of f in x_j.
The degree of 0 is negative infinity.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + y*x + 1, x, y).degree()

2
>>> Poly(x**2 + y*x + y, x, y).degree(y)
1
>>> Poly(0, x).degree()
-oo

degree_list()
Returns a list of degrees of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + y*x + 1, x, y).degree_list()

(2, 1)

diff(*specs, **kwargs)
Computes partial derivative of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 2*x + 1, x).diff()

Poly(2*x + 2, x, domain='ZZ')

>>> Poly(x*y**2 + x, x, y).diff((0, 0), (1, 1))

Poly(2*x*y, x, y, domain='ZZ')

5.19. Polynomials Manipulation Module 855

SymPy Documentation, Release 1.3

discriminant()
Computes the discriminant of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 2*x + 3, x).discriminant()

-8

dispersion(g=None)
Compute the dispersion of polynomials.
For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion dis(f, g)
is defined as:
dis(f, g) := max{J(f, g) ∪ {0}}
= max{{a ∈ N| gcd(f (x), g(x + a)) ̸= 1} ∪ {0}}

and for a single polynomial dis(f ) := dis(f, f ).

See also:
dispersionset (page 857)

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)

>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

Note that the definition of the dispersion is not symmetric:

856 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> fp = poly(x**4 - 3*x**2 + 1, x)

>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

Computing the dispersion also works over field extensions:

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 +␣
,→2*a)*x, x)

>>> sorted(dispersionset(fp))
[0, 1]

dispersionset(g=None)
Compute the dispersion set of two polynomials.
For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion set
J(f, g) is defined as:

J(f, g) := {a ∈ N0 | gcd(f (x), g(x + a)) ̸= 1}

= {a ∈ N0 | deg gcd(f (x), g(x + a)) ≥ 1}

For a single polynomial one defines J(f ) := J(f, f ).

See also:
dispersion (page 856)

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

5.19. Polynomials Manipulation Module 857

SymPy Documentation, Release 1.3

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)

>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

Note that the definition of the dispersion is not symmetric:

>>> fp = poly(x**4 - 3*x**2 + 1, x)

>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

Computing the dispersion also works over field extensions:

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 +␣
,→2*a)*x, x)

>>> sorted(dispersionset(fp))
[0, 1]

div(g, auto=True)
Polynomial division with remainder of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).div(Poly(2*x - 4, x))

(Poly(1/2*x + 1, x, domain='QQ'), Poly(5, x, domain='QQ'))

858 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Poly(x**2 + 1, x).div(Poly(2*x - 4, x), auto=False)

(Poly(0, x, domain='ZZ'), Poly(x**2 + 1, x, domain='ZZ'))

domain
Get the ground domain of self.
eject(*gens)
Eject selected generators into the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = Poly(x**2*y + x*y**3 + x*y + 1, x, y)

>>> f.eject(x)
Poly(x*y**3 + (x**2 + x)*y + 1, y, domain='ZZ[x]')
>>> f.eject(y)
Poly(y*x**2 + (y**3 + y)*x + 1, x, domain='ZZ[y]')

eval(x, a=None, auto=True)

Evaluate f at a in the given variable.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y, z

>>> Poly(x**2 + 2*x + 3, x).eval(2)

11

>>> Poly(2*x*y + 3*x + y + 2, x, y).eval(x, 2)

Poly(5*y + 8, y, domain='ZZ')

>>> f = Poly(2*x*y + 3*x + y + 2*z, x, y, z)

>>> f.eval({x: 2})

Poly(5*y + 2*z + 6, y, z, domain='ZZ')
>>> f.eval({x: 2, y: 5})
Poly(2*z + 31, z, domain='ZZ')
>>> f.eval({x: 2, y: 5, z: 7})
45

>>> f.eval((2, 5))

Poly(2*z + 31, z, domain='ZZ')
>>> f(2, 5)
Poly(2*z + 31, z, domain='ZZ')

exclude()
Remove unnecessary generators from f.

5.19. Polynomials Manipulation Module 859

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import a, b, c, d, x

>>> Poly(a + x, a, b, c, d, x).exclude()

Poly(a + x, a, x, domain='ZZ')

exquo(g, auto=True)
Computes polynomial exact quotient of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).exquo(Poly(x - 1, x))

Poly(x + 1, x, domain='ZZ')

>>> Poly(x**2 + 1, x).exquo(Poly(2*x - 4, x))

Traceback (most recent call last):
...
ExactQuotientFailed: 2*x - 4 does not divide x**2 + 1

exquo_ground(coeff)
Exact quotient of f by a an element of the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x + 4).exquo_ground(2)

Poly(x + 2, x, domain='ZZ')

>>> Poly(2*x + 3).exquo_ground(2)

Traceback (most recent call last):
...
ExactQuotientFailed: 2 does not divide 3 in ZZ

factor_list()
Returns a list of irreducible factors of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

860 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> f = 2*x**5 + 2*x**4*y + 4*x**3 + 4*x**2*y + 2*x + 2*y

>>> Poly(f).factor_list()
(2, [(Poly(x + y, x, y, domain='ZZ'), 1),
(Poly(x**2 + 1, x, y, domain='ZZ'), 2)])

factor_list_include()
Returns a list of irreducible factors of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = 2*x**5 + 2*x**4*y + 4*x**3 + 4*x**2*y + 2*x + 2*y

>>> Poly(f).factor_list_include()
[(Poly(2*x + 2*y, x, y, domain='ZZ'), 1),
(Poly(x**2 + 1, x, y, domain='ZZ'), 2)]

free_symbols
Free symbols of a polynomial expression.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y, z

>>> Poly(x**2 + 1).free_symbols

{x}
>>> Poly(x**2 + y).free_symbols
{x, y}
>>> Poly(x**2 + y, x).free_symbols
{x, y}
>>> Poly(x**2 + y, x, z).free_symbols
{x, y}

free_symbols_in_domain
Free symbols of the domain of self.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 1).free_symbols_in_domain

set()
>>> Poly(x**2 + y).free_symbols_in_domain
set()
(continues on next page)

5.19. Polynomials Manipulation Module 861

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Poly(x**2 + y, x).free_symbols_in_domain
{y}

classmethod from_dict(rep, *gens, **args)

Construct a polynomial from a dict.
classmethod from_expr(rep, *gens, **args)
Construct a polynomial from an expression.
classmethod from_list(rep, *gens, **args)
Construct a polynomial from a list.
classmethod from_poly(rep, *gens, **args)
Construct a polynomial from a polynomial.
gcd(g)
Returns the polynomial GCD of f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).gcd(Poly(x**2 - 3*x + 2, x))

Poly(x - 1, x, domain='ZZ')

gcdex(g, auto=True)
Extended Euclidean algorithm of f and g.
Returns (s, t, h) such that h = gcd(f, g) and s*f + t*g = h.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = x**4 - 2*x**3 - 6*x**2 + 12*x + 15

>>> g = x**3 + x**2 - 4*x - 4

>>> Poly(f).gcdex(Poly(g))
(Poly(-1/5*x + 3/5, x, domain='QQ'),
Poly(1/5*x**2 - 6/5*x + 2, x, domain='QQ'),
Poly(x + 1, x, domain='QQ'))

gen
Return the principal generator.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

862 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Poly(x**2 + 1, x).gen

x

get_domain()
Get the ground domain of f.
get_modulus()
Get the modulus of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, modulus=2).get_modulus()

2

gff_list()
Computes greatest factorial factorization of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = x**5 + 2*x**4 - x**3 - 2*x**2

>>> Poly(f).gff_list()
[(Poly(x, x, domain='ZZ'), 1), (Poly(x + 2, x, domain='ZZ'), 4)]

ground_roots()
Compute roots of f by factorization in the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**6 - 4*x**4 + 4*x**3 - x**2).ground_roots()

{0: 2, 1: 2}

half_gcdex(g, auto=True)
Half extended Euclidean algorithm of f and g.
Returns (s, h) such that h = gcd(f, g) and s*f = h (mod g).

Examples

5.19. Polynomials Manipulation Module 863

SymPy Documentation, Release 1.3

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = x**4 - 2*x**3 - 6*x**2 + 12*x + 15

>>> g = x**3 + x**2 - 4*x - 4

>>> Poly(f).half_gcdex(Poly(g))
(Poly(-1/5*x + 3/5, x, domain='QQ'), Poly(x + 1, x, domain='QQ'))

has_only_gens(*gens)
Return True if Poly(f, *gens) retains ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y, z

>>> Poly(x*y + 1, x, y, z).has_only_gens(x, y)

True
>>> Poly(x*y + z, x, y, z).has_only_gens(x, y)
False

homogeneous_order()
Returns the homogeneous order of f.
A homogeneous polynomial is a polynomial whose all monomials with non-zero co-
efficients have the same total degree. This degree is the homogeneous order of
f. If you only want to check if a polynomial is homogeneous, then use Poly.
is_homogeneous() (page 867).

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = Poly(x**5 + 2*x**3*y**2 + 9*x*y**4)

>>> f.homogeneous_order()
5

homogenize(s)
Returns the homogeneous polynomial of f.
A homogeneous polynomial is a polynomial whose all monomials with non-zero co-
efficients have the same total degree. If you only want to check if a polynomial is
homogeneous, then use Poly.is_homogeneous() (page 867). If you want not only
to check if a polynomial is homogeneous but also compute its homogeneous order,
then use Poly.homogeneous_order() (page 864).

864 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y, z

>>> f = Poly(x**5 + 2*x**2*y**2 + 9*x*y**3)

>>> f.homogenize(z)
Poly(x**5 + 2*x**2*y**2*z + 9*x*y**3*z, x, y, z, domain='ZZ')

inject(front=False)
Inject ground domain generators into f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = Poly(x**2*y + x*y**3 + x*y + 1, x)

>>> f.inject()
Poly(x**2*y + x*y**3 + x*y + 1, x, y, domain='ZZ')
>>> f.inject(front=True)
Poly(y**3*x + y*x**2 + y*x + 1, y, x, domain='ZZ')

integrate(*specs, **args)
Computes indefinite integral of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 2*x + 1, x).integrate()

Poly(1/3*x**3 + x**2 + x, x, domain='QQ')

>>> Poly(x*y**2 + x, x, y).integrate((0, 1), (1, 0))

Poly(1/2*x**2*y**2 + 1/2*x**2, x, y, domain='QQ')

intervals(all=False, eps=None, inf=None, sup=None, fast=False, sqf=False)

Compute isolating intervals for roots of f.
For real roots the Vincent-Akritas-Strzebonski (VAS) continued fractions method is
used.

References

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

5.19. Polynomials Manipulation Module 865

SymPy Documentation, Release 1.3

>>> Poly(x**2 - 3, x).intervals()

[((-2, -1), 1), ((1, 2), 1)]
>>> Poly(x**2 - 3, x).intervals(eps=1e-2)
[((-26/15, -19/11), 1), ((19/11, 26/15), 1)]

invert(g, auto=True)
Invert f modulo g when possible.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).invert(Poly(2*x - 1, x))

Poly(-4/3, x, domain='QQ')

>>> Poly(x**2 - 1, x).invert(Poly(x - 1, x))

Traceback (most recent call last):
...
NotInvertible: zero divisor

is_cyclotomic
Returns True if f is a cyclotomic polnomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = x**16 + x**14 - x**10 + x**8 - x**6 + x**2 + 1

>>> Poly(f).is_cyclotomic
False

>>> g = x**16 + x**14 - x**10 - x**8 - x**6 + x**2 + 1

>>> Poly(g).is_cyclotomic
True

is_ground
Returns True if f is an element of the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

866 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Poly(x, x).is_ground

False
>>> Poly(2, x).is_ground
True
>>> Poly(y, x).is_ground
True

is_homogeneous
Returns True if f is a homogeneous polynomial.
A homogeneous polynomial is a polynomial whose all monomials with non-zero co-
efficients have the same total degree. If you want not only to check if a poly-
nomial is homogeneous but also compute its homogeneous order, then use Poly.
homogeneous_order() (page 864).

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + x*y, x, y).is_homogeneous

True
>>> Poly(x**3 + x*y, x, y).is_homogeneous
False

is_irreducible
Returns True if f has no factors over its domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + x + 1, x, modulus=2).is_irreducible

True
>>> Poly(x**2 + 1, x, modulus=2).is_irreducible
False

is_linear
Returns True if f is linear in all its variables.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x + y + 2, x, y).is_linear

True
>>> Poly(x*y + 2, x, y).is_linear
False

5.19. Polynomials Manipulation Module 867

SymPy Documentation, Release 1.3

is_monic
Returns True if the leading coefficient of f is one.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x + 2, x).is_monic

True
>>> Poly(2*x + 2, x).is_monic
False

is_monomial
Returns True if f is zero or has only one term.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(3*x**2, x).is_monomial

True
>>> Poly(3*x**2 + 1, x).is_monomial
False

is_multivariate
Returns True if f is a multivariate polynomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + x + 1, x).is_multivariate

False
>>> Poly(x*y**2 + x*y + 1, x, y).is_multivariate
True
>>> Poly(x*y**2 + x*y + 1, x).is_multivariate
False
>>> Poly(x**2 + x + 1, x, y).is_multivariate
True

is_one
Returns True if f is a unit polynomial.

Examples

868 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(0, x).is_one

False
>>> Poly(1, x).is_one
True

is_primitive
Returns True if GCD of the coefficients of f is one.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**2 + 6*x + 12, x).is_primitive

False
>>> Poly(x**2 + 3*x + 6, x).is_primitive
True

is_quadratic
Returns True if f is quadratic in all its variables.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x*y + 2, x, y).is_quadratic

True
>>> Poly(x*y**2 + 2, x, y).is_quadratic
False

is_sqf
Returns True if f is a square-free polynomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 2*x + 1, x).is_sqf

False
>>> Poly(x**2 - 1, x).is_sqf
True

is_univariate
Returns True if f is a univariate polynomial.

5.19. Polynomials Manipulation Module 869

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + x + 1, x).is_univariate

True
>>> Poly(x*y**2 + x*y + 1, x, y).is_univariate
False
>>> Poly(x*y**2 + x*y + 1, x).is_univariate
True
>>> Poly(x**2 + x + 1, x, y).is_univariate
False

is_zero
Returns True if f is a zero polynomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(0, x).is_zero

True
>>> Poly(1, x).is_zero
False

l1_norm()
Returns l1 norm of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(-x**2 + 2*x - 3, x).l1_norm()

6

lcm(g)
Returns polynomial LCM of f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).lcm(Poly(x**2 - 3*x + 2, x))

Poly(x**3 - 2*x**2 - x + 2, x, domain='ZZ')

length()
Returns the number of non-zero terms in f.

870 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 2*x - 1).length()

3

lift()
Convert algebraic coefficients to rationals.

Examples

>>> from sympy import Poly, I

>>> from sympy.abc import x

>>> Poly(x**2 + I*x + 1, x, extension=I).lift()

Poly(x**4 + 3*x**2 + 1, x, domain='QQ')

ltrim(gen)
Remove dummy generators from f that are to the left of specified gen in the gener-
ators as ordered. When gen is an integer, it refers to the generator located at that
position within the tuple of generators of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y, z

>>> Poly(y**2 + y*z**2, x, y, z).ltrim(y)

Poly(y**2 + y*z**2, y, z, domain='ZZ')
>>> Poly(z, x, y, z).ltrim(-1)
Poly(z, z, domain='ZZ')

max_norm()
Returns maximum norm of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(-x**2 + 2*x - 3, x).max_norm()

3

monic(auto=True)
Divides all coefficients by LC(f).

5.19. Polynomials Manipulation Module 871

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly, ZZ

>>> from sympy.abc import x

>>> Poly(3*x**2 + 6*x + 9, x, domain=ZZ).monic()

Poly(x**2 + 2*x + 3, x, domain='QQ')

>>> Poly(3*x**2 + 4*x + 2, x, domain=ZZ).monic()

Poly(x**2 + 4/3*x + 2/3, x, domain='QQ')

monoms(order=None)
Returns all non-zero monomials from f in lex order.
See also:
all_monoms (page 850)

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 2*x*y**2 + x*y + 3*y, x, y).monoms()

[(2, 0), (1, 2), (1, 1), (0, 1)]

mul(g)
Multiply two polynomials f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).mul(Poly(x - 2, x))

Poly(x**3 - 2*x**2 + x - 2, x, domain='ZZ')

>>> Poly(x**2 + 1, x)*Poly(x - 2, x)

Poly(x**3 - 2*x**2 + x - 2, x, domain='ZZ')

mul_ground(coeff)
Multiply f by a an element of the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x + 1).mul_ground(2)

Poly(2*x + 2, x, domain='ZZ')

872 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

neg()
Negate all coefficients in f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).neg()

Poly(-x**2 + 1, x, domain='ZZ')

>>> -Poly(x**2 - 1, x)
Poly(-x**2 + 1, x, domain='ZZ')

classmethod new(rep, *gens)

Construct Poly (page 847) instance from raw representation.
norm()
Computes the product, Norm(f), of the conjugates of a polynomial f defined over a
number field K.

Examples

>>> from sympy import Poly, sqrt

>>> from sympy.abc import x

>>> a, b = sqrt(2), sqrt(3)

A polynomial over a quadratic extension. Two conjugates x - a and x + a.

>>> f = Poly(x - a, x, extension=a)

>>> f.norm()
Poly(x**2 - 2, x, domain='QQ')

A polynomial over a quartic extension. Four conjugates x - a, x - a, x + a and x + a.

>>> f = Poly(x - a, x, extension=(a, b))

>>> f.norm()
Poly(x**4 - 4*x**2 + 4, x, domain='QQ')

nroots(n=15, maxsteps=50, cleanup=True)

Compute numerical approximations of roots of f.
Parameters n … the number of digits to calculate
maxsteps … the maximum number of iterations to do
If the accuracy ‘n‘ cannot be reached in ‘maxsteps‘, it will raise an
exception. You need to rerun with higher maxsteps.

5.19. Polynomials Manipulation Module 873

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 3).nroots(n=15)

[-1.73205080756888, 1.73205080756888]
>>> Poly(x**2 - 3).nroots(n=30)
[-1.73205080756887729352744634151, 1.73205080756887729352744634151]

nth(*N)
Returns the n-th coefficient of f where N are the exponents of the generators in the
term of interest.
See also:
coeff_monomial (page 852)

Examples

>>> from sympy import Poly, sqrt

>>> from sympy.abc import x, y

>>> Poly(x**3 + 2*x**2 + 3*x, x).nth(2)

2
>>> Poly(x**3 + 2*x*y**2 + y**2, x, y).nth(1, 2)
2
>>> Poly(4*sqrt(x)*y)
Poly(4*y*(sqrt(x)), y, sqrt(x), domain='ZZ')
>>> _.nth(1, 1)
4

nth_power_roots_poly(n)
Construct a polynomial with n-th powers of roots of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = Poly(x**4 - x**2 + 1)

>>> f.nth_power_roots_poly(2)
Poly(x**4 - 2*x**3 + 3*x**2 - 2*x + 1, x, domain='ZZ')
>>> f.nth_power_roots_poly(3)
Poly(x**4 + 2*x**2 + 1, x, domain='ZZ')
>>> f.nth_power_roots_poly(4)
Poly(x**4 + 2*x**3 + 3*x**2 + 2*x + 1, x, domain='ZZ')
>>> f.nth_power_roots_poly(12)
Poly(x**4 - 4*x**3 + 6*x**2 - 4*x + 1, x, domain='ZZ')

one
Return one polynomial with self’s properties.

874 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

pdiv(g)
Polynomial pseudo-division of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).pdiv(Poly(2*x - 4, x))

(Poly(2*x + 4, x, domain='ZZ'), Poly(20, x, domain='ZZ'))

per(rep, gens=None, remove=None)

Create a Poly out of the given representation.

Examples

>>> from sympy import Poly, ZZ

>>> from sympy.abc import x, y

>>> from sympy.polys.polyclasses import DMP

>>> a = Poly(x**2 + 1)

>>> a.per(DMP([ZZ(1), ZZ(1)], ZZ), gens=[y])

Poly(y + 1, y, domain='ZZ')

pexquo(g)
Polynomial exact pseudo-quotient of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 1, x).pexquo(Poly(2*x - 2, x))

Poly(2*x + 2, x, domain='ZZ')

>>> Poly(x**2 + 1, x).pexquo(Poly(2*x - 4, x))

Traceback (most recent call last):
...
ExactQuotientFailed: 2*x - 4 does not divide x**2 + 1

pow(n)
Raise f to a non-negative power n.

Examples

5.19. Polynomials Manipulation Module 875

SymPy Documentation, Release 1.3

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x - 2, x).pow(3)

Poly(x**3 - 6*x**2 + 12*x - 8, x, domain='ZZ')

>>> Poly(x - 2, x)**3

Poly(x**3 - 6*x**2 + 12*x - 8, x, domain='ZZ')

pquo(g)
Polynomial pseudo-quotient of f by g.
See the Caveat note in the function prem(f, g).

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).pquo(Poly(2*x - 4, x))

Poly(2*x + 4, x, domain='ZZ')

>>> Poly(x**2 - 1, x).pquo(Poly(2*x - 2, x))

Poly(2*x + 2, x, domain='ZZ')

prem(g)
Polynomial pseudo-remainder of f by g.
Caveat: The function prem(f, g, x) can be safely used to compute in Z[x]
_only_ subresultant polynomial remainder sequences (prs’s).
To safely compute Euclidean and Sturmian prs’s in Z[x] employ anyone of the cor-
responding functions found in the module sympy.polys.subresultants_qq_zz. The
functions in the module with suffix _pg compute prs’s in Z[x] employing rem(f,
g, x), whereas the functions with suffix _amv compute prs’s in Z[x] employing
rem_z(f, g, x).
The function rem_z(f, g, x) differs from prem(f, g, x) in that to compute the re-
mainder polynomials in Z[x] it premultiplies the divident times the absolute value
of the leading coefficient of the divisor raised to the power degree(f, x) - degree(g,
x) + 1.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).prem(Poly(2*x - 4, x))

Poly(20, x, domain='ZZ')

primitive()
Returns the content and a primitive form of f.

876 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**2 + 8*x + 12, x).primitive()

(2, Poly(x**2 + 4*x + 6, x, domain='ZZ'))

quo(g, auto=True)
Computes polynomial quotient of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).quo(Poly(2*x - 4, x))

Poly(1/2*x + 1, x, domain='QQ')

>>> Poly(x**2 - 1, x).quo(Poly(x - 1, x))

Poly(x + 1, x, domain='ZZ')

quo_ground(coeff)
Quotient of f by a an element of the ground domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x + 4).quo_ground(2)

Poly(x + 2, x, domain='ZZ')

>>> Poly(2*x + 3).quo_ground(2)

Poly(x + 1, x, domain='ZZ')

rat_clear_denoms(g)
Clear denominators in a rational function f/g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> f = Poly(x**2/y + 1, x)
>>> g = Poly(x**3 + y, x)

>>> p, q = f.rat_clear_denoms(g)

5.19. Polynomials Manipulation Module 877

SymPy Documentation, Release 1.3

>>> p
Poly(x**2 + y, x, domain='ZZ[y]')
>>> q
Poly(y*x**3 + y**2, x, domain='ZZ[y]')

real_roots(multiple=True, radicals=True)
Return a list of real roots with multiplicities.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**3 - 7*x**2 + 4*x + 4).real_roots()

[-1/2, 2, 2]
>>> Poly(x**3 + x + 1).real_roots()
[CRootOf(x**3 + x + 1, 0)]

refine_root(s, t, eps=None, steps=None, fast=False, check_sqf=False)

Refine an isolating interval of a root to the given precision.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 3, x).refine_root(1, 2, eps=1e-2)

(19/11, 26/15)

rem(g, auto=True)
Computes the polynomial remainder of f by g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).rem(Poly(2*x - 4, x))

Poly(5, x, domain='ZZ')

>>> Poly(x**2 + 1, x).rem(Poly(2*x - 4, x), auto=False)

Poly(x**2 + 1, x, domain='ZZ')

reorder(*gens, **args)
Efficiently apply new order of generators.

878 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + x*y**2, x, y).reorder(y, x)

Poly(y**2*x + x**2, y, x, domain='ZZ')

replace(x, y=None)
Replace x with y in generators list.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 1, x).replace(x, y)

Poly(y**2 + 1, y, domain='ZZ')

resultant(g, includePRS=False)
Computes the resultant of f and g via PRS.
If includePRS=True, it includes the subresultant PRS in the result. Because the PRS
is used to calculate the resultant, this is more efficient than calling subresultants()
(page 833) separately.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = Poly(x**2 + 1, x)

>>> f.resultant(Poly(x**2 - 1, x))

4
>>> f.resultant(Poly(x**2 - 1, x), includePRS=True)
(4, [Poly(x**2 + 1, x, domain='ZZ'), Poly(x**2 - 1, x, domain='ZZ'),
Poly(-2, x, domain='ZZ')])

retract(field=None)
Recalculate the ground domain of a polynomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = Poly(x**2 + 1, x, domain='QQ[y]')

>>> f
Poly(x**2 + 1, x, domain='QQ[y]')

5.19. Polynomials Manipulation Module 879

SymPy Documentation, Release 1.3

>>> f.retract()
Poly(x**2 + 1, x, domain='ZZ')
>>> f.retract(field=True)
Poly(x**2 + 1, x, domain='QQ')

revert(n)
Compute f**(-1) mod x**n.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(1, x).revert(2)

Poly(1, x, domain='ZZ')

>>> Poly(1 + x, x).revert(1)

Poly(1, x, domain='ZZ')

>>> Poly(x**2 - 1, x).revert(1)

Traceback (most recent call last):
...
NotReversible: only unity is reversible in a ring

>>> Poly(1/x, x).revert(1)

Traceback (most recent call last):
...
PolynomialError: 1/x contains an element of the generators set

root(index, radicals=True)
Get an indexed root of a polynomial.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = Poly(2*x**3 - 7*x**2 + 4*x + 4)

>>> f.root(0)
-1/2
>>> f.root(1)
2
>>> f.root(2)
2
>>> f.root(3)
Traceback (most recent call last):
...
IndexError: root index out of [-3, 2] range, got 3

880 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Poly(x**5 + x + 1).root(0)

CRootOf(x**3 - x**2 + 1, 0)

set_domain(domain)
Set the ground domain of f.
set_modulus(modulus)
Set the modulus of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(5*x**2 + 2*x - 1, x).set_modulus(2)

Poly(x**2 + 1, x, modulus=2)

shift(a)
Efficiently compute Taylor shift f(x + a).

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 2*x + 1, x).shift(2)

Poly(x**2 + 2*x + 1, x, domain='ZZ')

slice(x, m, n=None)
Take a continuous subsequence of terms of f.
sqf_list(all=False)
Returns a list of square-free factors of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f = 2*x**5 + 16*x**4 + 50*x**3 + 76*x**2 + 56*x + 16

>>> Poly(f).sqf_list()
(2, [(Poly(x + 1, x, domain='ZZ'), 2),
(Poly(x + 2, x, domain='ZZ'), 3)])

>>> Poly(f).sqf_list(all=True)
(2, [(Poly(1, x, domain='ZZ'), 1),
(Poly(x + 1, x, domain='ZZ'), 2),
(Poly(x + 2, x, domain='ZZ'), 3)])

5.19. Polynomials Manipulation Module 881

SymPy Documentation, Release 1.3

sqf_list_include(all=False)
Returns a list of square-free factors of f.

Examples

>>> from sympy import Poly, expand

>>> from sympy.abc import x

>>> f = expand(2*(x + 1)**3*x**4)

>>> f
2*x**7 + 6*x**6 + 6*x**5 + 2*x**4

>>> Poly(f).sqf_list_include()
[(Poly(2, x, domain='ZZ'), 1),
(Poly(x + 1, x, domain='ZZ'), 3),
(Poly(x, x, domain='ZZ'), 4)]

>>> Poly(f).sqf_list_include(all=True)
[(Poly(2, x, domain='ZZ'), 1),
(Poly(1, x, domain='ZZ'), 2),
(Poly(x + 1, x, domain='ZZ'), 3),
(Poly(x, x, domain='ZZ'), 4)]

sqf_norm()
Computes square-free norm of f.
Returns s, f, r, such that g(x) = f(x-sa) and r(x) = Norm(g(x)) is a square-free
polynomial over K, where a is the algebraic extension of the ground domain.

Examples

>>> from sympy import Poly, sqrt

>>> from sympy.abc import x

>>> s, f, r = Poly(x**2 + 1, x, extension=[sqrt(3)]).sqf_norm()

>>> s
1
>>> f
Poly(x**2 - 2*sqrt(3)*x + 4, x, domain='QQ<sqrt(3)>')
>>> r
Poly(x**4 - 4*x**2 + 16, x, domain='QQ')

sqf_part()
Computes square-free part of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

882 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Poly(x**3 - 3*x - 2, x).sqf_part()

Poly(x**2 - x - 2, x, domain='ZZ')

sqr()
Square a polynomial f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x - 2, x).sqr()

Poly(x**2 - 4*x + 4, x, domain='ZZ')

>>> Poly(x - 2, x)**2

Poly(x**2 - 4*x + 4, x, domain='ZZ')

sturm(auto=True)
Computes the Sturm sequence of f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**3 - 2*x**2 + x - 3, x).sturm()

[Poly(x**3 - 2*x**2 + x - 3, x, domain='QQ'),
Poly(3*x**2 - 4*x + 1, x, domain='QQ'),
Poly(2/9*x + 25/9, x, domain='QQ'),
Poly(-2079/4, x, domain='QQ')]

sub(g)
Subtract two polynomials f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).sub(Poly(x - 2, x))

Poly(x**2 - x + 3, x, domain='ZZ')

>>> Poly(x**2 + 1, x) - Poly(x - 2, x)

Poly(x**2 - x + 3, x, domain='ZZ')

sub_ground(coeff)
Subtract an element of the ground domain from f.

5.19. Polynomials Manipulation Module 883

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x + 1).sub_ground(2)

Poly(x - 1, x, domain='ZZ')

subresultants(g)
Computes the subresultant PRS of f and g.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x).subresultants(Poly(x**2 - 1, x))

[Poly(x**2 + 1, x, domain='ZZ'),
Poly(x**2 - 1, x, domain='ZZ'),
Poly(-2, x, domain='ZZ')]

terms(order=None)
Returns all non-zero terms from f in lex order.
See also:
all_terms (page 851)

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + 2*x*y**2 + x*y + 3*y, x, y).terms()

[((2, 0), 1), ((1, 2), 2), ((1, 1), 1), ((0, 1), 3)]

terms_gcd()
Remove GCD of terms from the polynomial f.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**6*y**2 + x**3*y, x, y).terms_gcd()

((3, 1), Poly(x**3*y + 1, x, y, domain='ZZ'))

termwise(func, *gens, **args)

Apply a function to all terms of f.

884 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> def func(k, coeff):

... k = k[0]
... return coeff//10**(2-k)

>>> Poly(x**2 + 20*x + 400).termwise(func)

Poly(x**2 + 2*x + 4, x, domain='ZZ')

to_exact()
Make the ground domain exact.

Examples

>>> from sympy import Poly, RR

>>> from sympy.abc import x

>>> Poly(x**2 + 1.0, x, domain=RR).to_exact()

Poly(x**2 + 1, x, domain='QQ')

to_field()
Make the ground domain a field.

Examples

>>> from sympy import Poly, ZZ

>>> from sympy.abc import x

>>> Poly(x**2 + 1, x, domain=ZZ).to_field()

Poly(x**2 + 1, x, domain='QQ')

to_ring()
Make the ground domain a ring.

Examples

>>> from sympy import Poly, QQ

>>> from sympy.abc import x

>>> Poly(x**2 + 1, domain=QQ).to_ring()

Poly(x**2 + 1, x, domain='ZZ')

total_degree()
Returns the total degree of f.

5.19. Polynomials Manipulation Module 885

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Poly

>>> from sympy.abc import x, y

>>> Poly(x**2 + y*x + 1, x, y).total_degree()

2
>>> Poly(x + y**5, x, y).total_degree()
5

transform(p, q)
Efficiently evaluate the functional transformation q**n * f(p/q).

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(x**2 - 2*x + 1, x).transform(Poly(x + 1, x), Poly(x - 1, x))

Poly(4, x, domain='ZZ')

trunc(p)
Reduce f modulo a constant p.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> Poly(2*x**3 + 3*x**2 + 5*x + 7, x).trunc(3)

Poly(-x**3 - x + 1, x, domain='ZZ')

unify(g)
Make f and g belong to the same domain.

Examples

>>> from sympy import Poly

>>> from sympy.abc import x

>>> f, g = Poly(x/2 + 1), Poly(2*x + 1)

>>> f
Poly(1/2*x + 1, x, domain='QQ')
>>> g
Poly(2*x + 1, x, domain='ZZ')

>>> F, G = f.unify(g)

886 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> F
Poly(1/2*x + 1, x, domain='QQ')
>>> G
Poly(2*x + 1, x, domain='QQ')

unit
Return unit polynomial with self’s properties.
zero
Return zero polynomial with self’s properties.
class sympy.polys.polytools.PurePoly
Class for representing pure polynomials.
free_symbols
Free symbols of a polynomial.

Examples

>>> from sympy import PurePoly

>>> from sympy.abc import x, y

>>> PurePoly(x**2 + 1).free_symbols

set()
>>> PurePoly(x**2 + y).free_symbols
set()
>>> PurePoly(x**2 + y, x).free_symbols
{y}

class sympy.polys.polytools.GroebnerBasis
Represents a reduced Groebner basis.
contains(poly)
Check if poly belongs the ideal generated by self.

Examples

>>> from sympy import groebner

>>> from sympy.abc import x, y

>>> f = 2*x**3 + y**3 + 3*y

>>> G = groebner([x**2 + y**2 - 1, x*y - 2])

>>> G.contains(f)
True
>>> G.contains(f + 1)
False

fglm(order)
Convert a Groebner basis from one ordering to another.
The FGLM algorithm converts reduced Groebner bases of zero-dimensional ideals
from one ordering to another. This method is often used when it is infeasible to
compute a Groebner basis with respect to a particular ordering directly.

5.19. Polynomials Manipulation Module 887

SymPy Documentation, Release 1.3

References

J.C. Faugere, P. Gianni, D. Lazard, T. Mora (1994). Efficient Computation of Zero-

dimensional Groebner Bases by Change of Ordering

Examples

>>> from sympy.abc import x, y

>>> from sympy import groebner

>>> F = [x**2 - 3*y - x + 1, y**2 - 2*x + y - 1]

>>> G = groebner(F, x, y, order='grlex')

>>> list(G.fglm('lex'))
[2*x - y**2 - y + 1, y**4 + 2*y**3 - 3*y**2 - 16*y + 7]
>>> list(groebner(F, x, y, order='lex'))
[2*x - y**2 - y + 1, y**4 + 2*y**3 - 3*y**2 - 16*y + 7]

is_zero_dimensional
Checks if the ideal generated by a Groebner basis is zero-dimensional.
The algorithm checks if the set of monomials not divisible by the leading monomial
of any element of F is bounded.

References

David A. Cox, John B. Little, Donal O’Shea. Ideals, Varieties and Algorithms, 3rd
edition, p. 230
reduce(expr, auto=True)
Reduces a polynomial modulo a Groebner basis.
Given a polynomial f and a set of polynomials G = (g_1, ..., g_n), computes a
set of quotients q = (q_1, ..., q_n) and the remainder r such that f = q_1*f_1
+ ... + q_n*f_n + r, where r vanishes or r is a completely reduced polynomial
with respect to G.

Examples

>>> from sympy import groebner, expand

>>> from sympy.abc import x, y

>>> f = 2*x**4 - x**2 + y**3 + y**2

>>> G = groebner([x**3 - x, y**3 - y])

>>> G.reduce(f)
([2*x, 1], x**2 + y**2 + y)
>>> Q, r = _

888 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> expand(sum(q*g for q, g in zip(Q, G)) + r)

2*x**4 - x**2 + y**3 + y**2
>>> _ == f
True

Extra polynomial manipulation functions

sympy.polys.polyfuncs.symmetrize(F, *gens, **args)

Rewrite a polynomial in terms of elementary symmetric polynomials.
A symmetric polynomial is a multivariate polynomial that remains invariant under
any variable permutation, i.e., if f = f(x_1, x_2, ..., x_n), then f = f(x_{i_1},
x_{i_2}, ..., x_{i_n}), where (i_1, i_2, ..., i_n) is a permutation of (1, 2, .
.., n) (an element of the group S_n).
Returns a tuple of symmetric polynomials (f1, f2, ..., fn) such that f = f1 + f2 +
... + fn.

Examples

>>> from sympy.polys.polyfuncs import symmetrize

>>> from sympy.abc import x, y

>>> symmetrize(x**2 + y**2)

(-2*x*y + (x + y)**2, 0)

>>> symmetrize(x**2 + y**2, formal=True)

(s1**2 - 2*s2, 0, [(s1, x + y), (s2, x*y)])

>>> symmetrize(x**2 - y**2)

(-2*x*y + (x + y)**2, -2*y**2)

>>> symmetrize(x**2 - y**2, formal=True)

(s1**2 - 2*s2, -2*y**2, [(s1, x + y), (s2, x*y)])

sympy.polys.polyfuncs.horner(f, *gens, **args)

Rewrite a polynomial in Horner form.
Among other applications, evaluation of a polynomial at a point is optimal when it is
applied using the Horner scheme ([1]).

References

[1] - http://en.wikipedia.org/wiki/Horner_scheme

Examples

>>> from sympy.polys.polyfuncs import horner

>>> from sympy.abc import x, y, a, b, c, d, e

5.19. Polynomials Manipulation Module 889

SymPy Documentation, Release 1.3

>>> horner(9*x**4 + 8*x**3 + 7*x**2 + 6*x + 5)

x*(x*(x*(9*x + 8) + 7) + 6) + 5

>>> horner(a*x**4 + b*x**3 + c*x**2 + d*x + e)

e + x*(d + x*(c + x*(a*x + b)))

>>> f = 4*x**2*y**2 + 2*x**2*y + 2*x*y**2 + x*y

>>> horner(f, wrt=x)

x*(x*y*(4*y + 2) + y*(2*y + 1))

>>> horner(f, wrt=y)

y*(x*y*(4*x + 2) + x*(2*x + 1))

sympy.polys.polyfuncs.interpolate(data, x)
Construct an interpolating polynomial for the data points.

Examples

>>> from sympy.polys.polyfuncs import interpolate

>>> from sympy.abc import x

A list is interpreted as though it were paired with a range starting from 1:

>>> interpolate([1, 4, 9, 16], x)

x**2

This can be made explicit by giving a list of coordinates:

>>> interpolate([(1, 1), (2, 4), (3, 9)], x)

x**2

The (x, y) coordinates can also be given as keys and values of a dictionary (and the points
need not be equispaced):

>>> interpolate([(-1, 2), (1, 2), (2, 5)], x)

x**2 + 1
>>> interpolate({-1: 2, 1: 2, 2: 5}, x)
x**2 + 1

sympy.polys.polyfuncs.viete(f, roots=None, *gens, **args)

Generate Viete’s formulas for f.

Examples

>>> from sympy.polys.polyfuncs import viete

>>> from sympy import symbols

>>> x, a, b, c, r1, r2 = symbols('x,a:c,r1:3')

890 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> viete(a*x**2 + b*x + c, [r1, r2], x)

[(r1 + r2, -b/a), (r1*r2, c/a)]

Domain constructors

sympy.polys.constructor.construct_domain(obj, **args)
Construct a minimal domain for the list of coefficients.

Algebraic number fields

sympy.polys.numberfields.minimal_polynomial(ex, x=None, compose=True,

polys=False, domain=None)
Computes the minimal polynomial of an algebraic element.
Parameters ex : Expr
Element or expression whose minimal polynomial is to be calculated.
x : Symbol, optional
Independent variable of the minimal polynomial
compose : boolean, optional (default=True)
Method to use for computing minimal polynomial. If compose=True
(default) then _minpoly_compose is used, if compose=False then
groebner bases are used.
polys : boolean, optional (default=False)
If True returns a Poly object else an Expr object.
domain : Domain, optional
Ground domain

Notes

By default compose=True, the minimal polynomial of the subexpressions of ex are com-

puted, then the arithmetic operations on them are performed using the resultant and
factorization. If compose=False, a bottom-up algorithm is used with groebner. The de-
fault algorithm stalls less frequently.
If no ground domain is given, it will be generated automatically from the expression.

Examples

>>> from sympy import minimal_polynomial, sqrt, solve, QQ

>>> from sympy.abc import x, y

5.19. Polynomials Manipulation Module 891

SymPy Documentation, Release 1.3

>>> minimal_polynomial(sqrt(2), x)
x**2 - 2
>>> minimal_polynomial(sqrt(2), x, domain=QQ.algebraic_field(sqrt(2)))
x - sqrt(2)
>>> minimal_polynomial(sqrt(2) + sqrt(3), x)
x**4 - 10*x**2 + 1
>>> minimal_polynomial(solve(x**3 + x + 3)[0], x)
x**3 + x + 3
>>> minimal_polynomial(sqrt(y), x)
x**2 - y

sympy.polys.numberfields.minpoly(ex, x=None, compose=True, polys=False, do-

main=None)
Computes the minimal polynomial of an algebraic element.
Parameters ex : Expr
Element or expression whose minimal polynomial is to be calculated.
x : Symbol, optional
Independent variable of the minimal polynomial
compose : boolean, optional (default=True)
Method to use for computing minimal polynomial. If compose=True
(default) then _minpoly_compose is used, if compose=False then
groebner bases are used.
polys : boolean, optional (default=False)
If True returns a Poly object else an Expr object.
domain : Domain, optional
Ground domain

Notes

By default compose=True, the minimal polynomial of the subexpressions of ex are com-

puted, then the arithmetic operations on them are performed using the resultant and
factorization. If compose=False, a bottom-up algorithm is used with groebner. The de-
fault algorithm stalls less frequently.
If no ground domain is given, it will be generated automatically from the expression.

Examples

>>> from sympy import minimal_polynomial, sqrt, solve, QQ

>>> from sympy.abc import x, y

>>> minimal_polynomial(sqrt(2), x)
x**2 - 2
>>> minimal_polynomial(sqrt(2), x, domain=QQ.algebraic_field(sqrt(2)))
x - sqrt(2)
>>> minimal_polynomial(sqrt(2) + sqrt(3), x)
x**4 - 10*x**2 + 1
(continues on next page)

892 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> minimal_polynomial(solve(x**3 + x + 3)[0], x)
x**3 + x + 3
>>> minimal_polynomial(sqrt(y), x)
x**2 - y

sympy.polys.numberfields.primitive_element(extension, x=None, **args)

Construct a common number field for all extensions.
sympy.polys.numberfields.field_isomorphism(a, b, **args)
Construct an isomorphism between two number fields.
sympy.polys.numberfields.to_number_field(extension, theta=None, **args)
Express extension in the field generated by theta.
sympy.polys.numberfields.isolate(alg, eps=None, fast=False)
Give a rational isolating interval for an algebraic number.
class sympy.polys.numberfields.AlgebraicNumber
Class for representing algebraic numbers in SymPy.
as_expr(x=None)
Create a Basic expression from self.
as_poly(x=None)
Create a Poly instance from self.
coeffs()
Returns all SymPy coefficients of an algebraic number.
is_aliased
Returns True if alias was set.
native_coeffs()
Returns all native coefficients of an algebraic number.
to_algebraic_integer()
Convert self to an algebraic integer.

Monomials encoded as tuples

class sympy.polys.monomials.Monomial(monom, gens=None)

Class representing a monomial, i.e. a product of powers.
sympy.polys.monomials.itermonomials(variables, max_degree, min_degree=0)
Generate a set of monomials of the degree greater than or equal to mind egree and less
than or equal to maxd egree.
Given a set of variables V and a min_degree N and a max_degree M generate a set of
monomials of degree less than or equal to N and greater than or equal to M . The total
number of monomials in commutative variables is huge and is given by the following
formula if M = 0:
(#V + N )!
#V !N !
For example if we would like to generate a dense polynomial of a total degree N = 50
and M = 0, which is the worst case, in 5 variables, assuming that exponents and all
of coefficients are 32-bit long and stored in an array we would need almost 80 GiB of
memory! Fortunately most polynomials, that we will encounter, are sparse.

5.19. Polynomials Manipulation Module 893

SymPy Documentation, Release 1.3

Examples

Consider monomials in commutative variables x and y and non-commutative variables a

and b:

>>> from sympy import symbols

>>> from sympy.polys.monomials import itermonomials
>>> from sympy.polys.orderings import monomial_key
>>> from sympy.abc import x, y

>>> sorted(itermonomials([x, y], 2), key=monomial_key('grlex', [y, x]))

[1, x, y, x**2, x*y, y**2]

>>> sorted(itermonomials([x, y], 3), key=monomial_key('grlex', [y, x]))

[1, x, y, x**2, x*y, y**2, x**3, x**2*y, x*y**2, y**3]

>>> a, b = symbols('a, b', commutative=False)

>>> itermonomials([a, b, x], 2)
{1, a, a**2, b, b**2, x, x**2, a*b, b*a, x*a, x*b}

>>> sorted(itermonomials([x, y], 2, 1), key=monomial_key('grlex', [y, x]))

[x, y, x**2, x*y, y**2]

sympy.polys.monomials.monomial_count(V, N)
Computes the number of monomials.
The number of monomials is given by the following formula:

(#V + N )!
#V !N !
where N is a total degree and V is a set of variables.

Examples

>>> from sympy.polys.monomials import itermonomials, monomial_count

>>> from sympy.polys.orderings import monomial_key
>>> from sympy.abc import x, y

>>> monomial_count(2, 2)
6

>>> M = itermonomials([x, y], 2)

>>> sorted(M, key=monomial_key('grlex', [y, x]))

[1, x, y, x**2, x*y, y**2]
>>> len(M)
6

Orderings of monomials

class sympy.polys.orderings.LexOrder
Lexicographic order of monomials.

894 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.polys.orderings.GradedLexOrder
Graded lexicographic order of monomials.
class sympy.polys.orderings.ReversedGradedLexOrder
Reversed graded lexicographic order of monomials.

Formal manipulation of roots of polynomials

sympy.polys.rootoftools.rootof(f, x, index=None, radicals=True, expand=True)

An indexed root of a univariate polynomial.
Returns either a ComplexRootOf object or an explicit expression involving radicals.
Parameters f : Expr
Univariate polynomial.
x : Symbol, optional
Generator for f.
index : int or Integer
radicals : bool
Return a radical expression if possible.
expand : bool
Expand f.
class sympy.polys.rootoftools.RootOf
Represents a root of a univariate polynomial.
Base class for roots of different kinds of polynomials. Only complex roots are currently
supported.
class sympy.polys.rootoftools.ComplexRootOf
Represents an indexed complex root of a polynomial.
Roots of a univariate polynomial separated into disjoint real or complex intervals and in-
dexed in a fixed order. Currently only rational coefficients are allowed. Can be imported
as CRootOf.
See also:
eval_approx, eval_rational, _eval_evalf

Examples

>>> from sympy import CRootOf, rootof

>>> from sympy.abc import x

CRootOf is a way to reference a particular root of a polynomial. If there is a rational

root, it will be returned:

>>> CRootOf.clear_cache() # for doctest reproducibility

>>> CRootOf(x**2 - 4, 0)
-2

5.19. Polynomials Manipulation Module 895

SymPy Documentation, Release 1.3

Whether roots involving radicals are returned or not depends on whether the radicals
flag is true (which is set to True with rootof):
>>> CRootOf(x**2 - 3, 0)
CRootOf(x**2 - 3, 0)
>>> CRootOf(x**2 - 3, 0, radicals=True)
-sqrt(3)
>>> rootof(x**2 - 3, 0)
-sqrt(3)

The following cannot be expressed in terms of radicals:

>>> r = rootof(4*x**5 + 16*x**3 + 12*x**2 + 7, 0); r
CRootOf(4*x**5 + 16*x**3 + 12*x**2 + 7, 0)

The root bounds can be seen, however, and they are used by the evaluation methods to
get numerical approximations for the root.
>>> interval = r._get_interval(); interval
(-1, 0)
>>> r.evalf(2)
-0.98

The evalf method refines the width of the root bounds until it guarantees that any decimal
approximation within those bounds will satisfy the desired precision. It then stores the
refined interval so subsequent requests at or below the requested precision will not have
to recompute the root bounds and will return very quickly.
Before evaluation above, the interval was
>>> interval
(-1, 0)

After evaluation it is now

>>. r._get_interval() (-165/169, -206/211)
To reset all intervals for a given polynomial, the r eset method can be called from any
CRootOf instance of the polynomial:
>>> r._reset()
>>> r._get_interval()
(-1, 0)

The evala pprox method will also find the root to a given precision but the interval is not
modified unless the search for the root fails to converge within the root bounds. And
the secant method is used to find the root. (The evalf method uses bisection and will
always update the interval.)
>>> r.eval_approx(2)
-0.98

The interval needed to be slightly updated to find that root:

>>> r._get_interval()
(-1, -1/2)

The evalf_rational will compute a rational approximation of the root to the desired
accuracy or precision.

896 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> r.eval_rational(n=2)
-69629/71318

>>> t = CRootOf(x**3 + 10*x + 1, 1)

>>> t.eval_rational(1e-1)
15/256 - 805*I/256
>>> t.eval_rational(1e-1, 1e-4)
3275/65536 - 414645*I/131072
>>> t.eval_rational(1e-4, 1e-4)
6545/131072 - 414645*I/131072
>>> t.eval_rational(n=2)
104755/2097152 - 6634255*I/2097152

class sympy.polys.rootoftools.RootSum
Represents a sum of all roots of a univariate polynomial.

Symbolic root-finding algorithms

sympy.polys.polyroots.roots(f, *gens, **flags)

Computes symbolic roots of a univariate polynomial.
Given a univariate polynomial f with symbolic coefficients (or a list of the polynomial’s
coefficients), returns a dictionary with its roots and their multiplicities.
Only roots expressible via radicals will be returned. To get a complete set of roots use
RootOf class or numerical methods instead. By default cubic and quartic formulas are
used in the algorithm. To disable them because of unreadable output set cubics=False
or quartics=False respectively. If cubic roots are real but are expressed in terms of
complex numbers (casus irreducibilis [1]) the trig flag can be set to True to have the
solutions returned in terms of cosine and inverse cosine functions.
To get roots from a specific domain set the filter flag with one of the following spec-
ifiers: Z, Q, R, I, C. By default all roots are returned (this is equivalent to setting fil-
ter='C').
By default a dictionary is returned giving a compact result in case of multiple roots.
However to get a list containing all those roots set the multiple flag to True; the list
will have identical roots appearing next to each other in the result. (For a given Poly, the
all_roots method will give the roots in sorted numerical order.)

References

1. http://en.wikipedia.org/wiki/Cubic_function#Trigonometric_.28and_hyperbolic.29_
method

Examples

>>> from sympy import Poly, roots

>>> from sympy.abc import x, y

>>> roots(x**2 - 1, x)
{-1: 1, 1: 1}

5.19. Polynomials Manipulation Module 897

SymPy Documentation, Release 1.3

>>> p = Poly(x**2-1, x)
>>> roots(p)
{-1: 1, 1: 1}

>>> p = Poly(x**2-y, x, y)

>>> roots(Poly(p, x))

{-sqrt(y): 1, sqrt(y): 1}

>>> roots(x**2 - y, x)
{-sqrt(y): 1, sqrt(y): 1}

>>> roots([1, 0, -1])

{-1: 1, 1: 1}

Special polynomials

sympy.polys.specialpolys.swinnerton_dyer_poly(n, x=None, polys=False)

Generates n-th Swinnerton-Dyer polynomial in x.
Parameters n : int
n decides the order of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.specialpolys.interpolating_poly(n, x, X=’x’, Y=’y’)
Construct Lagrange interpolating polynomial for n data points.
sympy.polys.specialpolys.cyclotomic_poly(n, x=None, polys=False)
Generates cyclotomic polynomial of order n in x.
Parameters n : int
n decides the order of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.specialpolys.symmetric_poly(n, *gens, **args)
Generates symmetric polynomial of order n.
Returns a Poly object when polys=True, otherwise (default) returns an expression.
sympy.polys.specialpolys.random_poly(x, n, inf, sup, domain=ZZ, polys=False)
Generates a polynomial of degree n with coefficients in [inf, sup].
Parameters x
x is the independent term of polynomial

898 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

n : int
n decides the order of polynomial
inf
Lower limit of range in which coefficients lie
sup
Upper limit of range in which coefficients lie
domain : optional
Decides what ring the coefficients are supposed to belong. Default is
set to Integers.
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.

Orthogonal polynomials

sympy.polys.orthopolys.chebyshevt_poly(n, x=None, polys=False)

Generates Chebyshev polynomial of the first kind of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.orthopolys.chebyshevu_poly(n, x=None, polys=False)
Generates Chebyshev polynomial of the second kind of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.orthopolys.gegenbauer_poly(n, a, x=None, polys=False)
Generates Gegenbauer polynomial of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
a
Decides minimal domain for the list of coefficients.
polys : bool, optional

5.19. Polynomials Manipulation Module 899

SymPy Documentation, Release 1.3

polys=True returns an expression, otherwise (default) returns an ex-

pression.
sympy.polys.orthopolys.hermite_poly(n, x=None, polys=False)
Generates Hermite polynomial of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.orthopolys.jacobi_poly(n, a, b, x=None, polys=False)
Generates Jacobi polynomial of degree n in x.
Parameters n : int
n decides the degree of polynomial
a
Lower limit of minimal domain for the list of coefficients.
b
Upper limit of minimal domain for the list of coefficients.
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.orthopolys.legendre_poly(n, x=None, polys=False)
Generates Legendre polynomial of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
polys : bool, optional
polys=True returns an expression, otherwise (default) returns an ex-
pression.
sympy.polys.orthopolys.laguerre_poly(n, x=None, alpha=None, polys=False)
Generates Laguerre polynomial of degree n in x.
Parameters n : int
n decides the degree of polynomial
x : optional
alpha
Decides minimal domain for the list of coefficients.
polys : bool, optional

900 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

polys=True returns an expression, otherwise (default) returns an ex-

pression.

Manipulation of rational functions

sympy.polys.rationaltools.together(expr, deep=False)
Denest and combine rational expressions using symbolic methods.
This function takes an expression or a container of expressions and puts it (them) to-
gether by denesting and combining rational subexpressions. No heroic measures are
taken to minimize degree of the resulting numerator and denominator. To obtain com-
pletely reduced expression use cancel(). However, together() (page 901) can pre-
serve as much as possible of the structure of the input expression in the output (no
expansion is performed).
A wide variety of objects can be put together including lists, tuples, sets, relational ob-
jects, integrals and others. It is also possible to transform interior of function applica-
tions, by setting deep flag to True.
By definition, together() (page 901) is a complement to apart(), so
apart(together(expr)) should return expr unchanged. Note however, that to-
gether() (page 901) uses only symbolic methods, so it might be necessary to use
cancel() to perform algebraic simplification and minimize degree of the numerator and
denominator.

Examples

>>> from sympy import together, exp

>>> from sympy.abc import x, y, z

>>> together(1/x + 1/y)

(x + y)/(x*y)
>>> together(1/x + 1/y + 1/z)
(x*y + x*z + y*z)/(x*y*z)

>>> together(1/(x*y) + 1/y**2)

(x + y)/(x*y**2)

>>> together(1/(1 + 1/x) + 1/(1 + 1/y))

(x*(y + 1) + y*(x + 1))/((x + 1)*(y + 1))

>>> together(exp(1/x + 1/y))

exp(1/y + 1/x)
>>> together(exp(1/x + 1/y), deep=True)
exp((x + y)/(x*y))

>>> together(1/exp(x) + 1/(x*exp(x)))

(x + 1)*exp(-x)/x

>>> together(1/exp(2*x) + 1/(x*exp(3*x)))

(x*exp(x) + 1)*exp(-3*x)/x

5.19. Polynomials Manipulation Module 901

SymPy Documentation, Release 1.3

Partial fraction decomposition

sympy.polys.partfrac.apart(f, x=None, full=False, **options)

Compute partial fraction decomposition of a rational function.
Given a rational function f, computes the partial fraction decomposition of f. Two algo-
rithms are available: One is based on the undertermined coefficients method, the other
is Bronstein’s full partial fraction decomposition algorithm.
The undetermined coefficients method (selected by full=False) uses polynomial fac-
torization (and therefore accepts the same options as factor) for the denominator. Per
default it works over the rational numbers, therefore decomposition of denominators
with non-rational roots (e.g. irrational, complex roots) is not supported by default (see
options of factor).
Bronstein’s algorithm can be selected by using full=True and allows a decomposition
of denominators with non-rational roots. A human-readable result can be obtained via
doit() (see examples below).
See also:
apart_list (page 902), assemble_partfrac_list (page 904)

Examples

>>> from sympy.polys.partfrac import apart

>>> from sympy.abc import x, y

By default, using the undetermined coefficients method:

>>> apart(y/(x + 2)/(x + 1), x)

-y/(x + 2) + y/(x + 1)

The undetermined coefficients method does not provide a result when the denominators
roots are not rational:

>>> apart(y/(x**2 + x + 1), x)

y/(x**2 + x + 1)

You can choose Bronstein’s algorithm by setting full=True:

>>> apart(y/(x**2 + x + 1), x, full=True)

RootSum(_w**2 + _w + 1, Lambda(_a, (-2*_a*y/3 - y/3)/(-_a + x)))

Calling doit() yields a human-readable result:

>>> apart(y/(x**2 + x + 1), x, full=True).doit()

(-y/3 - 2*y*(-1/2 - sqrt(3)*I/2)/3)/(x + 1/2 + sqrt(3)*I/2) + (-y/3 -
2*y*(-1/2 + sqrt(3)*I/2)/3)/(x + 1/2 - sqrt(3)*I/2)

sympy.polys.partfrac.apart_list(f, x=None, dummies=None, **options)

Compute partial fraction decomposition of a rational function and return the result in
structured form.
Given a rational function f compute the partial fraction decomposition of f. Only Bron-
stein’s full partial fraction decomposition algorithm is supported by this method. The

902 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

return value is highly structured and perfectly suited for further algorithmic treatment
rather than being human-readable. The function returns a tuple holding three elements:
• The first item is the common coefficient, free of the variable x used for decomposi-
tion. (It is an element of the base field K.)
• The second item is the polynomial part of the decomposition. This can be the zero
polynomial. (It is an element of K[x].)
• The third part itself is a list of quadruples. Each quadruple has the following ele-
ments in this order:
– The (not necessarily irreducible) polynomial D whose roots wi appear in the lin-
ear denominator of a bunch of related fraction terms. (This item can also be a
list of explicit roots. However, at the moment apart_list never returns a result
this way, but the related assemble_partfrac_list function accepts this format
as input.)
– The numerator of the fraction, written as a function of the root w
– The linear denominator of the fraction excluding its power exponent, written as
a function of the root w.
– The power to which the denominator has to be raised.
On can always rebuild a plain expression by using the function assem-
ble_partfrac_list.
See also:
apart (page 902), assemble_partfrac_list (page 904)

References

1. [Bronstein93]

[Bronstein93]

Examples

A first example:

>>> from sympy.polys.partfrac import apart_list, assemble_partfrac_list

>>> from sympy.abc import x, t

>>> f = (2*x**3 - 2*x) / (x**2 - 2*x + 1)

>>> pfd = apart_list(f)
>>> pfd
(1,
Poly(2*x + 4, x, domain='ZZ'),
[(Poly(_w - 1, _w, domain='ZZ'), Lambda(_a, 4), Lambda(_a, -_a + x), 1)])

>>> assemble_partfrac_list(pfd)
2*x + 4 + 4/(x - 1)

Second example:

5.19. Polynomials Manipulation Module 903

SymPy Documentation, Release 1.3

>>> f = (-2*x - 2*x**2) / (3*x**2 - 6*x)

>>> pfd = apart_list(f)
>>> pfd
(-1,
Poly(2/3, x, domain='QQ'),
[(Poly(_w - 2, _w, domain='ZZ'), Lambda(_a, 2), Lambda(_a, -_a + x), 1)])

>>> assemble_partfrac_list(pfd)
-2/3 - 2/(x - 2)

Another example, showing symbolic parameters:

>>> pfd = apart_list(t/(x**2 + x + t), x)

>>> pfd
(1,
Poly(0, x, domain='ZZ[t]'),
[(Poly(_w**2 + _w + t, _w, domain='ZZ[t]'),
Lambda(_a, -2*_a*t/(4*t - 1) - t/(4*t - 1)),
Lambda(_a, -_a + x),
1)])

>>> assemble_partfrac_list(pfd)
RootSum(_w**2 + _w + t, Lambda(_a, (-2*_a*t/(4*t - 1) - t/(4*t - 1))/(-_a + x)))

This example is taken from Bronstein’s original paper:

>>> f = 36 / (x**5 - 2*x**4 - 2*x**3 + 4*x**2 + x - 2)

>>> pfd = apart_list(f)
>>> pfd
(1,
Poly(0, x, domain='ZZ'),
[(Poly(_w - 2, _w, domain='ZZ'), Lambda(_a, 4), Lambda(_a, -_a + x), 1),
(Poly(_w**2 - 1, _w, domain='ZZ'), Lambda(_a, -3*_a - 6), Lambda(_a, -_a + x), 2),
(Poly(_w + 1, _w, domain='ZZ'), Lambda(_a, -4), Lambda(_a, -_a + x), 1)])

>>> assemble_partfrac_list(pfd)
-4/(x + 1) - 3/(x + 1)**2 - 9/(x - 1)**2 + 4/(x - 2)

sympy.polys.partfrac.assemble_partfrac_list(partial_list)
Reassemble a full partial fraction decomposition from a structured result obtained by
the function apart_list.
See also:
apart (page 902), apart_list (page 902)

Examples

This example is taken from Bronstein’s original paper:

>>> from sympy.polys.partfrac import apart_list, assemble_partfrac_list

>>> from sympy.abc import x, y

904 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> f = 36 / (x**5 - 2*x**4 - 2*x**3 + 4*x**2 + x - 2)

>>> pfd = apart_list(f)
>>> pfd
(1,
Poly(0, x, domain='ZZ'),
[(Poly(_w - 2, _w, domain='ZZ'), Lambda(_a, 4), Lambda(_a, -_a + x), 1),
(Poly(_w**2 - 1, _w, domain='ZZ'), Lambda(_a, -3*_a - 6), Lambda(_a, -_a + x), 2),
(Poly(_w + 1, _w, domain='ZZ'), Lambda(_a, -4), Lambda(_a, -_a + x), 1)])

>>> assemble_partfrac_list(pfd)
-4/(x + 1) - 3/(x + 1)**2 - 9/(x - 1)**2 + 4/(x - 2)

If we happen to know some roots we can provide them easily inside the structure:

>>> pfd = apart_list(2/(x**2-2))

>>> pfd
(1,
Poly(0, x, domain='ZZ'),
[(Poly(_w**2 - 2, _w, domain='ZZ'),
Lambda(_a, _a/2),
Lambda(_a, -_a + x),
1)])

>>> pfda = assemble_partfrac_list(pfd)

>>> pfda
RootSum(_w**2 - 2, Lambda(_a, _a/(-_a + x)))/2

>>> pfda.doit()
-sqrt(2)/(2*(x + sqrt(2))) + sqrt(2)/(2*(x - sqrt(2)))

>>> from sympy import Dummy, Poly, Lambda, sqrt

>>> a = Dummy(”a”)
>>> pfd = (1, Poly(0, x, domain='ZZ'), [([sqrt(2),-sqrt(2)], Lambda(a, a/2),␣
,→Lambda(a, -a + x), 1)])

>>> assemble_partfrac_list(pfd)
-sqrt(2)/(2*(x + sqrt(2))) + sqrt(2)/(2*(x - sqrt(2)))

Dispersion of Polynomials

sympy.polys.dispersion.dispersionset(p, q=None, *gens, **args)

Compute the dispersion set of two polynomials.
For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion set J(f, g) is
defined as:
J(f, g) := {a ∈ N0 | gcd(f (x), g(x + a)) ̸= 1}
= {a ∈ N0 | deg gcd(f (x), g(x + a)) ≥ 1}

For a single polynomial one defines J(f ) := J(f, f ).

See also:
dispersion (page 833)

5.19. Polynomials Manipulation Module 905

SymPy Documentation, Release 1.3

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)

>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

Note that the definition of the dispersion is not symmetric:

>>> fp = poly(x**4 - 3*x**2 + 1, x)

>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

Computing the dispersion also works over field extensions:

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 + 2*a)*x, x)
>>> sorted(dispersionset(fp))
[0, 1]

906 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.dispersion.dispersion(p, q=None, *gens, **args)

Compute the dispersion of polynomials.
For two polynomials f (x) and g(x) with deg f > 0 and deg g > 0 the dispersion dis(f, g) is
defined as:
dis(f, g) := max{J(f, g) ∪ {0}}
= max{{a ∈ N| gcd(f (x), g(x + a)) ̸= 1} ∪ {0}}

and for a single polynomial dis(f ) := dis(f, f ). Note that we make the definition max{} :=
−∞.
See also:
dispersionset (page 835)

References

1. [ManWright94]
2. [Koepf98]
3. [Abramov71]
4. [Man93]

[ManWright94], [Koepf98], [Abramov71], [Man93]

Examples

>>> from sympy import poly

>>> from sympy.polys.dispersion import dispersion, dispersionset
>>> from sympy.abc import x

Dispersion set and dispersion of a simple polynomial:

>>> fp = poly((x - 3)*(x + 3), x)
>>> sorted(dispersionset(fp))
[0, 6]
>>> dispersion(fp)
6

Note that the definition of the dispersion is not symmetric:

>>> fp = poly(x**4 - 3*x**2 + 1, x)
>>> gp = fp.shift(-3)
>>> sorted(dispersionset(fp, gp))
[2, 3, 4]
>>> dispersion(fp, gp)
4
>>> sorted(dispersionset(gp, fp))
[]
>>> dispersion(gp, fp)
-oo

The maximum of an empty set is defined to be −∞ as seen in this example.

Computing the dispersion also works over field extensions:

5.19. Polynomials Manipulation Module 907

SymPy Documentation, Release 1.3

>>> from sympy import sqrt

>>> fp = poly(x**2 + sqrt(5)*x - 1, x, domain='QQ<sqrt(5)>')
>>> gp = poly(x**2 + (2 + sqrt(5))*x + sqrt(5), x, domain='QQ<sqrt(5)>')
>>> sorted(dispersionset(fp, gp))
[2]
>>> sorted(dispersionset(gp, fp))
[1, 4]

We can even perform the computations for polynomials having symbolic coefficients:

>>> from sympy.abc import a

>>> fp = poly(4*x**4 + (4*a + 8)*x**3 + (a**2 + 6*a + 4)*x**2 + (a**2 + 2*a)*x, x)
>>> sorted(dispersionset(fp))
[0, 1]

AGCA - Algebraic Geometry and Commutative Algebra Module

Introduction

Algebraic geometry is a mixture of the ideas of two Mediterranean cultures. It is

the superposition of the Arab science of the lightening calculation of the solutions
of equations over the Greek art of position and shape. This tapestry was originally
woven on European soil and is still being refined under the influence of international
fashion. Algebraic geometry studies the delicate balance between the geometrically
plausible and the algebraically possible. Whenever one side of this mathematical
teeter-totter outweighs the other, one immediately loses interest and runs off in
search of a more exciting amusement.
George R. Kempf 1944 – 2002
Algebraic Geometry refers to the study of geometric problems via algebraic methods (and
sometimes vice versa). While this is a rather old topic, algebraic geometry as understood
today is very much a 20th century development. Building on ideas of e.g. Riemann and
Dedekind, it was realized that there is an intimate connection between properties of the set
of solutions of a system of polynomial equations (called an algebraic variety) and the behavior
of the set of polynomial functions on that variety (called the coordinate ring).
As in many geometric disciplines, we can distinguish between local and global questions (and
methods). Local investigations in algebraic geometry are essentially equivalent to the study of
certain rings, their ideals and modules. This latter topic is also called commutative algebra.
It is the basic local toolset of algebraic geometers, in much the same way that differential
analysis is the local toolset of differential geometers.
A good conceptual introduction to commutative algebra is [Atiyah69]. An introduction more
geared towards computations, and the work most of the algorithms in this module are based
on, is [Greuel2008].
This module aims to eventually allow expression and solution of both local and global geo-
metric problems, both in the classical case over a field and in the more modern arithmetic
cases. So far, however, there is no geometric functionality at all. Currently the module only
provides tools for computational commutative algebra over fields.
All code examples assume:

908 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import *

>>> x, y, z = symbols('x,y,z')
>>> init_printing(use_unicode=True, wrap_line=False)

Reference

In this section we document the usage of the AGCA module. For convenience of the reader,
some definitions and examples/explanations are interspersed.

Base Rings

Almost all computations in commutative algebra are relative to a “base ring”. (For example,
when asking questions about an ideal, the base ring is the ring the ideal is a subset of.) In
principle all polys “domains” can be used as base rings. However, useful functionality is only
implemented for polynomial rings over fields, and various localizations and quotients thereof.
As demonstrated in the examples below, the most convenient method to create objects you
are interested in is to build them up from the ground field, and then use the various methods
to create new objects from old. For example, in order to create the local ring of the nodal
cubic y 2 = x3 at the origin, over Q, you do:

>>> lr = QQ.old_poly_ring(x, y, order=”ilex”) / [y**2 - x**3]

>>> lr
ℚ[x, y, order=ilex]
───────────────────
╱ 3 2╲
╲- x + y ╱

Note how the python list notation can be used as a short cut to express ideals. You can use
the convert method to return ordinary sympy objects into objects understood by the AGCA
module (although in many cases this will be done automatically – for example the list was
automatically turned into an ideal, and in the process the symbols x and y were automatically
converted into other representations). For example:

>>> X, Y = lr.convert(x), lr.convert(y) ; X

╱ 3 2╲
x + ╲- x + y ╱

>>> x**3 == y**2

False

>>> X**3 == Y**2

True

When no localisation is needed, a more mathematical notation can be used. For example, let
us create the coordinate ring of three-dimensional affine space A3 :

>>> ar = QQ.old_poly_ring(x, y, z); ar

ℚ[x, y, z]

For more details, refer to the following class documentation. Note that the base rings, being
domains, are the main point of overlap between the AGCA module and the rest of the polys

5.19. Polynomials Manipulation Module 909

SymPy Documentation, Release 1.3

module. All domains are documented in detail in the polys reference, so we show here only
an abridged version, with the methods most pertinent to the AGCA module.
class sympy.polys.domains.ring.Ring
Represents a ring domain.

Attributes

alias
dtype
one
rep
zero

free_module(rank)
Generate a free module of rank rank over self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2)
QQ[x]**2

ideal(*gens)
Generate an ideal of self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).ideal(x**2)
<x**2>

quotient_ring(e)
Form a quotient ring of self.
Here e can be an ideal or an iterable.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).quotient_ring(QQ.old_poly_ring(x).ideal(x**2))
QQ[x]/<x**2>
>>> QQ.old_poly_ring(x).quotient_ring([x**2])
QQ[x]/<x**2>

The division operator has been overloaded for this:

>>> QQ.old_poly_ring(x)/[x**2]
QQ[x]/<x**2>

sympy.polys.domains.polynomialring.PolynomialRing(domain_or_ring, sym-
bols=None, order=None)
A class for representing multivariate polynomial rings.

910 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

alias
domain
dtype
gens
ngens
rep
symbols

class sympy.polys.domains.quotientring.QuotientRing(ring, ideal)

Class representing (commutative) quotient rings.
You should not usually instantiate this by hand, instead use the constructor from the
base ring in the construction.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> I = QQ.old_poly_ring(x).ideal(x**3 + 1)
>>> QQ.old_poly_ring(x).quotient_ring(I)
QQ[x]/<x**3 + 1>

Shorter versions are possible:

>>> QQ.old_poly_ring(x)/I
QQ[x]/<x**3 + 1>

>>> QQ.old_poly_ring(x)/[x**3 + 1]
QQ[x]/<x**3 + 1>

Attributes:
• ring - the base ring
• base_ideal - the ideal used to form the quotient

Attributes

alias
one
rep
zero

Modules, Ideals and their Elementary Properties

Let A be a ring. An A-module is a set M , together with two binary operations + : M × M → M

and × : R × M → M called addition and scalar multiplication. These are required to satisfy
certain axioms, which can be found in e.g. [Atiyah69]. In this way modules are a direct
generalisation of both vector spaces (A being a field) and abelian groups (A = Z). A submodule
of the A-module M is a subset N ⊂ M , such that the binary operations restrict to N , and N
becomes an A-module with these operations.

5.19. Polynomials Manipulation Module 911

SymPy Documentation, Release 1.3

The ring A itself has a natural A-module structure where addition and multiplication in the
module coincide with addition and multiplication in the ring. This A-module is also written as
A. An A-submodule of A is called an ideal of A. Ideals come up very naturally in algebraic ge-
ometry. More general modules can be seen as a technically convenient “elbow room” beyond
talking only about ideals.
If M , N are A-modules, then there is a natural (componentwise) A-module structure on M × N .
Similarly there are A-module structures on cartesian products of more components. (For
the categorically inclined: the cartesian product of finitely many A-modules, with this A-
module structure, is the finite biproduct in the category of all A-modules. With infinitely
many components, it is the direct product (but the infinite direct sum has to be constructed
differently).) As usual, repeated product of the A-module M is denoted M, M 2 , M 3 . . ., or M I
for arbitrary index sets I.
An A-module M is called free if it is isomorphic to the A-module AI for some (not necessarily
finite) index set I (refer to the next section for a definition of isomorphism). The cardinality
of I is called the rank of M ; one may prove this is well-defined. In general, the AGCA module
only works with free modules of finite rank, and other closely related modules. The easiest
way to create modules is to use member methods of the objects they are made up from. For
example, let us create a free module of rank 4 over the coordinate ring of A2 we created above,
together with a submodule:

>>> F = ar.free_module(4) ; F
4
ℚ[x, y, z]

>>> S = F.submodule([1, x, x**2, x**3], [0, 1, 0, y]) ; S

╱⎡ 2 3⎤ ╲
╲⎣1, x, x , x ⎦, [0, 1, 0, y]╱

Note how python lists can be used as a short-cut notation for module elements (vectors). As
usual, the convert method can be used to convert sympy/python objects into the internal
AGCA representation (see detailed reference below).
Here is the detailed documentation of the classes for modules, free modules, and submodules:

class sympy.polys.agca.modules.Module(ring)
Abstract base class for modules.
Do not instantiate - use ring explicit constructors instead:

>>> from sympy import QQ

>>> from sympy.abc import x
>>> QQ.old_poly_ring(x).free_module(2)
QQ[x]**2

Attributes:
• dtype - type of elements
• ring - containing ring
Non-implemented methods:
• submodule
• quotient_module
• is_zero

912 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• is_submodule
• multiply_ideal
The method convert likely needs to be changed in subclasses.
contains(elem)
Return True if elem is an element of this module.
convert(elem, M=None)
Convert elem into internal representation of this module.
If M is not None, it should be a module containing it.
identity_hom()
Return the identity homomorphism on self.
is_submodule(other)
Returns True if other is a submodule of self.
is_zero()
Returns True if self is a zero module.
multiply_ideal(other)
Multiply self by the ideal other.
quotient_module(other)
Generate a quotient module.
submodule(*gens)
Generate a submodule.
subset(other)
Returns True if other is is a subset of self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.subset([(1, x), (x, 2)])
True
>>> F.subset([(1/x, x), (x, 2)])
False

class sympy.polys.agca.modules.FreeModule(ring, rank)

Abstract base class for free modules.
Additional attributes:
• rank - rank of the free module
Non-implemented methods:
• submodule
basis()
Return a set of basis elements.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(3).basis()
([1, 0, 0], [0, 1, 0], [0, 0, 1])

convert(elem, M=None)
Convert elem into the internal representation.

5.19. Polynomials Manipulation Module 913

SymPy Documentation, Release 1.3

This method is called implicitly whenever computations involve elements not in the
internal representation.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.convert([1, 0])
[1, 0]

dtype
alias of FreeModuleElement
identity_hom()
Return the identity homomorphism on self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2).identity_hom()
Matrix([
[1, 0], : QQ[x]**2 -> QQ[x]**2
[0, 1]])

is_submodule(other)
Returns True if other is a submodule of self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> M = F.submodule([2, x])
>>> F.is_submodule(F)
True
>>> F.is_submodule(M)
True
>>> M.is_submodule(F)
False

is_zero()
Returns True if self is a zero module.
(If, as this implementation assumes, the coefficient ring is not the zero ring, then
this is equivalent to the rank being zero.)

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(0).is_zero()
True
>>> QQ.old_poly_ring(x).free_module(1).is_zero()
False

multiply_ideal(other)
Multiply self by the ideal other.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> I = QQ.old_poly_ring(x).ideal(x)
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.multiply_ideal(I)
<[x, 0], [0, x]>

914 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

quotient_module(submodule)
Return a quotient module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = QQ.old_poly_ring(x).free_module(2)
>>> M.quotient_module(M.submodule([1, x], [x, 2]))
QQ[x]**2/<[1, x], [x, 2]>

Or more conicisely, using the overloaded division operator:

>>> QQ.old_poly_ring(x).free_module(2) / [[1, x], [x, 2]]

QQ[x]**2/<[1, x], [x, 2]>

class sympy.polys.agca.modules.SubModule(gens, container)

Base class for submodules.
Attributes:
• container - containing module
• gens - generators (subset of containing module)
• rank - rank of containing module
Non-implemented methods:
• _contains
• _syzygies
• _in_terms_of_generators
• _intersect
• _module_quotient
Methods that likely need change in subclasses:
• reduce_element
convert(elem, M=None)
Convert elem into the internal represantition.
Mostly called implicitly.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = QQ.old_poly_ring(x).free_module(2).submodule([1, x])
>>> M.convert([2, 2*x])
[2, 2*x]

identity_hom()
Return the identity homomorphism on self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2).submodule([x, x]).identity_hom()
Matrix([
[1, 0], : <[x, x]> -> <[x, x]>
[0, 1]])

5.19. Polynomials Manipulation Module 915

SymPy Documentation, Release 1.3

in_terms_of_generators(e)
Express element e of self in terms of the generators.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> M = F.submodule([1, 0], [1, 1])
>>> M.in_terms_of_generators([x, x**2])
[-x**2 + x, x**2]

inclusion_hom()
Return a homomorphism representing the inclusion map of self.
That is, the natural map from self to self.container.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2).submodule([x, x]).inclusion_hom()
Matrix([
[1, 0], : <[x, x]> -> QQ[x]**2
[0, 1]])

intersect(other, **options)
Returns the intersection of self with submodule other.

>>> from sympy.abc import x, y

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x, y).free_module(2)
>>> F.submodule([x, x]).intersect(F.submodule([y, y]))
<[x*y, x*y]>

Some implementation allow further options to be passed. Currently, to only one

implemented is relations=True, in which case the function will return a triple (res,
rela, relb), where res is the intersection module, and rela and relb are lists of
coefficient vectors, expressing the generators of res in terms of the generators of
self (rela) and other (relb).

>>> F.submodule([x, x]).intersect(F.submodule([y, y]), relations=True)

(<[x*y, x*y]>, [(y,)], [(x,)])

The above result says: the intersection module is generated by the single element
(−xy, −xy) = −y(x, x) = −x(y, y), where (x, x) and (y, y) respectively are the unique
generators of the two modules being intersected.
is_full_module()
Return True if self is the entire free module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.submodule([x, 1]).is_full_module()
False
>>> F.submodule([1, 1], [1, 2]).is_full_module()
True

is_submodule(other)
Returns True if other is a submodule of self.

916 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> M = F.submodule([2, x])
>>> N = M.submodule([2*x, x**2])
>>> M.is_submodule(M)
True
>>> M.is_submodule(N)
True
>>> N.is_submodule(M)
False

is_zero()
Return True if self is a zero module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.submodule([x, 1]).is_zero()
False
>>> F.submodule([0, 0]).is_zero()
True

module_quotient(other, **options)
Returns the module quotient of self by submodule other.
That is, if self is the module M and other is N , then return the ideal {f ∈ R|f N ⊂ M }.

>>> from sympy import QQ

>>> from sympy.abc import x, y
>>> F = QQ.old_poly_ring(x, y).free_module(2)
>>> S = F.submodule([x*y, x*y])
>>> T = F.submodule([x, x])
>>> S.module_quotient(T)
<y>

Some implementations allow further options to be passed. Currently, the only one
implemented is relations=True, which may only be passed if other is principal. In
this case the function will return a pair (res, rel) where res is the ideal, and rel
is a list of coefficient vectors, expressing the generators of the ideal, multiplied by
the generator of other in terms of generators of self.

>>> S.module_quotient(T, relations=True)

(<y>, [[1]])

This means that the quotient ideal is generated by the single element y, and that
y(x, x) = 1(xy, xy), (x, x) and (xy, xy) being the generators of T and S, respectively.
multiply_ideal(I)
Multiply self by the ideal I.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> I = QQ.old_poly_ring(x).ideal(x**2)
>>> M = QQ.old_poly_ring(x).free_module(2).submodule([1, 1])
>>> I*M
<[x**2, x**2]>

5.19. Polynomials Manipulation Module 917

SymPy Documentation, Release 1.3

quotient_module(other, **opts)
Return a quotient module.
This is the same as taking a submodule of a quotient of the containing module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> S1 = F.submodule([x, 1])
>>> S2 = F.submodule([x**2, x])
>>> S1.quotient_module(S2)
<[x, 1] + <[x**2, x]>>

Or more coincisely, using the overloaded division operator:

>>> F.submodule([x, 1]) / [(x**2, x)]

<[x, 1] + <[x**2, x]>>

reduce_element(x)
Reduce the element x of our ring modulo the ideal self.
Here “reduce” has no specific meaning, it could return a unique normal form, sim-
plify the expression a bit, or just do nothing.
submodule(*gens)
Generate a submodule.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = QQ.old_poly_ring(x).free_module(2).submodule([x, 1])
>>> M.submodule([x**2, x])
<[x**2, x]>

syzygy_module(**opts)
Compute the syzygy module of the generators of self.
Suppose M is generated by f1 , . . . , fn over the ring R. Consider the homomorphism
ϕ : Rn → M , given by sending (r1 , . . . , rn ) → r1 f1 + · · · + rn fn . The syzygy module is
defined to be the kernel of ϕ.
The syzygy module is zero iff the generators generate freely a free submodule:

>>> from sympy.abc import x, y

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2).submodule([1, 0], [1, 1]).syzygy_
,→module().is_zero()

True

A slightly more interesting example:

>>> M = QQ.old_poly_ring(x, y).free_module(2).submodule([x, 2*x], [y, 2*y])

>>> S = QQ.old_poly_ring(x, y).free_module(2).submodule([y, -x])
>>> M.syzygy_module() == S
True

union(other)
Returns the module generated by the union of self and other.

918 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(1)
>>> M = F.submodule([x**2 + x]) # <x(x+1)>
>>> N = F.submodule([x**2 - 1]) # <(x-1)(x+1)>
>>> M.union(N) == F.submodule([x+1])
True

Ideals are created very similarly to modules. For example, let’s verify that the nodal cubic is
indeed singular at the origin:

>>> I = lr.ideal(x, y)
>>> I == lr.ideal(x)
False

>>> I == lr.ideal(y)
False

We are using here the fact that a curve is non-singular at a point if and only if the maximal ideal
of the local ring is principal, and that in this case at least one of x and y must be generators.
This is the detailed documentation of the class ideal. Please note that most of the methods
regarding properties of ideals (primality etc.) are not yet implemented.
class sympy.polys.agca.ideals.Ideal(ring)
Abstract base class for ideals.
Do not instantiate - use explicit constructors in the ring class instead:

>>> from sympy import QQ

>>> from sympy.abc import x
>>> QQ.old_poly_ring(x).ideal(x+1)
<x + 1>

Attributes
• ring - the ring this ideal belongs to
Non-implemented methods:
• _contains_elem
• _contains_ideal
• _quotient
• _intersect
• _union
• _product
• is_whole_ring
• is_zero
• is_prime, is_maximal, is_primary, is_radical
• is_principal
• height, depth
• radical

5.19. Polynomials Manipulation Module 919

SymPy Documentation, Release 1.3

Methods that likely should be overridden in subclasses:

• reduce_element
contains(elem)
Return True if elem is an element of this ideal.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).ideal(x+1, x-1).contains(3)
True
>>> QQ.old_poly_ring(x).ideal(x**2, x**3).contains(x)
False

depth()
Compute the depth of self.
height()
Compute the height of self.
intersect(J)
Compute the intersection of self with ideal J.

>>> from sympy.abc import x, y

>>> from sympy import QQ
>>> R = QQ.old_poly_ring(x, y)
>>> R.ideal(x).intersect(R.ideal(y))
<x*y>

is_maximal()
Return True if self is a maximal ideal.
is_primary()
Return True if self is a primary ideal.
is_prime()
Return True if self is a prime ideal.
is_principal()
Return True if self is a principal ideal.
is_radical()
Return True if self is a radical ideal.
is_whole_ring()
Return True if self is the whole ring.
is_zero()
Return True if self is the zero ideal.
product(J)
Compute the ideal product of self and J.
That is, compute the ideal generated by products xy, for x an element of self and
y ∈ J.

>>> from sympy.abc import x, y

>>> from sympy import QQ
>>> QQ.old_poly_ring(x, y).ideal(x).product(QQ.old_poly_ring(x, y).ideal(y))
<x*y>

920 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

quotient(J, **opts)
Compute the ideal quotient of self by J.
That is, if self is the ideal I, compute the set I : J = {x ∈ R|xJ ⊂ I}.

>>> from sympy.abc import x, y

>>> from sympy import QQ
>>> R = QQ.old_poly_ring(x, y)
>>> R.ideal(x*y).quotient(R.ideal(x))
<y>

radical()
Compute the radical of self.
reduce_element(x)
Reduce the element x of our ring modulo the ideal self.
Here “reduce” has no specific meaning: it could return a unique normal form, sim-
plify the expression a bit, or just do nothing.
saturate(J)
Compute the ideal saturation of self by J.
That is, if self is the ideal I, compute the set I : J ∞ = {x ∈ R|xJ n ⊂ I for some n}.
subset(other)
Returns True if other is is a subset of self.
Here other may be an ideal.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> I = QQ.old_poly_ring(x).ideal(x+1)
>>> I.subset([x**2 - 1, x**2 + 2*x + 1])
True
>>> I.subset([x**2 + 1, x + 1])
False
>>> I.subset(QQ.old_poly_ring(x).ideal(x**2 - 1))
True

union(J)
Compute the ideal generated by the union of self and J.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).ideal(x**2 - 1).union(QQ.old_poly_ring(x).
,→ideal((x+1)**2)) == QQ.old_poly_ring(x).ideal(x+1)

True

If M is an A-module and N is an A-submodule, we can define two elements x and y of M to

be equivalent if x − y ∈ N . The set of equivalence classes is written M /N , and has a natural
A-module structure. This is called the quotient module of M by N . If K is a submodule of M
containing N , then K/N is in a natural way a submodule of M /N . Such a module is called a
subquotient. Here is the documentation of quotient and subquotient modules:
class sympy.polys.agca.modules.QuotientModule(ring, base, submodule)
Class for quotient modules.
Do not instantiate this directly. For subquotients, see the SubQuotientModule class.
Attributes:

5.19. Polynomials Manipulation Module 921

SymPy Documentation, Release 1.3

• base - the base module we are a quotient of

• killed_module - the submodule used to form the quotient
• rank of the base
convert(elem, M=None)
Convert elem into the internal representation.
This method is called implicitly whenever computations involve elements not in the
internal representation.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2) / [(1, 2), (1, x)]
>>> F.convert([1, 0])
[1, 0] + <[1, 2], [1, x]>

dtype
alias of QuotientModuleElement
identity_hom()
Return the identity homomorphism on self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = QQ.old_poly_ring(x).free_module(2) / [(1, 2), (1, x)]
>>> M.identity_hom()
Matrix([
[1, 0], : QQ[x]**2/<[1, 2], [1, x]> -> QQ[x]**2/<[1, 2], [1, x]>
[0, 1]])

is_submodule(other)
Return True if other is a submodule of self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> Q = QQ.old_poly_ring(x).free_module(2) / [(x, x)]
>>> S = Q.submodule([1, 0])
>>> Q.is_submodule(S)
True
>>> S.is_submodule(Q)
False

is_zero()
Return True if self is a zero module.
This happens if and only if the base module is the same as the submodule being
killed.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> (F/[(1, 0)]).is_zero()
False
>>> (F/[(1, 0), (0, 1)]).is_zero()
True

quotient_hom()
Return the quotient homomorphism to self.

922 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

That is, return a homomorphism representing the natural map from self.base to
self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = QQ.old_poly_ring(x).free_module(2) / [(1, 2), (1, x)]
>>> M.quotient_hom()
Matrix([
[1, 0], : QQ[x]**2 -> QQ[x]**2/<[1, 2], [1, x]>
[0, 1]])

submodule(*gens, **opts)
Generate a submodule.
This is the same as taking a quotient of a submodule of the base module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> Q = QQ.old_poly_ring(x).free_module(2) / [(x, x)]
>>> Q.submodule([x, 0])
<[x, 0] + <[x, x]>>

class sympy.polys.agca.modules.SubQuotientModule(gens, container, **opts)

Submodule of a quotient module.
Equivalently, quotient module of a submodule.
Do not instantiate this, instead use the submodule or quotient_module constructing
methods:

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> S = F.submodule([1, 0], [1, x])
>>> Q = F/[(1, 0)]
>>> S/[(1, 0)] == Q.submodule([5, x])
True

Attributes:
• base - base module we are quotient of
• killed_module - submodule used to form the quotient
is_full_module()
Return True if self is the entire free module.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> F = QQ.old_poly_ring(x).free_module(2)
>>> F.submodule([x, 1]).is_full_module()
False
>>> F.submodule([1, 1], [1, 2]).is_full_module()
True

quotient_hom()
Return the quotient homomorphism to self.
That is, return the natural map from self.base to self.

5.19. Polynomials Manipulation Module 923

SymPy Documentation, Release 1.3

>>> from sympy.abc import x

>>> from sympy import QQ
>>> M = (QQ.old_poly_ring(x).free_module(2) / [(1, x)]).submodule([1, 0])
>>> M.quotient_hom()
Matrix([
[1, 0], : <[1, 0], [1, x]> -> <[1, 0] + <[1, x]>, [1, x] + <[1, x]>>
[0, 1]])

Module Homomorphisms and Syzygies

Let M and N be A-modules. A mapping f : M → N satisfying various obvious properties (see

[Atiyah69]) is called an A-module homomorphism. In this case M is called the domain and N
the codomain. The set {x ∈ M |f (x) = 0} is called the kernel ker(f ), whereas the set {f (x)|x ∈ M }
is called the image im(f ). The kernel is a submodule of M , the image is a submodule of N . The
homomorphism f is injective if and only if ker(f ) = 0 and surjective if and only if im(f ) = N .
A bijective homomorphism is called an isomorphism. Equivalently, ker(f ) = 0 and im(f ) = N .
(A related notion, which currently has no special name in the AGCA module, is that of the
cokernel, coker(f ) = N /im(f ).)
Suppose now M is an A-module. M is called finitely generated if there exists a surjective
homomorphism An → M for some n. If such a morphism f is chosen, the images of the standard
basis of An are called the generators of M . The module ker(f ) is called syzygy module with
respect to the generators. A module is called finitely presented if it is finitely generated with
a finitely generated syzygy module. The class of finitely presented modules is essentially the
largest class we can hope to be able to meaningfully compute in.
It is an important theorem that, for all the rings we are considering, all submodules of finitely
generated modules are finitely generated, and hence finitely generated and finitely presented
modules are the same.
The notion of syzygies, while it may first seem rather abstract, is actually very computational.
This is because there exist (fairly easy) algorithms for computing them, and more general
questions (kernels, intersections, …) are often reduced to syzygy computation.
Let us say a few words about the definition of homomorphisms in the AGCA module. Suppose
first that f : M → N is an arbitrary morphism of A-modules. Then if K is a submodule of M , f
naturally defines a new homomorphism g : K → N (via g(x) = f (x)), called the restriction of f to
K. If now K contained in the kernel of f , then moreover f defines in a natural homomorphism
g : M /K → N (same formula as above!), and we say that f descends to M /K. Similarly, if L
is a submodule of N , there is a natural homomorphism g : M → N /L, we say that g factors
through f . Finally, if now L contains the image of f , then there is a natural homomorphism
g : M → L (defined, again, by the same formula), and we say g is obtained from f by restriction
of codomain. Observe also that each of these four operations is reversible, in the sense that
given g, one can always (non-uniquely) find f such that g is obtained from f in the above way.
Note that all modules implemented in AGCA are obtained from free modules by taking a
succession of submodules and quotients. Hence, in order to explain how to define a homo-
morphism between arbitrary modules, in light of the above, we need only explain how to
define homomorphisms of free modules. But, essentially by the definition of free module, a
homomorphism from a free module An to any module M is precisely the same as giving n
elements of M (the images of the standard basis), and giving an element of a free module
Am is precisely the same as giving m elements of A. Hence a homomorphism of free modules
An → Am can be specified via a matrix, entirely analogously to the case of vector spaces.
The functions restrict_domain etc. of the class Homomorphism can be used to carry out

924 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

the operations described above, and homomorphisms of free modules can in principle be
instantiated by hand. Since these operations are so common, there is a convenience function
homomorphism to define a homomorphism between arbitrary modules via the method outlined
above. It is essentially the only way homomorphisms need ever be created by the user.
sympy.polys.agca.homomorphisms.homomorphism(domain, codomain, matrix)
Create a homomorphism object.
This function tries to build a homomorphism from domain to codomain via the matrix
matrix.

Examples

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> R = QQ.old_poly_ring(x)
>>> T = R.free_module(2)

If domain is a free module generated by e1 , . . . , en , then matrix should be an n-element

iterable (b1 , . . . , bn ) where the bi are elements of codomain. The constructed homomor-
phism is the unique homomorphism sending ei to bi .

>>> F = R.free_module(2)
>>> h = homomorphism(F, T, [[1, x], [x**2, 0]])
>>> h
Matrix([
[1, x**2], : QQ[x]**2 -> QQ[x]**2
[x, 0]])
>>> h([1, 0])
[1, x]
>>> h([0, 1])
[x**2, 0]
>>> h([1, 1])
[x**2 + 1, x]

If domain is a submodule of a free module, them matrix determines a homomoprhism

from the containing free module to codomain, and the homomorphism returned is ob-
tained by restriction to domain.

>>> S = F.submodule([1, 0], [0, x])

>>> homomorphism(S, T, [[1, x], [x**2, 0]])
Matrix([
[1, x**2], : <[1, 0], [0, x]> -> QQ[x]**2
[x, 0]])

If domain is a (sub)quotient N /K, then matrix determines a homomorphism from N

to codomain. If the kernel contains K, this homomorphism descends to domain and is
returned; otherwise an exception is raised.

>>> homomorphism(S/[(1, 0)], T, [0, [x**2, 0]])

Matrix([
[0, x**2], : <[1, 0] + <[1, 0]>, [0, x] + <[1, 0]>, [1, 0] + <[1, 0]>> -> QQ[x]**2
[0, 0]])
(continues on next page)

5.19. Polynomials Manipulation Module 925

SymPy Documentation, Release 1.3

(continued from previous page)

>>> homomorphism(S/[(0, x)], T, [0, [x**2, 0]])
Traceback (most recent call last):
...
ValueError: kernel <[1, 0], [0, 0]> must contain sm, got <[0,x]>

Finally, here is the detailed reference of the actual homomorphism class:

class sympy.polys.agca.homomorphisms.ModuleHomomorphism(domain, codomain)
Abstract base class for module homomoprhisms. Do not instantiate.
Instead, use the homomorphism function:

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> homomorphism(F, F, [[1, 0], [0, 1]])
Matrix([
[1, 0], : QQ[x]**2 -> QQ[x]**2
[0, 1]])

Attributes:
• ring - the ring over which we are considering modules
• domain - the domain module
• codomain - the codomain module
• _ker - cached kernel
• _img - cached image
Non-implemented methods:
• _kernel
• _image
• _restrict_domain
• _restrict_codomain
• _quotient_domain
• _quotient_codomain
• _apply
• _mul_scalar
• _compose
• _add
image()
Compute the image of self.
That is, if self is the homomorphism ϕ : M → N , then compute im(ϕ) = {ϕ(x)|x ∈ M }.
This is a submodule of N .

926 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> homomorphism(F, F, [[1, 0], [x, 0]]).image() == F.submodule([1, 0])
True

is_injective()
Return True if self is injective.
That is, check if the elements of the domain are mapped to the same codomain
element.

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h.is_injective()
False
>>> h.quotient_domain(h.kernel()).is_injective()
True

is_isomorphism()
Return True if self is an isomorphism.
That is, check if every element of the codomain has precisely one preimage. Equiv-
alently, self is both injective and surjective.

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h = h.restrict_codomain(h.image())
>>> h.is_isomorphism()
False
>>> h.quotient_domain(h.kernel()).is_isomorphism()
True

is_surjective()
Return True if self is surjective.
That is, check if every element of the codomain has at least one preimage.

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h.is_surjective()
False
(continues on next page)

5.19. Polynomials Manipulation Module 927

SymPy Documentation, Release 1.3

(continued from previous page)

>>> h.restrict_codomain(h.image()).is_surjective()
True

is_zero()
Return True if self is a zero morphism.
That is, check if every element of the domain is mapped to zero under self.

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h.is_zero()
False
>>> h.restrict_domain(F.submodule()).is_zero()
True
>>> h.quotient_codomain(h.image()).is_zero()
True

kernel()
Compute the kernel of self.
That is, if self is the homomorphism ϕ : M → N , then compute ker(ϕ) = {x ∈ M |ϕ(x) =
0}. This is a submodule of M .

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> homomorphism(F, F, [[1, 0], [x, 0]]).kernel()
<[x, -1]>

quotient_codomain(sm)
Return self with codomain replaced by codomain/sm.
Here sm must be a submodule of self.codomain.

>>> from sympy import QQ

>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h
Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2
[0, 0]])
>>> h.quotient_codomain(F.submodule([1, 1]))
Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2/<[1, 1]>
[0, 0]])

This is the same as composing with the quotient map on the left:

928 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> (F/[(1, 1)]).quotient_hom() * h

Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2/<[1, 1]>
[0, 0]])

quotient_domain(sm)
Return self with domain replaced by domain/sm.
Here sm must be a submodule of self.kernel().
>>> from sympy import QQ
>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h
Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2
[0, 0]])
>>> h.quotient_domain(F.submodule([-x, 1]))
Matrix([
[1, x], : QQ[x]**2/<[-x, 1]> -> QQ[x]**2
[0, 0]])

restrict_codomain(sm)
Return self, with codomain restricted to to sm.
Here sm has to be a submodule of self.codomain containing the image.
>>> from sympy import QQ
>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h
Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2
[0, 0]])
>>> h.restrict_codomain(F.submodule([1, 0]))
Matrix([
[1, x], : QQ[x]**2 -> <[1, 0]>
[0, 0]])

restrict_domain(sm)
Return self, with the domain restricted to sm.
Here sm has to be a submodule of self.domain.
>>> from sympy import QQ
>>> from sympy.abc import x
>>> from sympy.polys.agca import homomorphism

>>> F = QQ.old_poly_ring(x).free_module(2)
>>> h = homomorphism(F, F, [[1, 0], [x, 0]])
>>> h
(continues on next page)

5.19. Polynomials Manipulation Module 929

SymPy Documentation, Release 1.3

(continued from previous page)

Matrix([
[1, x], : QQ[x]**2 -> QQ[x]**2
[0, 0]])
>>> h.restrict_domain(F.submodule([1, 0]))
Matrix([
[1, x], : <[1, 0]> -> QQ[x]**2
[0, 0]])

This is the same as just composing on the right with the submodule inclusion:

>>> h * F.submodule([1, 0]).inclusion_hom()

Matrix([
[1, x], : <[1, 0]> -> QQ[x]**2
[0, 0]])

Internals of the Polynomial Manipulation Module

The implementation of the polynomials module is structured internally in “levels”. There

are four levels, called L0, L1, L2 and L3. The levels three and four contain the user-facing
functionality and were described in the previous section. This section focuses on levels zero
and one.
Level zero provides core polynomial manipulation functionality with C-like, low-level inter-
faces. Level one wraps this low-level functionality into object oriented structures. These
are not the classes seen by the user, but rather classes used internally throughout the polys
module.
There is one additional complication in the implementation. This comes from the fact that
all polynomial manipulations are relative to a ground domain. For example, when factoring
a polynomial like x10 − 1, one has to decide what ring the coefficients are supposed to belong
to, or less trivially, what coefficients are allowed to appear in the factorization. This choice
of coefficients is called a ground domain. Typical choices include the integers Z, the rational
numbers Q or various related rings and fields. But it is perfectly legitimate (although in this
case uninteresting) to factorize over polynomial rings such as k[Y ], where k is some fixed field.
Thus the polynomial manipulation algorithms (both complicated ones like factoring, and sim-
pler ones like addition or multiplication) have to rely on other code to manipulate the co-
efficients. In the polynomial manipulation module, such code is encapsulated in so-called
“domains”. A domain is basically a factory object: it takes various representations of data,
and converts them into objects with unified interface. Every object created by a domain has
to implement the arithmetic operations +, − and ×. Other operations are accessed through
the domain, e.g. as in ZZ.quo(ZZ(4), ZZ(2)).
Note that there is some amount of circularity: the polynomial ring domains use the level
one classes, the level one classes use the level zero functions, and level zero functions use
domains. It is possible, in principle, but not in the current implementation, to work in rings
like k[X][Y ]. This would create even more layers. For this reason, working in the isomorphic
ring k[X, Y ] is preferred.

Domains

Here we document the various implemented ground domains. There are three types: abstract
domains, concrete domains, and “implementation domains”. Abstract domains cannot be

930 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(usefully) instantiated at all, and just collect together functionality shared by many other
domains. Concrete domains are those meant to be instantiated and used in the polynomial
manipulation algorithms. In some cases, there are various possible ways to implement the
data type the domain provides. For example, depending on what libraries are available on the
system, the integers are implemented either using the python built-in integers, or using gmpy.
Note that various aliases are created automatically depending on the libraries available. As
such e.g. ZZ always refers to the most efficient implementation of the integer ring available.

Abstract Domains

class sympy.polys.domains.domain.Domain
Represents an abstract domain.

Attributes

alias
dtype
one
rep
zero

abs(a)
Absolute value of a, implies __abs__.
add(a, b)
Sum of a and b, implies __add__.
algebraic_field(*extension)
Returns an algebraic field, i.e. K(α, . . .).
almosteq(a, b, tolerance=None)
Check if a and b are almost equal.
characteristic()
Return the characteristic of this domain.
cofactors(a, b)
Returns GCD and cofactors of a and b.
convert(element, base=None)
Convert element to self.dtype.
convert_from(element, base)
Convert element to self.dtype given the base domain.
denom(a)
Returns denominator of a.
div(a, b)
Division of a and b, implies something.
evalf(a, prec=None, **options)
Returns numerical approximation of a.
exquo(a, b)
Exact quotient of a and b, implies something.

5.19. Polynomials Manipulation Module 931

SymPy Documentation, Release 1.3

frac_field(*symbols, **kwargs)
Returns a fraction field, i.e. K(X).
from_AlgebraicField(a, K0)
Convert an algebraic number to dtype.
from_ComplexField(a, K0)
Convert a complex element to dtype.
from_ExpressionDomain(a, K0)
Convert a EX object to dtype.
from_FF_gmpy(a, K0)
Convert ModularInteger(mpz) to dtype.
from_FF_python(a, K0)
Convert ModularInteger(int) to dtype.
from_FractionField(a, K0)
Convert a rational function to dtype.
from_GlobalPolynomialRing(a, K0)
Convert a polynomial to dtype.
from_PolynomialRing(a, K0)
Convert a polynomial to dtype.
from_QQ_gmpy(a, K0)
Convert a GMPY mpq object to dtype.
from_QQ_python(a, K0)
Convert a Python Fraction object to dtype.
from_RealField(a, K0)
Convert a real element object to dtype.
from_ZZ_gmpy(a, K0)
Convert a GMPY mpz object to dtype.
from_ZZ_python(a, K0)
Convert a Python int object to dtype.
from_sympy(a)
Convert a SymPy object to dtype.
gcd(a, b)
Returns GCD of a and b.
gcdex(a, b)
Extended GCD of a and b.
get_exact()
Returns an exact domain associated with self.
get_field()
Returns a field associated with self.
get_ring()
Returns a ring associated with self.
half_gcdex(a, b)
Half extended GCD of a and b.

932 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

inject(*symbols)
Inject generators into this domain.
invert(a, b)
Returns inversion of a mod b, implies something.
is_negative(a)
Returns True if a is negative.
is_nonnegative(a)
Returns True if a is non-negative.
is_nonpositive(a)
Returns True if a is non-positive.
is_one(a)
Returns True if a is one.
is_positive(a)
Returns True if a is positive.
is_zero(a)
Returns True if a is zero.
lcm(a, b)
Returns LCM of a and b.
log(a, b)
Returns b-base logarithm of a.
map(seq)
Rersively apply self to all elements of seq.
mul(a, b)
Product of a and b, implies __mul__.
n(a, prec=None, **options)
Returns numerical approximation of a.
neg(a)
Returns a negated, implies __neg__.
numer(a)
Returns numerator of a.
of_type(element)
Check if a is of type dtype.
old_frac_field(*symbols, **kwargs)
Returns a fraction field, i.e. K(X).
old_poly_ring(*symbols, **kwargs)
Returns a polynomial ring, i.e. K[X].
poly_ring(*symbols, **kwargs)
Returns a polynomial ring, i.e. K[X].
pos(a)
Returns a positive, implies __pos__.
pow(a, b)
Raise a to power b, implies __pow__.

5.19. Polynomials Manipulation Module 933

SymPy Documentation, Release 1.3

quo(a, b)
Quotient of a and b, implies something.
rem(a, b)
Remainder of a and b, implies __mod__.
revert(a)
Returns a**(-1) if possible.
sqrt(a)
Returns square root of a.
sub(a, b)
Difference of a and b, implies __sub__.
to_sympy(a)
Convert a to a SymPy object.
unify(K1, symbols=None)
Construct a minimal domain that contains elements of K0 and K1.
Known domains (from smallest to largest):
• GF(p)
• ZZ
• QQ
• RR(prec, tol)
• CC(prec, tol)
• ALG(a, b, c)
• K[x, y, z]
• K(x, y, z)
• EX
class sympy.polys.domains.field.Field
Represents a field domain.

Attributes

alias
dtype
one
rep
zero

div(a, b)
Division of a and b, implies __div__.
exquo(a, b)
Exact quotient of a and b, implies __div__.
gcd(a, b)
Returns GCD of a and b.
This definition of GCD over fields allows to clear denominators in primitive().

934 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.polys.domains import QQ

>>> from sympy import S, gcd, primitive
>>> from sympy.abc import x

>>> QQ.gcd(QQ(2, 3), QQ(4, 9))

2/9
>>> gcd(S(2)/3, S(4)/9)
2/9
>>> primitive(2*x/3 + S(4)/9)
(2/9, 3*x + 2)

get_field()
Returns a field associated with self.
get_ring()
Returns a ring associated with self.
lcm(a, b)
Returns LCM of a and b.
>>> from sympy.polys.domains import QQ
>>> from sympy import S, lcm

>>> QQ.lcm(QQ(2, 3), QQ(4, 9))

4/3
>>> lcm(S(2)/3, S(4)/9)
4/3

quo(a, b)
Quotient of a and b, implies __div__.
rem(a, b)
Remainder of a and b, implies nothing.
revert(a)
Returns a**(-1) if possible.
class sympy.polys.domains.ring.Ring
Represents a ring domain.

Attributes

alias
dtype
one
rep
zero

denom(a)
Returns denominator of a.
div(a, b)
Division of a and b, implies __divmod__.
exquo(a, b)
Exact quotient of a and b, implies __floordiv__.

5.19. Polynomials Manipulation Module 935

SymPy Documentation, Release 1.3

free_module(rank)
Generate a free module of rank rank over self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).free_module(2)
QQ[x]**2

get_ring()
Returns a ring associated with self.
ideal(*gens)
Generate an ideal of self.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).ideal(x**2)
<x**2>

invert(a, b)
Returns inversion of a mod b.
numer(a)
Returns numerator of a.
quo(a, b)
Quotient of a and b, implies __floordiv__.
quotient_ring(e)
Form a quotient ring of self.
Here e can be an ideal or an iterable.

>>> from sympy.abc import x

>>> from sympy import QQ
>>> QQ.old_poly_ring(x).quotient_ring(QQ.old_poly_ring(x).ideal(x**2))
QQ[x]/<x**2>
>>> QQ.old_poly_ring(x).quotient_ring([x**2])
QQ[x]/<x**2>

The division operator has been overloaded for this:

>>> QQ.old_poly_ring(x)/[x**2]
QQ[x]/<x**2>

rem(a, b)
Remainder of a and b, implies __mod__.
revert(a)
Returns a**(-1) if possible.
class sympy.polys.domains.simpledomain.SimpleDomain
Base class for simple domains, e.g. ZZ, QQ.

936 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

alias
dtype
one
rep
zero

inject(*gens)
Inject generators into this domain.
class sympy.polys.domains.compositedomain.CompositeDomain
Base class for composite domains, e.g. ZZ[x], ZZ(X).

Attributes

alias
domain
dtype
gens
ngens
one
rep
symbols
zero

inject(*symbols)
Inject generators into this domain.

Concrete Domains

class sympy.polys.domains.FiniteField(mod, dom=None, symmetric=True)

General class for finite fields.

Attributes

alias
dom
dtype
mod
one
zero

characteristic()
Return the characteristic of this domain.
from_FF_gmpy(a, K0=None)
Convert ModularInteger(mpz) to dtype.

5.19. Polynomials Manipulation Module 937

SymPy Documentation, Release 1.3

from_FF_python(a, K0=None)
Convert ModularInteger(int) to dtype.
from_QQ_gmpy(a, K0=None)
Convert GMPY’s mpq to dtype.
from_QQ_python(a, K0=None)
Convert Python’s Fraction to dtype.
from_RealField(a, K0)
Convert mpmath’s mpf to dtype.
from_ZZ_gmpy(a, K0=None)
Convert GMPY’s mpz to dtype.
from_ZZ_python(a, K0=None)
Convert Python’s int to dtype.
from_sympy(a)
Convert SymPy’s Integer to SymPy’s Integer.
get_field()
Returns a field associated with self.
to_sympy(a)
Convert a to a SymPy object.
class sympy.polys.domains.IntegerRing
General class for integer rings.

Attributes

alias
dtype
one
zero

algebraic_field(*extension)
Returns an algebraic field, i.e. Q(α, . . .).
from_AlgebraicField(a, K0)
Convert a ANP object to dtype.
get_field()
Returns a field associated with self.
log(a, b)
Returns b-base logarithm of a.
class sympy.polys.domains.PolynomialRing(domain_or_ring, symbols=None, or-
der=None)
A class for representing multivariate polynomial rings.

938 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

alias
domain
dtype
gens
ngens
rep
symbols

factorial(a)
Returns factorial of a.
from_AlgebraicField(a, K0)
Convert an algebraic number to dtype.
from_FractionField(a, K0)
Convert a rational function to dtype.
from_PolynomialRing(a, K0)
Convert a polynomial to dtype.
from_QQ_gmpy(a, K0)
Convert a GMPY mpq object to dtype.
from_QQ_python(a, K0)
Convert a Python F raction object to dtype.
from_RealField(a, K0)
Convert a mpmath mpf object to dtype.
from_ZZ_gmpy(a, K0)
Convert a GMPY mpz object to dtype.
from_ZZ_python(a, K0)
Convert a Python int object to dtype.
from_sympy(a)
Convert SymPy’s expression to dtype.
gcd(a, b)
Returns GCD of a and b.
gcdex(a, b)
Extended GCD of a and b.
get_field()
Returns a field associated with self .
is_negative(a)
Returns True if LC(a) is negative.
is_nonnegative(a)
Returns True if LC(a) is non-negative.
is_nonpositive(a)
Returns True if LC(a) is non-positive.
is_positive(a)
Returns True if LC(a) is positive.

5.19. Polynomials Manipulation Module 939

SymPy Documentation, Release 1.3

lcm(a, b)
Returns LCM of a and b.
to_sympy(a)
Convert a to a SymPy object.
class sympy.polys.domains.RationalField
General class for rational fields.

Attributes

alias
dtype
one
zero

algebraic_field(*extension)
Returns an algebraic field, i.e. Q(α, . . .).
from_AlgebraicField(a, K0)
Convert a ANP object to dtype.
class sympy.polys.domains.AlgebraicField(dom, *ext)
A class for representing algebraic number fields.

Attributes

alias
one
rep
zero

algebraic_field(*extension)
Returns an algebraic field, i.e. Q(α, . . .).
denom(a)
Returns denominator of a.
dtype
alias of sympy.polys.polyclasses.ANP (page 951)
from_QQ_gmpy(a, K0)
Convert a GMPY mpq object to dtype.
from_QQ_python(a, K0)
Convert a Python Fraction object to dtype.
from_RealField(a, K0)
Convert a mpmath mpf object to dtype.
from_ZZ_gmpy(a, K0)
Convert a GMPY mpz object to dtype.
from_ZZ_python(a, K0)
Convert a Python int object to dtype.

940 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

from_sympy(a)
Convert SymPy’s expression to dtype.
get_ring()
Returns a ring associated with self.
is_negative(a)
Returns True if a is negative.
is_nonnegative(a)
Returns True if a is non-negative.
is_nonpositive(a)
Returns True if a is non-positive.
is_positive(a)
Returns True if a is positive.
numer(a)
Returns numerator of a.
to_sympy(a)
Convert a to a SymPy object.
class sympy.polys.domains.FractionField(domain_or_field, symbols=None, or-
der=None)
A class for representing multivariate rational function fields.

Attributes

alias
domain
dtype
gens
ngens
rep
symbols

denom(a)
Returns denominator of a.
factorial(a)
Returns factorial of a.
from_AlgebraicField(a, K0)
Convert an algebraic number to dtype.
from_FractionField(a, K0)
Convert a rational function to dtype.
from_PolynomialRing(a, K0)
Convert a polynomial to dtype.
from_QQ_gmpy(a, K0)
Convert a GMPY mpq object to dtype.
from_QQ_python(a, K0)
Convert a Python F raction object to dtype.

5.19. Polynomials Manipulation Module 941

SymPy Documentation, Release 1.3

from_RealField(a, K0)
Convert a mpmath mpf object to dtype.
from_ZZ_gmpy(a, K0)
Convert a GMPY mpz object to dtype.
from_ZZ_python(a, K0)
Convert a Python int object to dtype.
from_sympy(a)
Convert SymPy’s expression to dtype.
get_ring()
Returns a field associated with self .
is_negative(a)
Returns True if LC(a) is negative.
is_nonnegative(a)
Returns True if LC(a) is non-negative.
is_nonpositive(a)
Returns True if LC(a) is non-positive.
is_positive(a)
Returns True if LC(a) is positive.
numer(a)
Returns numerator of a.
to_sympy(a)
Convert a to a SymPy object.
class sympy.polys.domains.RealField(prec=53, dps=None, tol=None)
Real numbers up to the given precision.

Attributes

alias
dtype
one
zero

almosteq(a, b, tolerance=None)
Check if a and b are almost equal.
from_sympy(expr)
Convert SymPy’s number to dtype.
gcd(a, b)
Returns GCD of a and b.
get_exact()
Returns an exact domain associated with self.
get_ring()
Returns a ring associated with self.
lcm(a, b)
Returns LCM of a and b.

942 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

to_rational(element, limit=True)
Convert a real number to rational number.
to_sympy(element)
Convert element to SymPy number.
class sympy.polys.domains.ExpressionDomain
A class for arbitrary expressions.

Attributes

alias

class Expression(ex)
An arbitrary expression.
denom(a)
Returns denominator of a.
dtype
alias of ExpressionDomain.Expression (page 943)
from_ExpressionDomain(a, K0)
Convert a EX object to dtype.
from_FractionField(a, K0)
Convert a DMF object to dtype.
from_PolynomialRing(a, K0)
Convert a DMP object to dtype.
from_QQ_gmpy(a, K0)
Convert a GMPY mpq object to dtype.
from_QQ_python(a, K0)
Convert a Python Fraction object to dtype.
from_RealField(a, K0)
Convert a mpmath mpf object to dtype.
from_ZZ_gmpy(a, K0)
Convert a GMPY mpz object to dtype.
from_ZZ_python(a, K0)
Convert a Python int object to dtype.
from_sympy(a)
Convert SymPy’s expression to dtype.
get_field()
Returns a field associated with self.
get_ring()
Returns a ring associated with self.
is_negative(a)
Returns True if a is negative.
is_nonnegative(a)
Returns True if a is non-negative.

5.19. Polynomials Manipulation Module 943

SymPy Documentation, Release 1.3

is_nonpositive(a)
Returns True if a is non-positive.
is_positive(a)
Returns True if a is positive.
numer(a)
Returns numerator of a.
to_sympy(a)
Convert a to a SymPy object.

Implementation Domains

class sympy.polys.domains.PythonFiniteField(mod, symmetric=True)

Finite field based on Python’s integers.

Attributes

dom
dtype
mod
one
zero

class sympy.polys.domains.GMPYFiniteField(mod, symmetric=True)

Finite field based on GMPY integers.

Attributes

dom
dtype
mod
one
zero

class sympy.polys.domains.PythonIntegerRing
Integer ring based on Python’s int type.
class sympy.polys.domains.GMPYIntegerRing
Integer ring based on GMPY’s mpz type.
class sympy.polys.domains.PythonRationalField
Rational field based on Python rational number type.
class sympy.polys.domains.GMPYRationalField
Rational field based on GMPY mpq class.

944 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Level One

class sympy.polys.polyclasses.DMP(rep, dom, lev=None, ring=None)

Dense Multivariate Polynomials over K.
LC()
Returns the leading coefficient of f.
TC()
Returns the trailing coefficient of f.
abs()
Make all coefficients in f positive.
add(g)
Add two multivariate polynomials f and g.
add_ground(c)
Add an element of the ground domain to f.
all_coeffs()
Returns all coefficients from f.
all_monoms()
Returns all monomials from f.
all_terms()
Returns all terms from a f.
cancel(g, include=True)
Cancel common factors in a rational function f/g.
clear_denoms()
Clear denominators, but keep the ground domain.
coeffs(order=None)
Returns all non-zero coefficients from f in lex order.
cofactors(g)
Returns GCD of f and g and their cofactors.
compose(g)
Computes functional composition of f and g.
content()
Returns GCD of polynomial coefficients.
convert(dom)
Convert the ground domain of f.
count_complex_roots(inf=None, sup=None)
Return the number of complex roots of f in [inf, sup].
count_real_roots(inf=None, sup=None)
Return the number of real roots of f in [inf, sup].
decompose()
Computes functional decomposition of f.
deflate()
Reduce degree of f by mapping xm
i to yi .

degree(j=0)
Returns the leading degree of f in x_j.

5.19. Polynomials Manipulation Module 945

SymPy Documentation, Release 1.3

degree_list()
Returns a list of degrees of f.
diff(m=1, j=0)
Computes the m-th order derivative of f in x_j.
discriminant()
Computes discriminant of f.
div(g)
Polynomial division with remainder of f and g.
eject(dom, front=False)
Eject selected generators into the ground domain.
eval(a, j=0)
Evaluates f at the given point a in x_j.
exclude()
Remove useless generators from f.
Returns the removed generators and the new excluded f.

Examples

>>> from sympy.polys.polyclasses import DMP

>>> from sympy.polys.domains import ZZ

>>> DMP([[[ZZ(1)]], [[ZZ(1)], [ZZ(2)]]], ZZ).exclude()

([2], DMP([[1], [1, 2]], ZZ, None))

exquo(g)
Computes polynomial exact quotient of f and g.
exquo_ground(c)
Exact quotient of f by a an element of the ground domain.
factor_list()
Returns a list of irreducible factors of f.
factor_list_include()
Returns a list of irreducible factors of f.
classmethod from_dict(rep, lev, dom)
Construct and instance of cls from a dict representation.
classmethod from_list(rep, lev, dom)
Create an instance of cls given a list of native coefficients.
classmethod from_sympy_list(rep, lev, dom)
Create an instance of cls given a list of SymPy coefficients.
gcd(g)
Returns polynomial GCD of f and g.
gcdex(g)
Extended Euclidean algorithm, if univariate.
gff_list()
Computes greatest factorial factorization of f.

946 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

half_gcdex(g)
Half extended Euclidean algorithm, if univariate.
homogeneous_order()
Returns the homogeneous order of f.
homogenize(s)
Return homogeneous polynomial of f
inject(front=False)
Inject ground domain generators into f.
integrate(m=1, j=0)
Computes the m-th order indefinite integral of f in x_j.
intervals(all=False, eps=None, inf=None, sup=None, fast=False, sqf=False)
Compute isolating intervals for roots of f.
invert(g)
Invert f modulo g, if possible.
is_cyclotomic
Returns True if f is a cyclotomic polynomial.
is_ground
Returns True if f is an element of the ground domain.
is_homogeneous
Returns True if f is a homogeneous polynomial.
is_irreducible
Returns True if f has no factors over its domain.
is_linear
Returns True if f is linear in all its variables.
is_monic
Returns True if the leading coefficient of f is one.
is_monomial
Returns True if f is zero or has only one term.
is_one
Returns True if f is a unit polynomial.
is_primitive
Returns True if the GCD of the coefficients of f is one.
is_quadratic
Returns True if f is quadratic in all its variables.
is_sqf
Returns True if f is a square-free polynomial.
is_zero
Returns True if f is a zero polynomial.
l1_norm()
Returns l1 norm of f.
lcm(g)
Returns polynomial LCM of f and g.

5.19. Polynomials Manipulation Module 947

SymPy Documentation, Release 1.3

lift()
Convert algebraic coefficients to rationals.
max_norm()
Returns maximum norm of f.
monic()
Divides all coefficients by LC(f).
monoms(order=None)
Returns all non-zero monomials from f in lex order.
mul(g)
Multiply two multivariate polynomials f and g.
mul_ground(c)
Multiply f by a an element of the ground domain.
neg()
Negate all coefficients in f.
norm()
Computes Norm(f).
nth(*N)
Returns the n-th coefficient of f.
pdiv(g)
Polynomial pseudo-division of f and g.
per(rep, dom=None, kill=False, ring=None)
Create a DMP out of the given representation.
permute(P)
Returns a polynomial in K[xP (1) , ..., xP (n) ].

Examples

>>> from sympy.polys.polyclasses import DMP

>>> from sympy.polys.domains import ZZ

>>> DMP([[[ZZ(2)], [ZZ(1), ZZ(0)]], [[]]], ZZ).permute([1, 0, 2])

DMP([[[2], []], [[1, 0], []]], ZZ, None)

>>> DMP([[[ZZ(2)], [ZZ(1), ZZ(0)]], [[]]], ZZ).permute([1, 2, 0])

DMP([[[1], []], [[2, 0], []]], ZZ, None)

pexquo(g)
Polynomial exact pseudo-quotient of f and g.
pow(n)
Raise f to a non-negative power n.
pquo(g)
Polynomial pseudo-quotient of f and g.
prem(g)
Polynomial pseudo-remainder of f and g.

948 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

primitive()
Returns content and a primitive form of f.
quo(g)
Computes polynomial quotient of f and g.
quo_ground(c)
Quotient of f by a an element of the ground domain.
refine_root(s, t, eps=None, steps=None, fast=False)
Refine an isolating interval to the given precision.
eps should be a rational number.
rem(g)
Computes polynomial remainder of f and g.
resultant(g, includePRS=False)
Computes resultant of f and g via PRS.
revert(n)
Compute f**(-1) mod x**n.
shift(a)
Efficiently compute Taylor shift f(x + a).
slice(m, n, j=0)
Take a continuous subsequence of terms of f.
sqf_list(all=False)
Returns a list of square-free factors of f.
sqf_list_include(all=False)
Returns a list of square-free factors of f.
sqf_norm()
Computes square-free norm of f.
sqf_part()
Computes square-free part of f.
sqr()
Square a multivariate polynomial f.
sturm()
Computes the Sturm sequence of f.
sub(g)
Subtract two multivariate polynomials f and g.
sub_ground(c)
Subtract an element of the ground domain from f.
subresultants(g)
Computes subresultant PRS sequence of f and g.
terms(order=None)
Returns all non-zero terms from f in lex order.
terms_gcd()
Remove GCD of terms from the polynomial f.
to_dict(zero=False)
Convert f to a dict representation with native coefficients.

5.19. Polynomials Manipulation Module 949

SymPy Documentation, Release 1.3

to_exact()
Make the ground domain exact.
to_field()
Make the ground domain a field.
to_list()
Convert f to a list representation with native coefficients.
to_ring()
Make the ground domain a ring.
to_sympy_dict(zero=False)
Convert f to a dict representation with SymPy coefficients.
to_sympy_list()
Convert f to a list representation with SymPy coefficients.
to_tuple()
Convert f to a tuple representation with native coefficients.
This is needed for hashing.
total_degree()
Returns the total degree of f.
transform(p, q)
Evaluate functional transformation q**n * f(p/q).
trunc(p)
Reduce f modulo a constant p.
unify(g)
Unify representations of two multivariate polynomials.
class sympy.polys.polyclasses.DMF(rep, dom, lev=None, ring=None)
Dense Multivariate Fractions over K.
add(g)
Add two multivariate fractions f and g.
cancel()
Remove common factors from f.num and f.den.
denom()
Returns the denominator of f.
exquo(g)
Computes quotient of fractions f and g.
frac_unify(g)
Unify representations of two multivariate fractions.
half_per(rep, kill=False)
Create a DMP out of the given representation.
invert(check=True)
Computes inverse of a fraction f.
is_one
Returns True if f is a unit fraction.
is_zero
Returns True if f is a zero fraction.

950 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

mul(g)
Multiply two multivariate fractions f and g.
neg()
Negate all coefficients in f.
numer()
Returns the numerator of f.
per(num, den, cancel=True, kill=False, ring=None)
Create a DMF out of the given representation.
poly_unify(g)
Unify a multivariate fraction and a polynomial.
pow(n)
Raise f to a non-negative power n.
quo(g)
Computes quotient of fractions f and g.
sub(g)
Subtract two multivariate fractions f and g.
class sympy.polys.polyclasses.ANP(rep, mod, dom)
Dense Algebraic Number Polynomials over a field.
LC()
Returns the leading coefficient of f.
TC()
Returns the trailing coefficient of f.
is_ground
Returns True if f is an element of the ground domain.
is_one
Returns True if f is a unit algebraic number.
is_zero
Returns True if f is a zero algebraic number.
pow(n)
Raise f to a non-negative power n.
to_dict()
Convert f to a dict representation with native coefficients.
to_list()
Convert f to a list representation with native coefficients.
to_sympy_dict()
Convert f to a dict representation with SymPy coefficients.
to_sympy_list()
Convert f to a list representation with SymPy coefficients.
to_tuple()
Convert f to a tuple representation with native coefficients.
This is needed for hashing.
unify(g)
Unify representations of two algebraic numbers.

5.19. Polynomials Manipulation Module 951

SymPy Documentation, Release 1.3

Level Zero

Level zero contains the bulk code of the polynomial manipulation module.

Manipulation of dense, multivariate polynomials

These functions can be used to manipulate polynomials in K[X0 , . . . , Xu ]. Functions for manip-
ulating multivariate polynomials in the dense representation have the prefix dmp_. Functions
which only apply to univariate polynomials (i.e. u = 0) have the prefix dup__. The ground do-
main K has to be passed explicitly. For many multivariate polynomial manipulation functions
also the level u, i.e. the number of generators minus one, has to be passed. (Note that, in
many cases, dup_ versions of functions are available, which may be slightly more efficient.)
Basic manipulation:
sympy.polys.densebasic.dmp_LC(f, K)
Return leading coefficient of f.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import poly_LC

>>> poly_LC([], ZZ)

0
>>> poly_LC([ZZ(1), ZZ(2), ZZ(3)], ZZ)
1

sympy.polys.densebasic.dmp_TC(f, K)
Return trailing coefficient of f.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import poly_TC

>>> poly_TC([], ZZ)

0
>>> poly_TC([ZZ(1), ZZ(2), ZZ(3)], ZZ)
3

sympy.polys.densebasic.dmp_ground_LC(f, u, K)
Return the ground leading coefficient.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_ground_LC

952 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> f = ZZ.map([[[1], [2, 3]]])

>>> dmp_ground_LC(f, 2, ZZ)

1

sympy.polys.densebasic.dmp_ground_TC(f, u, K)
Return the ground trailing coefficient.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_ground_TC

>>> f = ZZ.map([[[1], [2, 3]]])

>>> dmp_ground_TC(f, 2, ZZ)

3

sympy.polys.densebasic.dmp_true_LT(f, u, K)
Return the leading term c * x_1**n_1 ... x_k**n_k.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_true_LT

>>> f = ZZ.map([[4], [2, 0], [3, 0, 0]])

>>> dmp_true_LT(f, 1, ZZ)

((2, 0), 4)

sympy.polys.densebasic.dmp_degree(f, u)
Return the leading degree of f in x_0 in K[X].
Note that the degree of 0 is negative infinity (the SymPy object -oo).

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_degree

>>> dmp_degree([[[]]], 2)
-oo

>>> f = ZZ.map([[2], [1, 2, 3]])

>>> dmp_degree(f, 1)
1

5.19. Polynomials Manipulation Module 953

SymPy Documentation, Release 1.3

sympy.polys.densebasic.dmp_degree_in(f, j, u)
Return the leading degree of f in x_j in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_degree_in

>>> f = ZZ.map([[2], [1, 2, 3]])

>>> dmp_degree_in(f, 0, 1)
1
>>> dmp_degree_in(f, 1, 1)
2

sympy.polys.densebasic.dmp_degree_list(f, u)
Return a list of degrees of f in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_degree_list

>>> f = ZZ.map([[1], [1, 2, 3]])

>>> dmp_degree_list(f, 1)
(1, 2)

sympy.polys.densebasic.dmp_strip(f, u)
Remove leading zeros from f in K[X].

Examples

>>> from sympy.polys.densebasic import dmp_strip

>>> dmp_strip([[], [0, 1, 2], [1]], 1)

[[0, 1, 2], [1]]

sympy.polys.densebasic.dmp_validate(f, K=None)
Return the number of levels in f and recursively strip it.

Examples

>>> from sympy.polys.densebasic import dmp_validate

>>> dmp_validate([[], [0, 1, 2], [1]])

([[1, 2], [1]], 1)

954 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> dmp_validate([[1], 1])

Traceback (most recent call last):
...
ValueError: invalid data structure for a multivariate polynomial

sympy.polys.densebasic.dup_reverse(f)
Compute x**n * f(1/x), i.e.: reverse f in K[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dup_reverse

>>> f = ZZ.map([1, 2, 3, 0])

>>> dup_reverse(f)
[3, 2, 1]

sympy.polys.densebasic.dmp_copy(f, u)
Create a new copy of a polynomial f in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_copy

>>> f = ZZ.map([[1], [1, 2]])

>>> dmp_copy(f, 1)
[[1], [1, 2]]

sympy.polys.densebasic.dmp_to_tuple(f, u)
Convert f into a nested tuple of tuples.
This is needed for hashing. This is similar to dmp_copy().

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_to_tuple

>>> f = ZZ.map([[1], [1, 2]])

>>> dmp_to_tuple(f, 1)
((1,), (1, 2))

sympy.polys.densebasic.dmp_normal(f, u, K)
Normalize a multivariate polynomial in the given domain.

5.19. Polynomials Manipulation Module 955

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_normal

>>> dmp_normal([[], [0, 1.5, 2]], 1, ZZ)

[[1, 2]]

sympy.polys.densebasic.dmp_convert(f, u, K0, K1)

Convert the ground domain of f from K0 to K1.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.densebasic import dmp_convert

>>> R, x = ring(”x”, ZZ)

>>> dmp_convert([[R(1)], [R(2)]], 1, R.to_domain(), ZZ)

[[1], [2]]
>>> dmp_convert([[ZZ(1)], [ZZ(2)]], 1, ZZ, R.to_domain())
[[1], [2]]

sympy.polys.densebasic.dmp_from_sympy(f, u, K)
Convert the ground domain of f from SymPy to K.

Examples

>>> from sympy import S

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.densebasic import dmp_from_sympy

>>> dmp_from_sympy([[S(1)], [S(2)]], 1, ZZ) == [[ZZ(1)], [ZZ(2)]]

True

sympy.polys.densebasic.dmp_nth(f, n, u, K)
Return the n-th coefficient of f in K[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_nth

>>> f = ZZ.map([[1], [2], [3]])

>>> dmp_nth(f, 0, 1, ZZ)

[3]
>>> dmp_nth(f, 4, 1, ZZ)
[]

956 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.densebasic.dmp_ground_nth(f, N, u, K)
Return the ground n-th coefficient of f in K[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_ground_nth

>>> f = ZZ.map([[1], [2, 3]])

>>> dmp_ground_nth(f, (0, 1), 1, ZZ)

2

sympy.polys.densebasic.dmp_zero_p(f, u)
Return True if f is zero in K[X].

Examples

>>> from sympy.polys.densebasic import dmp_zero_p

>>> dmp_zero_p([[[[[]]]]], 4)
True
>>> dmp_zero_p([[[[[1]]]]], 4)
False

sympy.polys.densebasic.dmp_zero(u)
Return a multivariate zero.

Examples

>>> from sympy.polys.densebasic import dmp_zero

>>> dmp_zero(4)
[[[[[]]]]]

sympy.polys.densebasic.dmp_one_p(f, u, K)
Return True if f is one in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_one_p

>>> dmp_one_p([[[ZZ(1)]]], 2, ZZ)

True

sympy.polys.densebasic.dmp_one(u, K)
Return a multivariate one over K.

5.19. Polynomials Manipulation Module 957

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_one

>>> dmp_one(2, ZZ)

[[[1]]]

sympy.polys.densebasic.dmp_ground_p(f, c, u)
Return True if f is constant in K[X].

Examples

>>> from sympy.polys.densebasic import dmp_ground_p

>>> dmp_ground_p([[[3]]], 3, 2)
True
>>> dmp_ground_p([[[4]]], None, 2)
True

sympy.polys.densebasic.dmp_ground(c, u)
Return a multivariate constant.

Examples

>>> from sympy.polys.densebasic import dmp_ground

>>> dmp_ground(3, 5)
[[[[[[3]]]]]]
>>> dmp_ground(1, -1)
1

sympy.polys.densebasic.dmp_zeros(n, u, K)
Return a list of multivariate zeros.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_zeros

>>> dmp_zeros(3, 2, ZZ)

[[[[]]], [[[]]], [[[]]]]
>>> dmp_zeros(3, -1, ZZ)
[0, 0, 0]

sympy.polys.densebasic.dmp_grounds(c, n, u)
Return a list of multivariate constants.

958 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_grounds

>>> dmp_grounds(ZZ(4), 3, 2)
[[[[4]]], [[[4]]], [[[4]]]]
>>> dmp_grounds(ZZ(4), 3, -1)
[4, 4, 4]

sympy.polys.densebasic.dmp_negative_p(f, u, K)
Return True if LC(f) is negative.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_negative_p

>>> dmp_negative_p([[ZZ(1)], [-ZZ(1)]], 1, ZZ)

False
>>> dmp_negative_p([[-ZZ(1)], [ZZ(1)]], 1, ZZ)
True

sympy.polys.densebasic.dmp_positive_p(f, u, K)
Return True if LC(f) is positive.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_positive_p

>>> dmp_positive_p([[ZZ(1)], [-ZZ(1)]], 1, ZZ)

True
>>> dmp_positive_p([[-ZZ(1)], [ZZ(1)]], 1, ZZ)
False

sympy.polys.densebasic.dmp_from_dict(f, u, K)
Create a K[X] polynomial from a dict.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_from_dict

>>> dmp_from_dict({(0, 0): ZZ(3), (0, 1): ZZ(2), (2, 1): ZZ(1)}, 1, ZZ)
[[1, 0], [], [2, 3]]
>>> dmp_from_dict({}, 0, ZZ)
[]

sympy.polys.densebasic.dmp_to_dict(f, u, K=None, zero=False)

Convert a K[X] polynomial to a dict``.

5.19. Polynomials Manipulation Module 959

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.densebasic import dmp_to_dict

>>> dmp_to_dict([[1, 0], [], [2, 3]], 1)

{(0, 0): 3, (0, 1): 2, (2, 1): 1}
>>> dmp_to_dict([], 0)
{}

sympy.polys.densebasic.dmp_swap(f, i, j, u, K)
Transform K[..x_i..x_j..] to K[..x_j..x_i..].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_swap

>>> f = ZZ.map([[[2], [1, 0]], []])

>>> dmp_swap(f, 0, 1, 2, ZZ)

[[[2], []], [[1, 0], []]]
>>> dmp_swap(f, 1, 2, 2, ZZ)
[[[1], [2, 0]], [[]]]
>>> dmp_swap(f, 0, 2, 2, ZZ)
[[[1, 0]], [[2, 0], []]]

sympy.polys.densebasic.dmp_permute(f, P, u, K)
Return a polynomial in K[x_{P(1)},..,x_{P(n)}].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_permute

>>> f = ZZ.map([[[2], [1, 0]], []])

>>> dmp_permute(f, [1, 0, 2], 2, ZZ)

[[[2], []], [[1, 0], []]]
>>> dmp_permute(f, [1, 2, 0], 2, ZZ)
[[[1], []], [[2, 0], []]]

sympy.polys.densebasic.dmp_nest(f, l, K)
Return a multivariate value nested l-levels.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_nest

960 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> dmp_nest([[ZZ(1)]], 2, ZZ)

[[[[1]]]]

sympy.polys.densebasic.dmp_raise(f, l, u, K)
Return a multivariate polynomial raised l-levels.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_raise

>>> f = ZZ.map([[], [1, 2]])

>>> dmp_raise(f, 2, 1, ZZ)

[[[[]]], [[[1]], [[2]]]]

sympy.polys.densebasic.dmp_deflate(f, u, K)
Map x_i**m_i to y_i in a polynomial in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_deflate

>>> f = ZZ.map([[1, 0, 0, 2], [], [3, 0, 0, 4]])

>>> dmp_deflate(f, 1, ZZ)

((2, 3), [[1, 2], [3, 4]])

sympy.polys.densebasic.dmp_multi_deflate(polys, u, K)
Map x_i**m_i to y_i in a set of polynomials in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_multi_deflate

>>> f = ZZ.map([[1, 0, 0, 2], [], [3, 0, 0, 4]])

>>> g = ZZ.map([[1, 0, 2], [], [3, 0, 4]])

>>> dmp_multi_deflate((f, g), 1, ZZ)

((2, 1), ([[1, 0, 0, 2], [3, 0, 0, 4]], [[1, 0, 2], [3, 0, 4]]))

sympy.polys.densebasic.dmp_inflate(f, M, u, K)
Map y_i to x_i**k_i in a polynomial in K[X].

5.19. Polynomials Manipulation Module 961

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_inflate

>>> f = ZZ.map([[1, 2], [3, 4]])

>>> dmp_inflate(f, (2, 3), 1, ZZ)

[[1, 0, 0, 2], [], [3, 0, 0, 4]]

sympy.polys.densebasic.dmp_exclude(f, u, K)
Exclude useless levels from f.
Return the levels excluded, the new excluded f, and the new u.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_exclude

>>> f = ZZ.map([[[1]], [[1], [2]]])

>>> dmp_exclude(f, 2, ZZ)

([2], [[1], [1, 2]], 1)

sympy.polys.densebasic.dmp_include(f, J, u, K)
Include useless levels in f.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_include

>>> f = ZZ.map([[1], [1, 2]])

>>> dmp_include(f, [2], 1, ZZ)

[[[1]], [[1], [2]]]

sympy.polys.densebasic.dmp_inject(f, u, K, front=False)
Convert f from K[X][Y] to K[X,Y].

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.densebasic import dmp_inject

>>> R, x,y = ring(”x,y”, ZZ)

962 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> dmp_inject([R(1), x + 2], 0, R.to_domain())

([[[1]], [[1], [2]]], 2)
>>> dmp_inject([R(1), x + 2], 0, R.to_domain(), front=True)
([[[1]], [[1, 2]]], 2)

sympy.polys.densebasic.dmp_eject(f, u, K, front=False)
Convert f from K[X,Y] to K[X][Y].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_eject

>>> dmp_eject([[[1]], [[1], [2]]], 2, ZZ['x', 'y'])

[1, x + 2]

sympy.polys.densebasic.dmp_terms_gcd(f, u, K)
Remove GCD of terms from f in K[X].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_terms_gcd

>>> f = ZZ.map([[1, 0], [1, 0, 0], [], []])

>>> dmp_terms_gcd(f, 1, ZZ)

((2, 1), [[1], [1, 0]])

sympy.polys.densebasic.dmp_list_terms(f, u, K, order=None)
List all non-zero terms from f in the given order order.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_list_terms

>>> f = ZZ.map([[1, 1], [2, 3]])

>>> dmp_list_terms(f, 1, ZZ)

[((1, 1), 1), ((1, 0), 1), ((0, 1), 2), ((0, 0), 3)]
>>> dmp_list_terms(f, 1, ZZ, order='grevlex')
[((1, 1), 1), ((1, 0), 1), ((0, 1), 2), ((0, 0), 3)]

sympy.polys.densebasic.dmp_apply_pairs(f, g, h, args, u, K)
Apply h to pairs of coefficients of f and g.

5.19. Polynomials Manipulation Module 963

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dmp_apply_pairs

>>> h = lambda x, y, z: 2*x + y - z

>>> dmp_apply_pairs([[1], [2, 3]], [[3], [2, 1]], h, (1,), 1, ZZ)

[[4], [5, 6]]

sympy.polys.densebasic.dmp_slice(f, m, n, u, K)
Take a continuous subsequence of terms of f in K[X].
sympy.polys.densebasic.dup_random(n, a, b, K)
Return a polynomial of degree n with coefficients in [a, b].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.densebasic import dup_random

>>> dup_random(3, -10, 10, ZZ) #doctest: +SKIP

[-2, -8, 9, -4]

Arithmetic operations:
sympy.polys.densearith.dmp_add_term(f, c, i, u, K)
Add c(x_2..x_u)*x_0**i to f in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_add_term(x*y + 1, 2, 2)
2*x**2 + x*y + 1

sympy.polys.densearith.dmp_sub_term(f, c, i, u, K)
Subtract c(x_2..x_u)*x_0**i from f in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_sub_term(2*x**2 + x*y + 1, 2, 2)

x*y + 1

sympy.polys.densearith.dmp_mul_term(f, c, i, u, K)
Multiply f by c(x_2..x_u)*x_0**i in K[X].

964 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_mul_term(x**2*y + x, 3*y, 2)

3*x**4*y**2 + 3*x**3*y

sympy.polys.densearith.dmp_add_ground(f, c, u, K)
Add an element of the ground domain to f.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_add_ground(x**3 + 2*x**2 + 3*x + 4, ZZ(4))

x**3 + 2*x**2 + 3*x + 8

sympy.polys.densearith.dmp_sub_ground(f, c, u, K)
Subtract an element of the ground domain from f.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_sub_ground(x**3 + 2*x**2 + 3*x + 4, ZZ(4))

x**3 + 2*x**2 + 3*x

sympy.polys.densearith.dmp_mul_ground(f, c, u, K)
Multiply f by a constant value in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_mul_ground(2*x + 2*y, ZZ(3))

6*x + 6*y

sympy.polys.densearith.dmp_quo_ground(f, c, u, K)
Quotient by a constant in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

5.19. Polynomials Manipulation Module 965

SymPy Documentation, Release 1.3

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_quo_ground(2*x**2*y + 3*x, ZZ(2))
x**2*y + x

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_quo_ground(2*x**2*y + 3*x, QQ(2))
x**2*y + 3/2*x

sympy.polys.densearith.dmp_exquo_ground(f, c, u, K)
Exact quotient by a constant in K[X].

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_exquo_ground(x**2*y + 2*x, QQ(2))

1/2*x**2*y + x

sympy.polys.densearith.dup_lshift(f, n, K)
Efficiently multiply f by x**n in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_lshift(x**2 + 1, 2)
x**4 + x**2

sympy.polys.densearith.dup_rshift(f, n, K)
Efficiently divide f by x**n in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_rshift(x**4 + x**2, 2)

x**2 + 1
>>> R.dup_rshift(x**4 + x**2 + 2, 2)
x**2 + 1

sympy.polys.densearith.dmp_abs(f, u, K)
Make all coefficients positive in K[X].

966 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_abs(x**2*y - x)
x**2*y + x

sympy.polys.densearith.dmp_neg(f, u, K)
Negate a polynomial in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_neg(x**2*y - x)
-x**2*y + x

sympy.polys.densearith.dmp_add(f, g, u, K)
Add dense polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_add(x**2 + y, x**2*y + x)

x**2*y + x**2 + x + y

sympy.polys.densearith.dmp_sub(f, g, u, K)
Subtract dense polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_sub(x**2 + y, x**2*y + x)

-x**2*y + x**2 - x + y

sympy.polys.densearith.dmp_add_mul(f, g, h, u, K)
Returns f + g*h where f, g, h are in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

5.19. Polynomials Manipulation Module 967

SymPy Documentation, Release 1.3

>>> R.dmp_add_mul(x**2 + y, x, x + 2)
2*x**2 + 2*x + y

sympy.polys.densearith.dmp_sub_mul(f, g, h, u, K)
Returns f - g*h where f, g, h are in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_sub_mul(x**2 + y, x, x + 2)
-2*x + y

sympy.polys.densearith.dmp_mul(f, g, u, K)
Multiply dense polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_mul(x*y + 1, x)
x**2*y + x

sympy.polys.densearith.dmp_sqr(f, u, K)
Square dense polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_sqr(x**2 + x*y + y**2)

x**4 + 2*x**3*y + 3*x**2*y**2 + 2*x*y**3 + y**4

sympy.polys.densearith.dmp_pow(f, n, u, K)
Raise f to the n-th power in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_pow(x*y + 1, 3)
x**3*y**3 + 3*x**2*y**2 + 3*x*y + 1

sympy.polys.densearith.dmp_pdiv(f, g, u, K)
Polynomial pseudo-division in K[X].

968 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_pdiv(x**2 + x*y, 2*x + 2)

(2*x + 2*y - 2, -4*y + 4)

sympy.polys.densearith.dmp_prem(f, g, u, K)
Polynomial pseudo-remainder in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_prem(x**2 + x*y, 2*x + 2)

-4*y + 4

sympy.polys.densearith.dmp_pquo(f, g, u, K)
Polynomial exact pseudo-quotient in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x**2 + x*y

>>> g = 2*x + 2*y
>>> h = 2*x + 2

>>> R.dmp_pquo(f, g)
2*x

>>> R.dmp_pquo(f, h)
2*x + 2*y - 2

sympy.polys.densearith.dmp_pexquo(f, g, u, K)
Polynomial pseudo-quotient in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x**2 + x*y

>>> g = 2*x + 2*y
>>> h = 2*x + 2

5.19. Polynomials Manipulation Module 969

SymPy Documentation, Release 1.3

>>> R.dmp_pexquo(f, g)
2*x

>>> R.dmp_pexquo(f, h)
Traceback (most recent call last):
...
ExactQuotientFailed: [[2], [2]] does not divide [[1], [1, 0], []]

sympy.polys.densearith.dmp_rr_div(f, g, u, K)
Multivariate division with remainder over a ring.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_rr_div(x**2 + x*y, 2*x + 2)

(0, x**2 + x*y)

sympy.polys.densearith.dmp_ff_div(f, g, u, K)
Polynomial division with remainder over a field.

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_ff_div(x**2 + x*y, 2*x + 2)

(1/2*x + 1/2*y - 1/2, -y + 1)

sympy.polys.densearith.dmp_div(f, g, u, K)
Polynomial division with remainder in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_div(x**2 + x*y, 2*x + 2)
(0, x**2 + x*y)

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_div(x**2 + x*y, 2*x + 2)
(1/2*x + 1/2*y - 1/2, -y + 1)

sympy.polys.densearith.dmp_rem(f, g, u, K)
Returns polynomial remainder in K[X].

970 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_rem(x**2 + x*y, 2*x + 2)
x**2 + x*y

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_rem(x**2 + x*y, 2*x + 2)
-y + 1

sympy.polys.densearith.dmp_quo(f, g, u, K)
Returns exact polynomial quotient in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_quo(x**2 + x*y, 2*x + 2)
0

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_quo(x**2 + x*y, 2*x + 2)
1/2*x + 1/2*y - 1/2

sympy.polys.densearith.dmp_exquo(f, g, u, K)
Returns polynomial quotient in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x**2 + x*y

>>> g = x + y
>>> h = 2*x + 2

>>> R.dmp_exquo(f, g)
x

>>> R.dmp_exquo(f, h)
Traceback (most recent call last):
...
ExactQuotientFailed: [[2], [2]] does not divide [[1], [1, 0], []]

sympy.polys.densearith.dmp_max_norm(f, u, K)
Returns maximum norm of a polynomial in K[X].

5.19. Polynomials Manipulation Module 971

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_max_norm(2*x*y - x - 3)
3

sympy.polys.densearith.dmp_l1_norm(f, u, K)
Returns l1 norm of a polynomial in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_l1_norm(2*x*y - x - 3)
6

sympy.polys.densearith.dmp_expand(polys, u, K)
Multiply together several polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_expand([x**2 + y**2, x + 1])

x**3 + x**2 + x*y**2 + y**2

Further tools:
sympy.polys.densetools.dmp_integrate(f, m, u, K)
Computes the indefinite integral of f in x_0 in K[X].

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_integrate(x + 2*y, 1)

1/2*x**2 + 2*x*y
>>> R.dmp_integrate(x + 2*y, 2)
1/6*x**3 + x**2*y

sympy.polys.densetools.dmp_integrate_in(f, m, j, u, K)
Computes the indefinite integral of f in x_j in K[X].

972 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> R.dmp_integrate_in(x + 2*y, 1, 0)

1/2*x**2 + 2*x*y
>>> R.dmp_integrate_in(x + 2*y, 1, 1)
x*y + y**2

sympy.polys.densetools.dmp_diff(f, m, u, K)
m-th order derivative in x_0 of a polynomial in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x*y**2 + 2*x*y + 3*x + 2*y**2 + 3*y + 1

>>> R.dmp_diff(f, 1)
y**2 + 2*y + 3
>>> R.dmp_diff(f, 2)
0

sympy.polys.densetools.dmp_diff_in(f, m, j, u, K)
m-th order derivative in x_j of a polynomial in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x*y**2 + 2*x*y + 3*x + 2*y**2 + 3*y + 1

>>> R.dmp_diff_in(f, 1, 0)
y**2 + 2*y + 3
>>> R.dmp_diff_in(f, 1, 1)
2*x*y + 2*x + 4*y + 3

sympy.polys.densetools.dmp_eval(f, a, u, K)
Evaluate a polynomial at x_0 = a in K[X] using the Horner scheme.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

5.19. Polynomials Manipulation Module 973

SymPy Documentation, Release 1.3

>>> R.dmp_eval(2*x*y + 3*x + y + 2, 2)

5*y + 8

sympy.polys.densetools.dmp_eval_in(f, a, j, u, K)
Evaluate a polynomial at x_j = a in K[X] using the Horner scheme.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 2*x*y + 3*x + y + 2

>>> R.dmp_eval_in(f, 2, 0)
5*y + 8
>>> R.dmp_eval_in(f, 2, 1)
7*x + 4

sympy.polys.densetools.dmp_eval_tail(f, A, u, K)
Evaluate a polynomial at x_j = a_j, ... in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 2*x*y + 3*x + y + 2

>>> R.dmp_eval_tail(f, [2])

7*x + 4
>>> R.dmp_eval_tail(f, [2, 2])
18

sympy.polys.densetools.dmp_diff_eval_in(f, m, a, j, u, K)
Differentiate and evaluate a polynomial in x_j at a in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x*y**2 + 2*x*y + 3*x + 2*y**2 + 3*y + 1

>>> R.dmp_diff_eval_in(f, 1, 2, 0)
y**2 + 2*y + 3
>>> R.dmp_diff_eval_in(f, 1, 2, 1)
6*x + 11

sympy.polys.densetools.dmp_trunc(f, p, u, K)
Reduce a K[X] polynomial modulo a polynomial p in K[Y].

974 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y + 8*x**2 + 5*x*y + 6*x + 2*y + 3

>>> g = (y - 1).drop(x)

>>> R.dmp_trunc(f, g)
11*x**2 + 11*x + 5

sympy.polys.densetools.dmp_ground_trunc(f, p, u, K)
Reduce a K[X] polynomial modulo a constant p in K.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y + 8*x**2 + 5*x*y + 6*x + 2*y + 3

>>> R.dmp_ground_trunc(f, ZZ(3))

-x**2 - x*y - y

sympy.polys.densetools.dup_monic(f, K)
Divide all coefficients by LC(f) in K[x].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_monic(3*x**2 + 6*x + 9)
x**2 + 2*x + 3

>>> R, x = ring(”x”, QQ)

>>> R.dup_monic(3*x**2 + 4*x + 2)
x**2 + 4/3*x + 2/3

sympy.polys.densetools.dmp_ground_monic(f, u, K)
Divide all coefficients by LC(f) in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y + 6*x**2 + 3*x*y + 9*y + 3

5.19. Polynomials Manipulation Module 975

SymPy Documentation, Release 1.3

>>> R.dmp_ground_monic(f)
x**2*y + 2*x**2 + x*y + 3*y + 1

>>> R, x,y = ring(”x,y”, QQ)

>>> f = 3*x**2*y + 8*x**2 + 5*x*y + 6*x + 2*y + 3

>>> R.dmp_ground_monic(f)
x**2*y + 8/3*x**2 + 5/3*x*y + 2*x + 2/3*y + 1

sympy.polys.densetools.dup_content(f, K)
Compute the GCD of coefficients of f in K[x].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x = ring(”x”, ZZ)

>>> f = 6*x**2 + 8*x + 12

>>> R.dup_content(f)
2

>>> R, x = ring(”x”, QQ)

>>> f = 6*x**2 + 8*x + 12

>>> R.dup_content(f)
2

sympy.polys.densetools.dmp_ground_content(f, u, K)
Compute the GCD of coefficients of f in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 2*x*y + 6*x + 4*y + 12

>>> R.dmp_ground_content(f)
2

>>> R, x,y = ring(”x,y”, QQ)

>>> f = 2*x*y + 6*x + 4*y + 12

>>> R.dmp_ground_content(f)
2

sympy.polys.densetools.dup_primitive(f, K)
Compute content and the primitive form of f in K[x].

976 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x = ring(”x”, ZZ)

>>> f = 6*x**2 + 8*x + 12

>>> R.dup_primitive(f)
(2, 3*x**2 + 4*x + 6)

>>> R, x = ring(”x”, QQ)

>>> f = 6*x**2 + 8*x + 12

>>> R.dup_primitive(f)
(2, 3*x**2 + 4*x + 6)

sympy.polys.densetools.dmp_ground_primitive(f, u, K)
Compute content and the primitive form of f in K[X].

Examples

>>> from sympy.polys import ring, ZZ, QQ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 2*x*y + 6*x + 4*y + 12

>>> R.dmp_ground_primitive(f)
(2, x*y + 3*x + 2*y + 6)

>>> R, x,y = ring(”x,y”, QQ)

>>> f = 2*x*y + 6*x + 4*y + 12

>>> R.dmp_ground_primitive(f)
(2, x*y + 3*x + 2*y + 6)

sympy.polys.densetools.dup_extract(f, g, K)
Extract common content from a pair of polynomials in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_extract(6*x**2 + 12*x + 18, 4*x**2 + 8*x + 12)

(2, 3*x**2 + 6*x + 9, 2*x**2 + 4*x + 6)

sympy.polys.densetools.dmp_ground_extract(f, g, u, K)
Extract common content from a pair of polynomials in K[X].

5.19. Polynomials Manipulation Module 977

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_ground_extract(6*x*y + 12*x + 18, 4*x*y + 8*x + 12)

(2, 3*x*y + 6*x + 9, 2*x*y + 4*x + 6)

sympy.polys.densetools.dup_real_imag(f, K)
Return bivariate polynomials f1 and f2, such that f = f1 + f2*I.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dup_real_imag(x**3 + x**2 + x + 1)

(x**3 + x**2 - 3*x*y**2 + x - y**2 + 1, 3*x**2*y + 2*x*y - y**3 + y)

sympy.polys.densetools.dup_mirror(f, K)
Evaluate efficiently the composition f(-x) in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_mirror(x**3 + 2*x**2 - 4*x + 2)

-x**3 + 2*x**2 + 4*x + 2

sympy.polys.densetools.dup_scale(f, a, K)
Evaluate efficiently composition f(a*x) in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_scale(x**2 - 2*x + 1, ZZ(2))

4*x**2 - 4*x + 1

sympy.polys.densetools.dup_shift(f, a, K)
Evaluate efficiently Taylor shift f(x + a) in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

978 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> R.dup_shift(x**2 - 2*x + 1, ZZ(2))

x**2 + 2*x + 1

sympy.polys.densetools.dup_transform(f, p, q, K)
Evaluate functional transformation q**n * f(p/q) in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_transform(x**2 - 2*x + 1, x**2 + 1, x - 1)

x**4 - 2*x**3 + 5*x**2 - 4*x + 4

sympy.polys.densetools.dmp_compose(f, g, u, K)
Evaluate functional composition f(g) in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_compose(x*y + 2*x + y, y)

y**2 + 3*y

sympy.polys.densetools.dup_decompose(f, K)
Computes functional decomposition of f in K[x].
Given a univariate polynomial f with coefficients in a field of characteristic zero, returns
list [f_1, f_2, ..., f_n], where:

f = f_1 o f_2 o ... f_n = f_1(f_2(... f_n))

and f_2, ..., f_n are monic and homogeneous polynomials of at least second degree.
Unlike factorization, complete functional decompositions of polynomials are not unique,
consider examples:
1. f o g = f(x + b) o (g - b)
2. x**n o x**m = x**m o x**n
3. T_n o T_m = T_m o T_n
where T_n and T_m are Chebyshev polynomials.

References

1. [Kozen89]

[Kozen89]

5.19. Polynomials Manipulation Module 979

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_decompose(x**4 - 2*x**3 + x**2)

[x**2, x**2 - x]

sympy.polys.densetools.dmp_lift(f, u, K)
Convert algebraic coefficients to integers in K[X].

Examples

>>> from sympy.polys import ring, QQ

>>> from sympy import I

>>> K = QQ.algebraic_field(I)
>>> R, x = ring(”x”, K)

>>> f = x**2 + K([QQ(1), QQ(0)])*x + K([QQ(2), QQ(0)])

>>> R.dmp_lift(f)
x**8 + 2*x**6 + 9*x**4 - 8*x**2 + 16

sympy.polys.densetools.dup_sign_variations(f, K)
Compute the number of sign variations of f in K[x].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_sign_variations(x**4 - x**2 - x + 1)

2

sympy.polys.densetools.dmp_clear_denoms(f, u, K0, K1=None, convert=False)

Clear denominators, i.e. transform K_0 to K_1.

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> f = QQ(1,2)*x + QQ(1,3)*y + 1

>>> R.dmp_clear_denoms(f, convert=False)

(6, 3*x + 2*y + 6)
>>> R.dmp_clear_denoms(f, convert=True)
(6, 3*x + 2*y + 6)

980 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.densetools.dmp_revert(f, g, u, K)
Compute f**(-1) mod x**n using Newton iteration.

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

Manipulation of dense, univariate polynomials with finite field coefficients

Functions in this module carry the prefix gf_, referring to the classical name “Galois Fields”
for finite fields. Note that many polynomial factorization algorithms work by reduction to the
finite field case, so having special implementations for this case is justified both by perfor-
mance, and by the necessity of certain methods which do not even make sense over general
fields.
sympy.polys.galoistools.gf_crt(U, M, K=None)
Chinese Remainder Theorem.
Given a set of integer residues u_0,...,u_n and a set of co-prime integer moduli m_0,.
..,m_n, returns an integer u, such that u = u_i mod m_i for i = ``0,...,n.
As an example consider a set of residues U = [49, 76, 65] and a set of moduli M =
[99, 97, 95]. Then we have:

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_crt
>>> from sympy.ntheory.modular import solve_congruence

>>> gf_crt([49, 76, 65], [99, 97, 95], ZZ)

639985

This is the correct result because:

>>> [639985 % m for m in [99, 97, 95]]

[49, 76, 65]

Note: this is a low-level routine with no error checking.

See also:

sympy.ntheory.modular.crt (page 329) a higher level crt routine

sympy.ntheory.modular.solve_congruence (page 330)

sympy.polys.galoistools.gf_crt1(M, K)
First part of the Chinese Remainder Theorem.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_crt1

5.19. Polynomials Manipulation Module 981

SymPy Documentation, Release 1.3

>>> gf_crt1([99, 97, 95], ZZ)

(912285, [9215, 9405, 9603], [62, 24, 12])

sympy.polys.galoistools.gf_crt2(U, M, p, E, S, K)
Second part of the Chinese Remainder Theorem.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_crt2

>>> U = [49, 76, 65]

>>> M = [99, 97, 95]
>>> p = 912285
>>> E = [9215, 9405, 9603]
>>> S = [62, 24, 12]

>>> gf_crt2(U, M, p, E, S, ZZ)

639985

sympy.polys.galoistools.gf_int(a, p)
Coerce a mod p to an integer in the range [-p/2, p/2].

Examples

>>> from sympy.polys.galoistools import gf_int

>>> gf_int(2, 7)
2
>>> gf_int(5, 7)
-2

sympy.polys.galoistools.gf_degree(f)
Return the leading degree of f.

Examples

>>> from sympy.polys.galoistools import gf_degree

>>> gf_degree([1, 1, 2, 0])

3
>>> gf_degree([])
-1

sympy.polys.galoistools.gf_LC(f, K)
Return the leading coefficient of f.

982 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_LC

>>> gf_LC([3, 0, 1], ZZ)

3

sympy.polys.galoistools.gf_TC(f, K)
Return the trailing coefficient of f.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_TC

>>> gf_TC([3, 0, 1], ZZ)

1

sympy.polys.galoistools.gf_strip(f)
Remove leading zeros from f.

Examples

>>> from sympy.polys.galoistools import gf_strip

>>> gf_strip([0, 0, 0, 3, 0, 1])

[3, 0, 1]

sympy.polys.galoistools.gf_trunc(f, p)
Reduce all coefficients modulo p.

Examples

>>> from sympy.polys.galoistools import gf_trunc

>>> gf_trunc([7, -2, 3], 5)

[2, 3, 3]

sympy.polys.galoistools.gf_normal(f, p, K)
Normalize all coefficients in K.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_normal

5.19. Polynomials Manipulation Module 983

SymPy Documentation, Release 1.3

>>> gf_normal([5, 10, 21, -3], 5, ZZ)

[1, 2]

sympy.polys.galoistools.gf_from_dict(f, p, K)
Create a GF(p)[x] polynomial from a dict.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_from_dict

>>> gf_from_dict({10: ZZ(4), 4: ZZ(33), 0: ZZ(-1)}, 5, ZZ)

[4, 0, 0, 0, 0, 0, 3, 0, 0, 0, 4]

sympy.polys.galoistools.gf_to_dict(f, p, symmetric=True)
Convert a GF(p)[x] polynomial to a dict.

Examples

>>> from sympy.polys.galoistools import gf_to_dict

>>> gf_to_dict([4, 0, 0, 0, 0, 0, 3, 0, 0, 0, 4], 5)

{0: -1, 4: -2, 10: -1}
>>> gf_to_dict([4, 0, 0, 0, 0, 0, 3, 0, 0, 0, 4], 5, symmetric=False)
{0: 4, 4: 3, 10: 4}

sympy.polys.galoistools.gf_from_int_poly(f, p)
Create a GF(p)[x] polynomial from Z[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_from_int_poly

>>> gf_from_int_poly([7, -2, 3], 5)

[2, 3, 3]

sympy.polys.galoistools.gf_to_int_poly(f, p, symmetric=True)
Convert a GF(p)[x] polynomial to Z[x].

Examples

>>> from sympy.polys.galoistools import gf_to_int_poly

>>> gf_to_int_poly([2, 3, 3], 5)

[2, -2, -2]
>>> gf_to_int_poly([2, 3, 3], 5, symmetric=False)
[2, 3, 3]

984 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.galoistools.gf_neg(f, p, K)
Negate a polynomial in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_neg

>>> gf_neg([3, 2, 1, 0], 5, ZZ)

[2, 3, 4, 0]

sympy.polys.galoistools.gf_add_ground(f, a, p, K)
Compute f + a where f in GF(p)[x] and a in GF(p).

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_add_ground

>>> gf_add_ground([3, 2, 4], 2, 5, ZZ)

[3, 2, 1]

sympy.polys.galoistools.gf_sub_ground(f, a, p, K)
Compute f - a where f in GF(p)[x] and a in GF(p).

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sub_ground

>>> gf_sub_ground([3, 2, 4], 2, 5, ZZ)

[3, 2, 2]

sympy.polys.galoistools.gf_mul_ground(f, a, p, K)
Compute f * a where f in GF(p)[x] and a in GF(p).

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_mul_ground

>>> gf_mul_ground([3, 2, 4], 2, 5, ZZ)

[1, 4, 3]

sympy.polys.galoistools.gf_quo_ground(f, a, p, K)
Compute f/a where f in GF(p)[x] and a in GF(p).

5.19. Polynomials Manipulation Module 985

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_quo_ground

>>> gf_quo_ground(ZZ.map([3, 2, 4]), ZZ(2), 5, ZZ)

[4, 1, 2]

sympy.polys.galoistools.gf_add(f, g, p, K)
Add polynomials in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_add

>>> gf_add([3, 2, 4], [2, 2, 2], 5, ZZ)

[4, 1]

sympy.polys.galoistools.gf_sub(f, g, p, K)
Subtract polynomials in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sub

>>> gf_sub([3, 2, 4], [2, 2, 2], 5, ZZ)

[1, 0, 2]

sympy.polys.galoistools.gf_mul(f, g, p, K)
Multiply polynomials in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_mul

>>> gf_mul([3, 2, 4], [2, 2, 2], 5, ZZ)

[1, 0, 3, 2, 3]

sympy.polys.galoistools.gf_sqr(f, p, K)
Square polynomials in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sqr

986 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> gf_sqr([3, 2, 4], 5, ZZ)

[4, 2, 3, 1, 1]

sympy.polys.galoistools.gf_add_mul(f, g, h, p, K)
Returns f + g*h where f, g, h in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_add_mul
>>> gf_add_mul([3, 2, 4], [2, 2, 2], [1, 4], 5, ZZ)
[2, 3, 2, 2]

sympy.polys.galoistools.gf_sub_mul(f, g, h, p, K)
Compute f - g*h where f, g, h in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sub_mul

>>> gf_sub_mul([3, 2, 4], [2, 2, 2], [1, 4], 5, ZZ)

[3, 3, 2, 1]

sympy.polys.galoistools.gf_expand(F, p, K)
Expand results of factor() in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_expand

>>> gf_expand([([3, 2, 4], 1), ([2, 2], 2), ([3, 1], 3)], 5, ZZ)
[4, 3, 0, 3, 0, 1, 4, 1]

sympy.polys.galoistools.gf_div(f, g, p, K)
Division with remainder in GF(p)[x].
Given univariate polynomials f and g with coefficients in a finite field with p elements,
returns polynomials q and r (quotient and remainder) such that f = q*g + r.
Consider polynomials x**3 + x + 1 and x**2 + x in GF(2):

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_div, gf_add_mul

>>> gf_div(ZZ.map([1, 0, 1, 1]), ZZ.map([1, 1, 0]), 2, ZZ)

([1, 1], [1])

As result we obtained quotient x + 1 and remainder 1, thus:

5.19. Polynomials Manipulation Module 987

SymPy Documentation, Release 1.3

>>> gf_add_mul(ZZ.map([1]), ZZ.map([1, 1]), ZZ.map([1, 1, 0]), 2, ZZ)

[1, 0, 1, 1]

References

1. [Monagan93]
2. [Gathen99]

[Monagan93], [Gathen99]
sympy.polys.galoistools.gf_rem(f, g, p, K)
Compute polynomial remainder in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_rem

>>> gf_rem(ZZ.map([1, 0, 1, 1]), ZZ.map([1, 1, 0]), 2, ZZ)

[1]

sympy.polys.galoistools.gf_quo(f, g, p, K)
Compute exact quotient in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_quo

>>> gf_quo(ZZ.map([1, 0, 1, 1]), ZZ.map([1, 1, 0]), 2, ZZ)

[1, 1]
>>> gf_quo(ZZ.map([1, 0, 3, 2, 3]), ZZ.map([2, 2, 2]), 5, ZZ)
[3, 2, 4]

sympy.polys.galoistools.gf_exquo(f, g, p, K)
Compute polynomial quotient in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_exquo

>>> gf_exquo(ZZ.map([1, 0, 3, 2, 3]), ZZ.map([2, 2, 2]), 5, ZZ)

[3, 2, 4]

988 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> gf_exquo(ZZ.map([1, 0, 1, 1]), ZZ.map([1, 1, 0]), 2, ZZ)

Traceback (most recent call last):
...
ExactQuotientFailed: [1, 1, 0] does not divide [1, 0, 1, 1]

sympy.polys.galoistools.gf_lshift(f, n, K)
Efficiently multiply f by x**n.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_lshift

>>> gf_lshift([3, 2, 4], 4, ZZ)

[3, 2, 4, 0, 0, 0, 0]

sympy.polys.galoistools.gf_rshift(f, n, K)
Efficiently divide f by x**n.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_rshift

>>> gf_rshift([1, 2, 3, 4, 0], 3, ZZ)

([1, 2], [3, 4, 0])

sympy.polys.galoistools.gf_pow(f, n, p, K)
Compute f**n in GF(p)[x] using repeated squaring.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_pow

>>> gf_pow([3, 2, 4], 3, 5, ZZ)

[2, 4, 4, 2, 2, 1, 4]

sympy.polys.galoistools.gf_pow_mod(f, n, g, p, K)
Compute f**n in GF(p)[x]/(g) using repeated squaring.
Given polynomials f and g in GF(p)[x] and a non-negative integer n, efficiently computes
f**n (mod g) i.e. the remainder of f**n from division by g, using the repeated squaring
algorithm.

References

1. [Gathen99]

[Gathen99]

5.19. Polynomials Manipulation Module 989

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_pow_mod

>>> gf_pow_mod(ZZ.map([3, 2, 4]), 3, ZZ.map([1, 1]), 5, ZZ)

[]

sympy.polys.galoistools.gf_gcd(f, g, p, K)
Euclidean Algorithm in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_gcd

>>> gf_gcd(ZZ.map([3, 2, 4]), ZZ.map([2, 2, 3]), 5, ZZ)

[1, 3]

sympy.polys.galoistools.gf_lcm(f, g, p, K)
Compute polynomial LCM in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_lcm

>>> gf_lcm(ZZ.map([3, 2, 4]), ZZ.map([2, 2, 3]), 5, ZZ)

[1, 2, 0, 4]

sympy.polys.galoistools.gf_cofactors(f, g, p, K)
Compute polynomial GCD and cofactors in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_cofactors

>>> gf_cofactors(ZZ.map([3, 2, 4]), ZZ.map([2, 2, 3]), 5, ZZ)

([1, 3], [3, 3], [2, 1])

sympy.polys.galoistools.gf_gcdex(f, g, p, K)
Extended Euclidean Algorithm in GF(p)[x].
Given polynomials f and g in GF(p)[x], computes polynomials s, t and h, such that h
= gcd(f, g) and s*f + t*g = h. The typical application of EEA is solving polynomial
diophantine equations.
Consider polynomials f = (x + 7) (x + 1), g = (x + 7) (x**2 + 1) in GF(11)[x].
Application of Extended Euclidean Algorithm gives:

990 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_gcdex, gf_mul, gf_add

>>> s, t, g = gf_gcdex(ZZ.map([1, 8, 7]), ZZ.map([1, 7, 1, 7]), 11, ZZ)

>>> s, t, g
([5, 6], [6], [1, 7])

As result we obtained polynomials s = 5*x + 6 and t = 6, and additionally gcd(f, g)

= x + 7. This is correct because:

>>> S = gf_mul(s, ZZ.map([1, 8, 7]), 11, ZZ)

>>> T = gf_mul(t, ZZ.map([1, 7, 1, 7]), 11, ZZ)

>>> gf_add(S, T, 11, ZZ) == [1, 7]

True

References

1. [Gathen99]

[Gathen99]
sympy.polys.galoistools.gf_monic(f, p, K)
Compute LC and a monic polynomial in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_monic

>>> gf_monic(ZZ.map([3, 2, 4]), 5, ZZ)

(3, [1, 4, 3])

sympy.polys.galoistools.gf_diff(f, p, K)
Differentiate polynomial in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_diff

>>> gf_diff([3, 2, 4], 5, ZZ)

[1, 2]

sympy.polys.galoistools.gf_eval(f, a, p, K)
Evaluate f(a) in GF(p) using Horner scheme.

5.19. Polynomials Manipulation Module 991

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_eval

>>> gf_eval([3, 2, 4], 2, 5, ZZ)

0

sympy.polys.galoistools.gf_multi_eval(f, A, p, K)
Evaluate f(a) for a in [a_1, ..., a_n].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_multi_eval

>>> gf_multi_eval([3, 2, 4], [0, 1, 2, 3, 4], 5, ZZ)

[4, 4, 0, 2, 0]

sympy.polys.galoistools.gf_compose(f, g, p, K)
Compute polynomial composition f(g) in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_compose

>>> gf_compose([3, 2, 4], [2, 2, 2], 5, ZZ)

[2, 4, 0, 3, 0]

sympy.polys.galoistools.gf_compose_mod(g, h, f, p, K)
Compute polynomial composition g(h) in GF(p)[x]/(f).

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_compose_mod

>>> gf_compose_mod(ZZ.map([3, 2, 4]), ZZ.map([2, 2, 2]), ZZ.map([4, 3]), 5, ZZ)

[4]

sympy.polys.galoistools.gf_trace_map(a, b, c, n, f, p, K)
Compute polynomial trace map in GF(p)[x]/(f).
Given a polynomial f in GF(p)[x], polynomials a, b, c in the quotient ring GF(p)[x]/(f)
such that b = c**t (mod f) for some positive power t of p, and a positive integer n,
returns a mapping:

a -> a**t**n, a + a**t + a**t**2 + ... + a**t**n (mod f)

992 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

In factorization context, b = x**p mod f and c = x mod f. This way we can efficiently
compute trace polynomials in equal degree factorization routine, much faster than with
other methods, like iterated Frobenius algorithm, for large degrees.

References

1. [Gathen92]

[Gathen92]

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_trace_map

>>> gf_trace_map([1, 2], [4, 4], [1, 1], 4, [3, 2, 4], 5, ZZ)
([1, 3], [1, 3])

sympy.polys.galoistools.gf_random(n, p, K)
Generate a random polynomial in GF(p)[x] of degree n.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_random
>>> gf_random(10, 5, ZZ) #doctest: +SKIP
[1, 2, 3, 2, 1, 1, 1, 2, 0, 4, 2]

sympy.polys.galoistools.gf_irreducible(n, p, K)
Generate random irreducible polynomial of degree n in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_irreducible
>>> gf_irreducible(10, 5, ZZ) #doctest: +SKIP
[1, 4, 2, 2, 3, 2, 4, 1, 4, 0, 4]

sympy.polys.galoistools.gf_irreducible_p(f, p, K)
Test irreducibility of a polynomial f in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_irreducible_p

5.19. Polynomials Manipulation Module 993

SymPy Documentation, Release 1.3

>>> gf_irreducible_p(ZZ.map([1, 4, 2, 2, 3, 2, 4, 1, 4, 0, 4]), 5, ZZ)

True
>>> gf_irreducible_p(ZZ.map([3, 2, 4]), 5, ZZ)
False

sympy.polys.galoistools.gf_sqf_p(f, p, K)
Return True if f is square-free in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sqf_p

>>> gf_sqf_p(ZZ.map([3, 2, 4]), 5, ZZ)

True
>>> gf_sqf_p(ZZ.map([2, 4, 4, 2, 2, 1, 4]), 5, ZZ)
False

sympy.polys.galoistools.gf_sqf_part(f, p, K)
Return square-free part of a GF(p)[x] polynomial.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_sqf_part

>>> gf_sqf_part(ZZ.map([1, 1, 3, 0, 1, 0, 2, 2, 1]), 5, ZZ)

[1, 4, 3]

sympy.polys.galoistools.gf_sqf_list(f, p, K, all=False)
Return the square-free decomposition of a GF(p)[x] polynomial.
Given a polynomial f in GF(p)[x], returns the leading coefficient of f and a square-free
decomposition f_1**e_1 f_2**e_2 ... f_k**e_k such that all f_i are monic polyno-
mials and (f_i, f_j) for i != j are co-prime and e_1 ... e_k are given in increasing
order. All trivial terms (i.e. f_i = 1) aren’t included in the output.
Consider polynomial f = x**11 + 1 over GF(11)[x]:

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import (

... gf_from_dict, gf_diff, gf_sqf_list, gf_pow,
... )
...

>>> f = gf_from_dict({11: ZZ(1), 0: ZZ(1)}, 11, ZZ)

Note that f'(x) = 0:

>>> gf_diff(f, 11, ZZ)

[]

994 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

This phenomenon doesn’t happen in characteristic zero. However we can still compute
square-free decomposition of f using gf_sqf():

>>> gf_sqf_list(f, 11, ZZ)

(1, [([1, 1], 11)])

We obtained factorization f = (x + 1)**11. This is correct because:

>>> gf_pow([1, 1], 11, 11, ZZ) == f

True

References

1. [Geddes92]

[Geddes92]
sympy.polys.galoistools.gf_Qmatrix(f, p, K)
Calculate Berlekamp’s Q matrix.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_Qmatrix

>>> gf_Qmatrix([3, 2, 4], 5, ZZ)

[[1, 0],
[3, 4]]

>>> gf_Qmatrix([1, 0, 0, 0, 1], 5, ZZ)

[[1, 0, 0, 0],
[0, 4, 0, 0],
[0, 0, 1, 0],
[0, 0, 0, 4]]

sympy.polys.galoistools.gf_Qbasis(Q, p, K)
Compute a basis of the kernel of Q.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_Qmatrix, gf_Qbasis

>>> gf_Qbasis(gf_Qmatrix([1, 0, 0, 0, 1], 5, ZZ), 5, ZZ)

[[1, 0, 0, 0], [0, 0, 1, 0]]

>>> gf_Qbasis(gf_Qmatrix([3, 2, 4], 5, ZZ), 5, ZZ)

[[1, 0]]

sympy.polys.galoistools.gf_berlekamp(f, p, K)
Factor a square-free f in GF(p)[x] for small p.

5.19. Polynomials Manipulation Module 995

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_berlekamp

>>> gf_berlekamp([1, 0, 0, 0, 1], 5, ZZ)

[[1, 0, 2], [1, 0, 3]]

sympy.polys.galoistools.gf_zassenhaus(f, p, K)
Factor a square-free f in GF(p)[x] for medium p.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_zassenhaus

>>> gf_zassenhaus(ZZ.map([1, 4, 3]), 5, ZZ)

[[1, 1], [1, 3]]

sympy.polys.galoistools.gf_shoup(f, p, K)
Factor a square-free f in GF(p)[x] for large p.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_shoup

>>> gf_shoup(ZZ.map([1, 4, 3]), 5, ZZ)

[[1, 1], [1, 3]]

sympy.polys.galoistools.gf_factor_sqf(f, p, K, method=None)
Factor a square-free polynomial f in GF(p)[x].

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_factor_sqf

>>> gf_factor_sqf(ZZ.map([3, 2, 4]), 5, ZZ)

(3, [[1, 1], [1, 3]])

sympy.polys.galoistools.gf_factor(f, p, K)
Factor (non square-free) polynomials in GF(p)[x].
Given a possibly non square-free polynomial f in GF(p)[x], returns its complete factor-
ization into irreducibles:

f_1(x)**e_1 f_2(x)**e_2 ... f_d(x)**e_d

996 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

where each f_i is a monic polynomial and gcd(f_i, f_j) == 1, for i != j. The result
is given as a tuple consisting of the leading coefficient of f and a list of factors of f with
their multiplicities.
The algorithm proceeds by first computing square-free decomposition of f and then it-
eratively factoring each of square-free factors.
Consider a non square-free polynomial f = (7*x + 1) (x + 2)**2 in GF(11)[x]. We
obtain its factorization into irreducibles as follows:

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.galoistools import gf_factor

>>> gf_factor(ZZ.map([5, 2, 7, 2]), 11, ZZ)

(5, [([1, 2], 1), ([1, 8], 2)])

We arrived with factorization f = 5 (x + 2) (x + 8)**2. We didn’t recover the exact

form of the input polynomial because we requested to get monic factors of f and its
leading coefficient separately.
Square-free factors of f can be factored into irreducibles over GF(p) using three very
different methods:
Berlekamp efficient for very small values of p (usually p < 25)
Cantor-Zassenhaus efficient on average input and with “typical” p
Shoup-Kaltofen-Gathen efficient with very large inputs and modulus
If you want to use a specific factorization method, instead of the default one, set
GF_FACTOR_METHOD with one of berlekamp, zassenhaus or shoup values.

References

1. [Gathen99]

[Gathen99]
sympy.polys.galoistools.gf_value(f, a)
Value of polynomial ‘f’ at ‘a’ in field R.

Examples

>>> from sympy.polys.galoistools import gf_value

>>> gf_value([1, 7, 2, 4], 11)

2204

sympy.polys.galoistools.gf_csolve(f, n)
To solve f(x) congruent 0 mod(n).
n is divided into canonical factors and f(x) cong 0 mod(p**e) will be solved for each factor.
Applying the Chinese Remainder Theorem to the results returns the final answers.

5.19. Polynomials Manipulation Module 997

SymPy Documentation, Release 1.3

References

[1] ‘An introduction to the Theory of Numbers’ 5th Edition by Ivan Niven,
Zuckerman and Montgomery.

Examples

Solve [1, 1, 7] congruent 0 mod(189):

>>> from sympy.polys.galoistools import gf_csolve

>>> gf_csolve([1, 1, 7], 189)
[13, 49, 76, 112, 139, 175]

Manipulation of sparse, distributed polynomials and vectors

Dense representations quickly require infeasible amounts of storage and computation time if
the number of variables increases. For this reason, there is code to manipulate polynomials
in a sparse representation.
Sparse polynomials are represented as dictionaries.
sympy.polys.rings.ring(symbols, domain, order=LexOrder())
Construct a polynomial ring returning (ring, x_1, ..., x_n).
Parameters symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (non-
empty)
domain : Domain or coercible
order : Order or coercible, optional, defaults to lex

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex

>>> R, x, y, z = ring(”x,y,z”, ZZ, lex)

>>> R
Polynomial ring in x, y, z over ZZ with lex order
>>> x + y + z
x + y + z
>>> type(_)
<class 'sympy.polys.rings.PolyElement'>

sympy.polys.rings.xring(symbols, domain, order=LexOrder())

Construct a polynomial ring returning (ring, (x_1, ..., x_n)).
Parameters symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (non-
empty)
domain : Domain or coercible
order : Order or coercible, optional, defaults to lex

998 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.rings import xring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex

>>> R, (x, y, z) = xring(”x,y,z”, ZZ, lex)

>>> R
Polynomial ring in x, y, z over ZZ with lex order
>>> x + y + z
x + y + z
>>> type(_)
<class 'sympy.polys.rings.PolyElement'>

sympy.polys.rings.vring(symbols, domain, order=LexOrder())

Construct a polynomial ring and inject x_1, ..., x_n into the global namespace.
Parameters symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (non-
empty)
domain : Domain or coercible
order : Order or coercible, optional, defaults to lex

Examples

>>> from sympy.polys.rings import vring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex

>>> vring(”x,y,z”, ZZ, lex)

Polynomial ring in x, y, z over ZZ with lex order
>>> x + y + z
x + y + z
>>> type(_)
<class 'sympy.polys.rings.PolyElement'>

sympy.polys.rings.sring(exprs, *symbols, **options)

Construct a ring deriving generators and domain from options and input expressions.
Parameters exprs : Expr or sequence of Expr (sympifiable)
symbols : sequence of Symbol/Expr
options : keyword arguments understood by Options

Examples

>>> from sympy.core import symbols

>>> from sympy.polys.rings import sring
>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex

5.19. Polynomials Manipulation Module 999

SymPy Documentation, Release 1.3

>>> x, y, z = symbols(”x,y,z”)
>>> R, f = sring(x + 2*y + 3*z)
>>> R
Polynomial ring in x, y, z over ZZ with lex order
>>> f
x + 2*y + 3*z
>>> type(_)
<class 'sympy.polys.rings.PolyElement'>

class sympy.polys.rings.PolyRing
Multivariate distributed polynomial ring.

Attributes

domain
gens
ngens
order
symbols

add(*objs)
Add a sequence of polynomials or containers of polynomials.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.add([ x**2 + 2*i + 3 for i in range(4) ])
4*x**2 + 24
>>> _.factor_list()
(4, [(x**2 + 6, 1)])

add_gens(symbols)
Add the elements of symbols as generators to self
compose(other)
Add the generators of other to self
drop(*gens)
Remove specified generators from this ring.
drop_to_ground(*gens)
Remove specified generators from the ring and inject them into its domain.
index(gen)
Compute index of gen in self.gens.
monomial_basis(i)
Return the ith-basis element.
mul(*objs)
Multiply a sequence of polynomials or containers of polynomials.

1000 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.mul([ x**2 + 2*i + 3 for i in range(4) ])
x**8 + 24*x**6 + 206*x**4 + 744*x**2 + 945
>>> _.factor_list()
(1, [(x**2 + 3, 1), (x**2 + 5, 1), (x**2 + 7, 1), (x**2 + 9, 1)])

class sympy.polys.rings.PolyElement
Element of multivariate distributed polynomial ring.
almosteq(p2, tolerance=None)
Approximate equality test for polynomials.
cancel(g)
Cancel common factors in a rational function f/g.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> (2*x**2 - 2).cancel(x**2 - 2*x + 1)

(2*x + 2, x - 1)

coeff(element)
Returns the coefficient that stands next to the given monomial.
Parameters element : PolyElement (with is_monomial = True) or 1

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y, z = ring(”x,y,z”, ZZ)

>>> f = 3*x**2*y - x*y*z + 7*z**3 + 23

>>> f.coeff(x**2*y)
3
>>> f.coeff(x*y)
0
>>> f.coeff(1)
23

coeffs(order=None)
Ordered list of polynomial coefficients.
Parameters order : Order or coercible, optional

5.19. Polynomials Manipulation Module 1001

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex, grlex

>>> _, x, y = ring(”x, y”, ZZ, lex)

>>> f = x*y**7 + 2*x**2*y**3

>>> f.coeffs()
[2, 1]
>>> f.coeffs(grlex)
[1, 2]

const()
Returns the constant coeffcient.
content()
Returns GCD of polynomial’s coefficients.
copy()
Return a copy of polynomial self.
Polynomials are mutable; if one is interested in preserving a polynomial, and one
plans to use inplace operations, one can copy the polynomial. This method makes a
shallow copy.

Examples

>>> from sympy.polys.domains import ZZ

>>> from sympy.polys.rings import ring

>>> R, x, y = ring('x, y', ZZ)

>>> p = (x + y)**2
>>> p1 = p.copy()
>>> p2 = p
>>> p[R.zero_monom] = 3
>>> p
x**2 + 2*x*y + y**2 + 3
>>> p1
x**2 + 2*x*y + y**2
>>> p2
x**2 + 2*x*y + y**2 + 3

degree(x=None)
The leading degree in x or the main variable.
Note that the degree of 0 is negative infinity (the SymPy object -oo).
degrees()
A tuple containing leading degrees in all variables.
Note that the degree of 0 is negative infinity (the SymPy object -oo)
diff(x)
Computes partial derivative in x.

1002 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring(”x,y”, ZZ)

>>> p = x + x**2*y**3
>>> p.diff(x)
2*x*y**3 + 1

div(fv)
Division algorithm, see [CLO] p64.
fv array of polynomials return qv, r such that self = sum(fv[i]*qv[i]) + r
All polynomials are required not to be Laurent polynomials.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring('x, y', ZZ)

>>> f = x**3
>>> f0 = x - y**2
>>> f1 = x - y
>>> qv, r = f.div((f0, f1))
>>> qv[0]
x**2 + x*y**2 + y**4
>>> qv[1]
0
>>> r
y**6

imul_num(c)
multiply inplace the polynomial p by an element in the coefficient ring, provided p
is not one of the generators; else multiply not inplace

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring('x, y', ZZ)

>>> p = x + y**2
>>> p1 = p.imul_num(3)
>>> p1
3*x + 3*y**2
>>> p1 is p
True
>>> p = x
>>> p1 = p.imul_num(3)
>>> p1
(continues on next page)

5.19. Polynomials Manipulation Module 1003

SymPy Documentation, Release 1.3

(continued from previous page)

3*x
>>> p1 is p
False

itercoeffs()
Iterator over coefficients of a polynomial.
itermonoms()
Iterator over monomials of a polynomial.
iterterms()
Iterator over terms of a polynomial.
leading_expv()
Leading monomial tuple according to the monomial ordering.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y, z = ring('x, y, z', ZZ)

>>> p = x**4 + x**3*y + x**2*z**2 + z**7
>>> p.leading_expv()
(4, 0, 0)

leading_monom()
Leading monomial as a polynomial element.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring('x, y', ZZ)

>>> (3*x*y + y**2).leading_monom()
x*y

leading_term()
Leading term as a polynomial element.

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring('x, y', ZZ)

>>> (3*x*y + y**2).leading_term()
3*x*y

1004 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

listcoeffs()
Unordered list of polynomial coefficients.
listmonoms()
Unordered list of polynomial monomials.
listterms()
Unordered list of polynomial terms.
monic()
Divides all coefficients by the leading coefficient.
monoms(order=None)
Ordered list of polynomial monomials.
Parameters order : Order or coercible, optional

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex, grlex

>>> _, x, y = ring(”x, y”, ZZ, lex)

>>> f = x*y**7 + 2*x**2*y**3

>>> f.monoms()
[(2, 3), (1, 7)]
>>> f.monoms(grlex)
[(1, 7), (2, 3)]

primitive()
Returns content and a primitive polynomial.
square()
square of a polynomial

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ

>>> _, x, y = ring('x, y', ZZ)

>>> p = x + y**2
>>> p.square()
x**2 + 2*x*y**2 + y**4

strip_zero()
Eliminate monomials with zero coefficient.
tail_degree(x=None)
The tail degree in x or the main variable.
Note that the degree of 0 is negative infinity (the SymPy object -oo)

5.19. Polynomials Manipulation Module 1005

SymPy Documentation, Release 1.3

tail_degrees()
A tuple containing tail degrees in all variables.
Note that the degree of 0 is negative infinity (the SymPy object -oo)
terms(order=None)
Ordered list of polynomial terms.
Parameters order : Order or coercible, optional

Examples

>>> from sympy.polys.rings import ring

>>> from sympy.polys.domains import ZZ
>>> from sympy.polys.orderings import lex, grlex

>>> _, x, y = ring(”x, y”, ZZ, lex)

>>> f = x*y**7 + 2*x**2*y**3

>>> f.terms()
[((2, 3), 2), ((1, 7), 1)]
>>> f.terms(grlex)
[((1, 7), 1), ((2, 3), 2)]

In commutative algebra, one often studies not only polynomials, but also modules over poly-
nomial rings. The polynomial manipulation module provides rudimentary low-level support
for finitely generated free modules. This is mainly used for Groebner basis computations (see
there), so manipulation functions are only provided to the extend needed. They carry the
prefix sdm_. Note that in examples, the generators of the free module are called f1 , f2 , . . ..
sympy.polys.distributedmodules.sdm_monomial_mul(M, X)
Multiply tuple X representing a monomial of K[X] into the tuple M representing a mono-
mial of F .

Examples

Multiplying xy 3 into xf1 yields x2 y 3 f1 :

>>> from sympy.polys.distributedmodules import sdm_monomial_mul

>>> sdm_monomial_mul((1, 1, 0), (1, 3))
(1, 2, 3)

sympy.polys.distributedmodules.sdm_monomial_deg(M)
Return the total degree of M.

Examples

For example, the total degree of x2 yf5 is 3:

>>> from sympy.polys.distributedmodules import sdm_monomial_deg

>>> sdm_monomial_deg((5, 2, 1))
3

1006 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.distributedmodules.sdm_monomial_divides(A, B)
Does there exist a (polynomial) monomial X such that XA = B?

Examples

Positive examples:
In the following examples, the monomial is given in terms of x, y and the generator(s),
f_1, f_2 etc. The tuple form of that monomial is used in the call to sdm_monomial_divides.
Note: the generator appears last in the expression but first in the tuple and other factors
appear in the same order that they appear in the monomial expression.
A = f1 divides B = f1

>>> from sympy.polys.distributedmodules import sdm_monomial_divides

>>> sdm_monomial_divides((1, 0, 0), (1, 0, 0))
True

A = f1 divides B = x2 yf1

>>> sdm_monomial_divides((1, 0, 0), (1, 2, 1))

True

A = xyf5 divides B = x2 yf5

>>> sdm_monomial_divides((5, 1, 1), (5, 2, 1))

True

Negative examples:
A = f1 does not divide B = f2

>>> sdm_monomial_divides((1, 0, 0), (2, 0, 0))

False

A = xf1 does not divide B = f1

>>> sdm_monomial_divides((1, 1, 0), (1, 0, 0))

False

A = xy 2 f5 does not divide B = yf5

>>> sdm_monomial_divides((5, 1, 2), (5, 0, 1))

False

sympy.polys.distributedmodules.sdm_LC(f, K)
Returns the leading coeffcient of f.
sympy.polys.distributedmodules.sdm_to_dict(f)
Make a dictionary from a distributed polynomial.
sympy.polys.distributedmodules.sdm_from_dict(d, O)
Create an sdm from a dictionary.
Here O is the monomial order to use.

5.19. Polynomials Manipulation Module 1007

SymPy Documentation, Release 1.3

>>> from sympy.polys.distributedmodules import sdm_from_dict

>>> from sympy.polys import QQ, lex
>>> dic = {(1, 1, 0): QQ(1), (1, 0, 0): QQ(2), (0, 1, 0): QQ(0)}
>>> sdm_from_dict(dic, lex)
[((1, 1, 0), 1), ((1, 0, 0), 2)]

sympy.polys.distributedmodules.sdm_add(f, g, O, K)
Add two module elements f, g.
Addition is done over the ground field K, monomials are ordered according to O.

Examples

All examples use lexicographic order.

(xyf1 ) + (f2 ) = f2 + xyf1

>>> from sympy.polys.distributedmodules import sdm_add

>>> from sympy.polys import lex, QQ
>>> sdm_add([((1, 1, 1), QQ(1))], [((2, 0, 0), QQ(1))], lex, QQ)
[((2, 0, 0), 1), ((1, 1, 1), 1)]

(xyf1 ) + (−xyf1 ) = 0‘

>>> sdm_add([((1, 1, 1), QQ(1))], [((1, 1, 1), QQ(-1))], lex, QQ)

[]

(f1 ) + (2f1 ) = 3f1

>>> sdm_add([((1, 0, 0), QQ(1))], [((1, 0, 0), QQ(2))], lex, QQ)

[((1, 0, 0), 3)]

(yf1 ) + (xf1 ) = xf1 + yf1

>>> sdm_add([((1, 0, 1), QQ(1))], [((1, 1, 0), QQ(1))], lex, QQ)

[((1, 1, 0), 1), ((1, 0, 1), 1)]

sympy.polys.distributedmodules.sdm_LM(f)
Returns the leading monomial of f.
Only valid if f ̸= 0.

Examples

>>> from sympy.polys.distributedmodules import sdm_LM, sdm_from_dict

>>> from sympy.polys import QQ, lex
>>> dic = {(1, 2, 3): QQ(1), (4, 0, 0): QQ(1), (4, 0, 1): QQ(1)}
>>> sdm_LM(sdm_from_dict(dic, lex))
(4, 0, 1)

sympy.polys.distributedmodules.sdm_LT(f)
Returns the leading term of f.
Only valid if f ̸= 0.

1008 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.distributedmodules import sdm_LT, sdm_from_dict

>>> from sympy.polys import QQ, lex
>>> dic = {(1, 2, 3): QQ(1), (4, 0, 0): QQ(2), (4, 0, 1): QQ(3)}
>>> sdm_LT(sdm_from_dict(dic, lex))
((4, 0, 1), 3)

sympy.polys.distributedmodules.sdm_mul_term(f, term, O, K)
Multiply a distributed module element f by a (polynomial) term term.
Multiplication of coefficients is done over the ground field K, and monomials are ordered
according to O.

Examples

0f1 = 0

>>> from sympy.polys.distributedmodules import sdm_mul_term

>>> from sympy.polys import lex, QQ
>>> sdm_mul_term([((1, 0, 0), QQ(1))], ((0, 0), QQ(0)), lex, QQ)
[]

x0 = 0

>>> sdm_mul_term([], ((1, 0), QQ(1)), lex, QQ)

[]

(x)(f1 ) = xf1

>>> sdm_mul_term([((1, 0, 0), QQ(1))], ((1, 0), QQ(1)), lex, QQ)

[((1, 1, 0), 1)]

(2xy)(3xf1 + 4yf2 ) = 8xy 2 f2 + 6x2 yf1

>>> f = [((2, 0, 1), QQ(4)), ((1, 1, 0), QQ(3))]

>>> sdm_mul_term(f, ((1, 1), QQ(2)), lex, QQ)
[((2, 1, 2), 8), ((1, 2, 1), 6)]

sympy.polys.distributedmodules.sdm_zero()
Return the zero module element.
sympy.polys.distributedmodules.sdm_deg(f)
Degree of f.
This is the maximum of the degrees of all its monomials. Invalid if f is zero.

Examples

>>> from sympy.polys.distributedmodules import sdm_deg

>>> sdm_deg([((1, 2, 3), 1), ((10, 0, 1), 1), ((2, 3, 4), 4)])
7

sympy.polys.distributedmodules.sdm_from_vector(vec, O, K, **opts)
Create an sdm from an iterable of expressions.

5.19. Polynomials Manipulation Module 1009

SymPy Documentation, Release 1.3

Coefficients are created in the ground field K, and terms are ordered according to mono-
mial order O. Named arguments are passed on to the polys conversion code and can be
used to specify for example generators.

Examples

>>> from sympy.polys.distributedmodules import sdm_from_vector

>>> from sympy.abc import x, y, z
>>> from sympy.polys import QQ, lex
>>> sdm_from_vector([x**2+y**2, 2*z], lex, QQ)
[((1, 0, 0, 1), 2), ((0, 2, 0, 0), 1), ((0, 0, 2, 0), 1)]

sympy.polys.distributedmodules.sdm_to_vector(f, gens, K, n=None)

Convert sdm f into a list of polynomial expressions.
The generators for the polynomial ring are specified via gens. The rank of the module is
guessed, or passed via n. The ground field is assumed to be K.

Examples

>>> from sympy.polys.distributedmodules import sdm_to_vector

>>> from sympy.abc import x, y, z
>>> from sympy.polys import QQ, lex
>>> f = [((1, 0, 0, 1), QQ(2)), ((0, 2, 0, 0), QQ(1)), ((0, 0, 2, 0), QQ(1))]
>>> sdm_to_vector(f, [x, y, z], QQ)
[x**2 + y**2, 2*z]

Polynomial factorization algorithms

Many variants of Euclid’s algorithm:

Classical remainder sequence

Let K be a field, and consider the ring K[X] of polynomials in a single indeterminate X with
coefficients in K. Given two elements f and g of K[X] with g ̸= 0 there are unique polynomials q
and r such that f = qg + r and deg(r) < deg(g) or r = 0. They are denoted by quo(f, g) (quotient)
and rem(f, g) (remainder), so we have the division identity

f = quo(f, g)g + rem(f, g).

It follows that every ideal I of K[X] is a principal ideal, generated by any element ̸= 0 of
minimum degree (assuming I non-zero). In fact, if g is such a polynomial and f is any element
of I, rem(f, g) belongs to I as a linear combination of f and g, hence must be zero; therefore
f is a multiple of g.
Using this result it is possible to find a greatest common divisor (gcd) of any polynomials
f, g, . . . in K[X]. If I is the ideal formed by all linear combinations of the given polynomials
with coefficients in K[X], and d is its generator, then every common divisor of the polynomials
also divides d. On the other hand, the given polynomials are multiples of the generator d;
hence d is a gcd of the polynomials, denoted gcd(f, g, . . .).

1010 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

An algorithm for the gcd of two polynomials f and g in K[X] can now be obtained as follows.
By the division identity, r = rem(f, g) is in the ideal generated by f and g, as well as f is in the
ideal generated by g and r. Hence the ideals generated by the pairs (f, g) and (g, r) are the
same. Set f0 = f , f1 = g, and define recursively fi = rem(fi−2 , fi−1 ) for i ≥ 2. The recursion
ends after a finite number of steps with fk+1 = 0, since the degrees of the polynomials are
strictly decreasing. By the above remark, all the pairs (fi−1 , fi ) generate the same ideal. In
particular, the ideal generated by f and g is generated by fk alone as fk+1 = 0. Hence d = fk is
a gcd of f and g.
The sequence of polynomials f0 , f1 , . . . , fk is called the Euclidean polynomial remainder se-
quence determined by (f, g) because of the analogy with the classical Euclidean algorithm for
the gcd of natural numbers.
The algorithm may be extended to obtain an expression for d in terms of f and g by using the
full division identities to write recursively each fi as a linear combination of f and g. This
leads to an equation

d = uf + vg (u, v ∈ K[X])

analogous to Bézout’s identity in the case of integers.

sympy.polys.euclidtools.dmp_half_gcdex(f, g, u, K)
Half extended Euclidean algorithm in F [X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

sympy.polys.euclidtools.dmp_gcdex(f, g, u, K)
Extended Euclidean algorithm in F [X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

sympy.polys.euclidtools.dmp_invert(f, g, u, K)
Compute multiplicative inverse of f modulo g in F [X].

Examples

>>> from sympy.polys import ring, QQ

>>> R, x = ring(”x”, QQ)

sympy.polys.euclidtools.dmp_euclidean_prs(f, g, u, K)
Euclidean polynomial remainder sequence (PRS) in K[X].

Examples

5.19. Polynomials Manipulation Module 1011

SymPy Documentation, Release 1.3

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

Simplified remainder sequences

Assume, as is usual, that the coefficient field K is the field of fractions of an integral domain
A. In this case the coefficients (numerators and denominators) of the polynomials in the
Euclidean remainder sequence tend to grow very fast.
If A is a unique factorization domain, the coefficients may be reduced by cancelling common
factors of numerators and denominators. Further reduction is possible noting that a gcd of
polynomials in K[X] is not unique: it may be multiplied by any (non-zero) constant factor.
Any polynomial f in K[X] can be simplified by extracting the denominators and common fac-
tors of the numerators of its coefficients. This yields the representation f = cF where c ∈ K
is the content of f and F is a primitive polynomial, i.e., a polynomial in A[X] with coprime
coefficients.
It is possible to start the algorithm by replacing the given polynomials f and g with their
primitive parts. This will only modify rem(f, g) by a constant factor. Replacing it with its
primitive part and continuing recursively we obtain all the primitive parts of the polynomials
in the Euclidean remainder sequence, including the primitive gcd(f, g).
This sequence is the primitive polynomial remainder sequence. It is an example of general
polynomial remainder sequences where the computed remainders are modified by constant
multipliers (or divisors) in order to simplify the results.
sympy.polys.euclidtools.dmp_primitive_prs(f, g, u, K)
Primitive polynomial remainder sequence (PRS) in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

Subresultant sequence

The coefficients of the primitive polynomial sequence do not grow exceedingly, but the com-
putation of the primitive parts requires extra processing effort. Besides, the method only
works with fraction fields of unique factorization domains, excluding, for example, the gen-
eral number fields.
Collins [Collins67] realized that the so-called subresultant polynomials of a pair of polynomi-
als also form a generalized remainder sequence. The coefficients of these polynomials are
expressible as determinants in the coefficients of the given polynomials. Hence (the logarithm
of) their size only grows linearly. In addition, if the coefficients of the given polynomials are in
the subdomain A, so are those of the subresultant polynomials. This means that the subresul-
tant sequence is comparable to the primitive remainder sequence without relying on unique
factorization in A.

1012 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

To see how subresultants are associated with remainder sequences recall that all polynomials
h in the sequence are linear combinations of the given polynomials f and g

h = uf + vg

with polynomials u and v in K[X]. Moreover, as is seen from the extended Euclidean algorithm,
the degrees of u and v are relatively low, with limited growth from step to step.
Let n = deg(f ), and m = deg(g), and assume n ≥ m. If deg(h) = j < m, the coefficients of the
powers X k (k > j) in the products uf and vg cancel each other. In particular, the products must
have the same degree, say, l. Then deg(u) = l − n and deg(v) = l − m with a total of 2l − n − m + 2
coefficients to be determined.
On the other hand, the equality h = uf + vg implies that l − j linear combinations of the
coefficients are zero, those associated with the powers X i (j < i ≤ l), and one has a given
non-zero value, namely the leading coefficient of h.
To satisfy these l − j + 1 linear equations the total number of coefficients to be determined
cannot be lower than l − j + 1, in general. This leads to the inequality l ≥ n + m − j − 1. Taking
l = n + m − j − 1, we obtain deg(u) = m − j − 1 and deg(v) = n − j − 1.
In the case j = 0 the matrix of the resulting system of linear equations is the Sylvester matrix
S(f, g) associated to f and g, an (n + m) × (n + m) matrix with coefficients of f and g as entries.
Its determinant is the resultant res(f, g) of the pair (f, g). It is non-zero if and only if f and g
are relatively prime.
For any j in the interval from 0 to m the matrix of the linear system is an (n+m−2j)×(n+m−2j)
submatrix of the Sylvester matrix. Its determinant sj (f, g) is called the j th scalar subresultant
of f and g.
If sj (f, g) is not zero, the associated equation h = uf +vg has a unique solution where deg(h) = j
and the leading coefficient of h has any given value; the one with leading coefficient sj (f, g) is
the j th subresultant polynomial or, briefly, subresultant of the pair (f, g), and denoted Sj (f, g).
This choice guarantees that the remainining coefficients are also certain subdeterminants of
the Sylvester matrix. In particular, if f and g are in A[X], so is Sj (f, g) as well. This construction
of subresultants applies to any j between 0 and m regardless of the value of sj (f, g); if it is zero,
then deg(Sj (f, g)) < j.
The properties of subresultants are as follows. Let n0 = deg(f ), n1 = deg(g), n2 , . . . , nk be the
decreasing sequence of degrees of polynomials in a remainder sequence. Let 0 ≤ j ≤ n1 ; then
• sj (f, g) ̸= 0 if and only if j = ni for some i.
• Sj (f, g) ̸= 0 if and only if j = ni or j = ni − 1 for some i.
Normally, ni−1 − ni = 1 for 1 < i ≤ k. If ni−1 − ni > 1 for some i (the abnormal case), then
Sni−1 −1 (f, g) and Sni (f, g) are constant multiples of each other. Hence either one could be
included in the polynomial remainder sequence. The former is given by smaller determinants,
so it is expected to have smaller coefficients.
Collins defined the subresultant remainder sequence by setting

fi = Sni−1 −1 (f, g) (2 ≤ i ≤ k).

In the normal case, these are the same as the Sni (f, g). He also derived expressions for the
constants γi in the remainder formulas

γi fi = rem(fi−2 , fi−1 )

in terms of the leading coefficients of f1 , . . . , fi−1 , working in the field K.

5.19. Polynomials Manipulation Module 1013

SymPy Documentation, Release 1.3

Brown and Traub [BrownTraub71] later developed a recursive procedure for computing the
coefficients γi . Their algorithm deals with elements of the domain A exclusively (assuming
f, g ∈ A[X]). However, in the abnormal case there was a problem, a division in A which could
only be conjectured to be exact.
This was subsequently justified by Brown [Brown78] who showed that the result of the division
is, in fact, a scalar subresultant. More specifically, the constant appearing in the computation
of fi is sni−2 (f, g) (Theorem 3). The implication of this discovery is that the scalar subresultants
are computed as by-products of the algorithm, all but snk (f, g) which is not needed after finding
fk+1 = 0. Completing the last step we obtain all non-zero scalar subresultants, including the
last one which is the resultant if this does not vanish.
sympy.polys.euclidtools.dmp_inner_subresultants(f, g, u, K)
Subresultant PRS algorithm in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y - y**3 - 4

>>> g = x**2 + x*y**3 - 9

>>> a = 3*x*y**4 + y**3 - 27*y + 4

>>> b = -3*y**10 - 12*y**7 + y**6 - 54*y**4 + 8*y**3 + 729*y**2 - 216*y + 16

>>> prs = [f, g, a, b]

>>> sres = [[1], [1], [3, 0, 0, 0, 0], [-3, 0, 0, -12, 1, 0, -54, 8, 729, -216,␣
,→16]]

>>> R.dmp_inner_subresultants(f, g) == (prs, sres)

True

sympy.polys.euclidtools.dmp_subresultants(f, g, u, K)
Computes subresultant PRS of two polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y - y**3 - 4

>>> g = x**2 + x*y**3 - 9

>>> a = 3*x*y**4 + y**3 - 27*y + 4

>>> b = -3*y**10 - 12*y**7 + y**6 - 54*y**4 + 8*y**3 + 729*y**2 - 216*y + 16

>>> R.dmp_subresultants(f, g) == [f, g, a, b]

True

sympy.polys.euclidtools.dmp_prs_resultant(f, g, u, K)
Resultant algorithm in K[X] using subresultant PRS.

1014 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y - y**3 - 4

>>> g = x**2 + x*y**3 - 9

>>> a = 3*x*y**4 + y**3 - 27*y + 4

>>> b = -3*y**10 - 12*y**7 + y**6 - 54*y**4 + 8*y**3 + 729*y**2 - 216*y + 16

>>> res, prs = R.dmp_prs_resultant(f, g)

>>> res == b # resultant has n-1 variables

False
>>> res == b.drop(x)
True
>>> prs == [f, g, a, b]
True

sympy.polys.euclidtools.dmp_zz_modular_resultant(f, g, p, u, K)
Compute resultant of f and g modulo a prime p.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x + y + 2
>>> g = 2*x*y + x + 3

>>> R.dmp_zz_modular_resultant(f, g, 5)
-2*y**2 + 1

sympy.polys.euclidtools.dmp_zz_collins_resultant(f, g, u, K)
Collins’s modular resultant algorithm in Z[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = x + y + 2
>>> g = 2*x*y + x + 3

>>> R.dmp_zz_collins_resultant(f, g)
-2*y**2 - 5*y + 1

sympy.polys.euclidtools.dmp_qq_collins_resultant(f, g, u, K0)
Collins’s modular resultant algorithm in Q[X].

5.19. Polynomials Manipulation Module 1015

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y = ring(”x,y”, QQ)

>>> f = QQ(1,2)*x + y + QQ(2,3)

>>> g = 2*x*y + x + 3

>>> R.dmp_qq_collins_resultant(f, g)
-2*y**2 - 7/3*y + 5/6

sympy.polys.euclidtools.dmp_resultant(f, g, u, K, includePRS=False)
Computes resultant of two polynomials in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> f = 3*x**2*y - y**3 - 4

>>> g = x**2 + x*y**3 - 9

>>> R.dmp_resultant(f, g)
-3*y**10 - 12*y**7 + y**6 - 54*y**4 + 8*y**3 + 729*y**2 - 216*y + 16

sympy.polys.euclidtools.dmp_discriminant(f, u, K)
Computes discriminant of a polynomial in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y,z,t = ring(”x,y,z,t”, ZZ)

>>> R.dmp_discriminant(x**2*y + x*z + t)

-4*y*t + z**2

sympy.polys.euclidtools.dmp_rr_prs_gcd(f, g, u, K)
Computes polynomial GCD using subresultants over a ring.
Returns (h, cff, cfg) such that a = gcd(f, g), cff = quo(f, h), and cfg = quo(g,
h).

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> f = x**2 + 2*x*y + y**2

>>> g = x**2 + x*y

1016 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> R.dmp_rr_prs_gcd(f, g)
(x + y, x + y, x)

sympy.polys.euclidtools.dmp_ff_prs_gcd(f, g, u, K)
Computes polynomial GCD using subresultants over a field.
Returns (h, cff, cfg) such that a = gcd(f, g), cff = quo(f, h), and cfg = quo(g,
h).

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y, = ring(”x,y”, QQ)

>>> f = QQ(1,2)*x**2 + x*y + QQ(1,2)*y**2

>>> g = x**2 + x*y

>>> R.dmp_ff_prs_gcd(f, g)
(x + y, 1/2*x + 1/2*y, x)

sympy.polys.euclidtools.dmp_zz_heu_gcd(f, g, u, K)
Heuristic polynomial GCD in Z[X].
Given univariate polynomials f and g in Z[X], returns their GCD and cofactors, i.e. poly-
nomials h, cff and cfg such that:

h = gcd(f, g), cff = quo(f, h) and cfg = quo(g, h)

The algorithm is purely heuristic which means it may fail to compute the GCD. This will
be signaled by raising an exception. In this case you will need to switch to another GCD
method.
The algorithm computes the polynomial GCD by evaluating polynomials f and g at certain
points and computing (fast) integer GCD of those evaluations. The polynomial GCD is
recovered from the integer image by interpolation. The evaluation process reduces f and
g variable by variable into a large integer. The final step is to verify if the interpolated
polynomial is the correct GCD. This gives cofactors of the input polynomials as a side
effect.

References

1. [Liao95]

[Liao95]

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

5.19. Polynomials Manipulation Module 1017

SymPy Documentation, Release 1.3

>>> f = x**2 + 2*x*y + y**2

>>> g = x**2 + x*y

>>> R.dmp_zz_heu_gcd(f, g)
(x + y, x + y, x)

sympy.polys.euclidtools.dmp_qq_heu_gcd(f, g, u, K0)
Heuristic polynomial GCD in Q[X].
Returns (h, cff, cfg) such that a = gcd(f, g), cff = quo(f, h), and cfg = quo(g,
h).

Examples

>>> from sympy.polys import ring, QQ

>>> R, x,y, = ring(”x,y”, QQ)

>>> f = QQ(1,4)*x**2 + x*y + y**2

>>> g = QQ(1,2)*x**2 + x*y

>>> R.dmp_qq_heu_gcd(f, g)
(x + 2*y, 1/4*x + 1/2*y, 1/2*x)

sympy.polys.euclidtools.dmp_inner_gcd(f, g, u, K)
Computes polynomial GCD and cofactors of f and g in K[X].
Returns (h, cff, cfg) such that a = gcd(f, g), cff = quo(f, h), and cfg = quo(g,
h).

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> f = x**2 + 2*x*y + y**2

>>> g = x**2 + x*y

>>> R.dmp_inner_gcd(f, g)
(x + y, x + y, x)

sympy.polys.euclidtools.dmp_gcd(f, g, u, K)
Computes polynomial GCD of f and g in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> f = x**2 + 2*x*y + y**2

>>> g = x**2 + x*y

1018 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> R.dmp_gcd(f, g)
x + y

sympy.polys.euclidtools.dmp_lcm(f, g, u, K)
Computes polynomial LCM of f and g in K[X].

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> f = x**2 + 2*x*y + y**2

>>> g = x**2 + x*y

>>> R.dmp_lcm(f, g)
x**3 + 2*x**2*y + x*y**2

sympy.polys.euclidtools.dmp_content(f, u, K)
Returns GCD of multivariate coefficients.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> R.dmp_content(2*x*y + 6*x + 4*y + 12)

2*y + 6

sympy.polys.euclidtools.dmp_primitive(f, u, K)
Returns multivariate content and a primitive polynomial.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y, = ring(”x,y”, ZZ)

>>> R.dmp_primitive(2*x*y + 6*x + 4*y + 12)

(2*y + 6, x + 2)

sympy.polys.euclidtools.dmp_cancel(f, g, u, K, include=True)
Cancel common factors in a rational function f /g.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

5.19. Polynomials Manipulation Module 1019

SymPy Documentation, Release 1.3

>>> R.dmp_cancel(2*x**2 - 2, x**2 - 2*x + 1)

(2*x + 2, x - 1)

Polynomial factorization in characteristic zero:

sympy.polys.factortools.dmp_trial_division(f, factors, u, K)
Determine multiplicities of factors using trial division.
sympy.polys.factortools.dmp_zz_mignotte_bound(f, u, K)
Mignotte bound for multivariate polynomials in K[X].
sympy.polys.factortools.dup_zz_hensel_step(m, f, g, h, s, t, K)
One step in Hensel lifting in Z[x].
Given positive integer m and Z[x] polynomials f , g, h, s and t such that:
f == g*h (mod m)
s*g + t*h == 1 (mod m)

lc(f) is not a zero divisor (mod m)

lc(h) == 1

deg(f) == deg(g) + deg(h)

deg(s) < deg(h)
deg(t) < deg(g)

returns polynomials G, H, S and T , such that:

f == G*H (mod m**2)
S*G + T**H == 1 (mod m**2)

References

1. [Gathen99]

[Gathen99]
sympy.polys.factortools.dup_zz_hensel_lift(p, f, f_list, l, K)
Multifactor Hensel lifting in Z[x].
Given a prime p, polynomial f over Z[x] such that lc(f ) is a unit modulo p, monic pair-wise
coprime polynomials fi over Z[x] satisfying:
f = lc(f) f_1 ... f_r (mod p)

and a positive integer l, returns a list of monic polynomials F1 , F2 , …, Fr satisfying:

f = lc(f) F_1 ... F_r (mod p**l)

F_i = f_i (mod p), i = 1..r

References

1. [Gathen99]

[Gathen99]

1020 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.factortools.dup_zz_zassenhaus(f, K)
Factor primitive square-free polynomials in Z[x].
sympy.polys.factortools.dup_zz_irreducible_p(f, K)
Test irreducibility using Eisenstein’s criterion.
sympy.polys.factortools.dup_cyclotomic_p(f, K, irreducible=False)
Efficiently test if f is a cyclotomic polnomial.

Examples

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> f = x**16 + x**14 - x**10 + x**8 - x**6 + x**2 + 1

>>> R.dup_cyclotomic_p(f)
False

>>> g = x**16 + x**14 - x**10 - x**8 - x**6 + x**2 + 1

>>> R.dup_cyclotomic_p(g)
True

sympy.polys.factortools.dup_zz_cyclotomic_poly(n, K)
Efficiently generate n-th cyclotomic polnomial.
sympy.polys.factortools.dup_zz_cyclotomic_factor(f, K)
Efficiently factor polynomials x ∗ ∗n − 1 and x ∗ ∗n + 1 in Z[x].
Given a univariate polynomial f in Z[x] returns a list of factors of f , provided that f is in
the form x ∗ ∗n − 1 or x ∗ ∗n + 1 for n >= 1. Otherwise returns None.
Factorization is performed using using cyclotomic decomposition of f , which makes this
method much faster that any other direct factorization approach (e.g. Zassenhaus’s).

References

1. [Weisstein09]

[Weisstein09]
sympy.polys.factortools.dup_zz_factor_sqf(f, K)
Factor square-free (non-primitive) polyomials in Z[x].
sympy.polys.factortools.dup_zz_factor(f, K)
Factor (non square-free) polynomials in Z[x].
Given a univariate polynomial f in Z[x] computes its complete factorization f1 , ..., fn into
irreducibles over integers:

f = content(f) f_1**k_1 ... f_n**k_n

The factorization is computed by reducing the input polynomial into a primitive square-
free polynomial and factoring it using Zassenhaus algorithm. Trial division is used to
recover the multiplicities of factors.
The result is returned as a tuple consisting of:

5.19. Polynomials Manipulation Module 1021

SymPy Documentation, Release 1.3

(content(f), [(f_1, k_1), ..., (f_n, k_n))

Consider polynomial f = 2 ∗ x ∗ ∗4 − 2:

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> R.dup_zz_factor(2*x**4 - 2)
(2, [(x - 1, 1), (x + 1, 1), (x**2 + 1, 1)])

In result we got the following factorization:

f = 2 (x - 1) (x + 1) (x**2 + 1)

Note that this is a complete factorization over integers, however over Gaussian integers
we can factor the last term.
By default, polynomials x∗∗n−1 and x∗∗n+1 are factored using cyclotomic decomposition
to speedup computations. To disable this behaviour set cyclotomic=False.

References

1. [Gathen99]

[Gathen99]
sympy.polys.factortools.dmp_zz_wang_non_divisors(E, cs, ct, K)
Wang/EEZ: Compute a set of valid divisors.
sympy.polys.factortools.dmp_zz_wang_test_points(f, T, ct, A, u, K)
Wang/EEZ: Test evaluation points for suitability.
sympy.polys.factortools.dmp_zz_wang_lead_coeffs(f, T, cs, E, H, A, u, K)
Wang/EEZ: Compute correct leading coefficients.
sympy.polys.factortools.dmp_zz_diophantine(F, c, A, d, p, u, K)
Wang/EEZ: Solve multivariate Diophantine equations.
sympy.polys.factortools.dmp_zz_wang_hensel_lifting(f, H, LC, A, p, u, K)
Wang/EEZ: Parallel Hensel lifting algorithm.
sympy.polys.factortools.dmp_zz_wang(f, u, K, mod=None, seed=None)
Factor primitive square-free polynomials in Z[X].
Given a multivariate polynomial f in Z[x1 , ..., xn ], which is primitive and square-free in x1 ,
computes factorization of f into irreducibles over integers.
The procedure is based on Wang’s Enhanced Extended Zassenhaus algorithm. The al-
gorithm works by viewing f as a univariate polynomial in Z[x2 , ..., xn ][x1 ], for which an
evaluation mapping is computed:

x_2 -> a_2, ..., x_n -> a_n

where ai , for i = 2, ..., n, are carefully chosen integers. The mapping is used to transform f
into a univariate polynomial in Z[x1 ], which can be factored efficiently using Zassenhaus
algorithm. The last step is to lift univariate factors to obtain true multivariate factors.
For this purpose a parallel Hensel lifting procedure is used.

1022 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The parameter seed is passed to _randint and can be used to seed randint (when an
integer) or (for testing purposes) can be a sequence of numbers.

References

1. [Wang78]
2. [Geddes92]

[Wang78], [Geddes92]
sympy.polys.factortools.dmp_zz_factor(f, u, K)
Factor (non square-free) polynomials in Z[X].
Given a multivariate polynomial f in Z[x] computes its complete factorization f1 , ..., fn into
irreducibles over integers:

f = content(f) f_1**k_1 ... f_n**k_n

The factorization is computed by reducing the input polynomial into a primitive square-
free polynomial and factoring it using Enhanced Extended Zassenhaus (EEZ) algorithm.
Trial division is used to recover the multiplicities of factors.
The result is returned as a tuple consisting of:

(content(f), [(f_1, k_1), ..., (f_n, k_n))

Consider polynomial f = 2 ∗ (x ∗ ∗2 − y ∗ ∗2):

>>> from sympy.polys import ring, ZZ

>>> R, x,y = ring(”x,y”, ZZ)

>>> R.dmp_zz_factor(2*x**2 - 2*y**2)

(2, [(x - y, 1), (x + y, 1)])

In result we got the following factorization:

f = 2 (x - y) (x + y)

References

1. [Gathen99]

[Gathen99]
sympy.polys.factortools.dmp_ext_factor(f, u, K)
Factor multivariate polynomials over algebraic number fields.
sympy.polys.factortools.dup_gf_factor(f, K)
Factor univariate polynomials over finite fields.
sympy.polys.factortools.dmp_factor_list(f, u, K0)
Factor polynomials into irreducibles in K[X].
sympy.polys.factortools.dmp_factor_list_include(f, u, K)
Factor polynomials into irreducibles in K[X].

5.19. Polynomials Manipulation Module 1023

SymPy Documentation, Release 1.3

sympy.polys.factortools.dmp_irreducible_p(f, u, K)
Returns True if f has no factors over its domain.

Groebner basis algorithms

Groebner bases can be used to answer many problems in computational commutative algebra.
Their computation in rather complicated, and very performance-sensitive. We present here
various low-level implementations of Groebner basis computation algorithms; please see the
previous section of the manual for usage.
sympy.polys.groebnertools.groebner(seq, ring, method=None)
Computes Groebner basis for a set of polynomials in K[X].
Wrapper around the (default) improved Buchberger and the other algorithms for com-
puting Groebner bases. The choice of algorithm can be changed via method argument
or setup() from sympy.polys.polyconfig, where method can be either buchberger or
f5b.
sympy.polys.groebnertools.spoly(p1, p2, ring)
Compute LCM(LM(p1), LM(p2))/LM(p1)*p1 - LCM(LM(p1), LM(p2))/LM(p2)*p2 This is
the S-poly provided p1 and p2 are monic
sympy.polys.groebnertools.red_groebner(G, ring)
Compute reduced Groebner basis, from BeckerWeispfenning93, p. 216
Selects a subset of generators, that already generate the ideal and computes a reduced
Groebner basis for them.
sympy.polys.groebnertools.is_groebner(G, ring)
Check if G is a Groebner basis.
sympy.polys.groebnertools.is_minimal(G, ring)
Checks if G is a minimal Groebner basis.
sympy.polys.groebnertools.is_reduced(G, ring)
Checks if G is a reduced Groebner basis.
sympy.polys.fglmtools.matrix_fglm(F, ring, O_to)
Converts the reduced Groebner basis F of a zero-dimensional ideal w.r.t. O_from to a
reduced Groebner basis w.r.t. O_to.

References

J.C. Faugere, P. Gianni, D. Lazard, T. Mora (1994). Efficient Computation of Zero-

dimensional Groebner Bases by Change of Ordering
Groebner basis algorithms for modules are also provided:
sympy.polys.distributedmodules.sdm_spoly(f, g, O, K, phantom=None)
Compute the generalized s-polynomial of f and g.
The ground field is assumed to be K, and monomials ordered according to O.
This is invalid if either of f or g is zero.
If the leading terms of f and g involve different basis elements of F , their s-poly is defined
to be zero. Otherwise it is a certain linear combination of f and g in which the leading
terms cancel. See [SCA, defn 2.3.6] for details.

1024 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If phantom is not None, it should be a pair of module elements on which to perform the
same operation(s) as on f and g. The in this case both results are returned.

Examples

>>> from sympy.polys.distributedmodules import sdm_spoly

>>> from sympy.polys import QQ, lex
>>> f = [((2, 1, 1), QQ(1)), ((1, 0, 1), QQ(1))]
>>> g = [((2, 3, 0), QQ(1))]
>>> h = [((1, 2, 3), QQ(1))]
>>> sdm_spoly(f, h, lex, QQ)
[]
>>> sdm_spoly(f, g, lex, QQ)
[((1, 2, 1), 1)]

sympy.polys.distributedmodules.sdm_ecart(f)
Compute the ecart of f.
This is defined to be the difference of the total degree of f and the total degree of the
leading monomial of f [SCA, defn 2.3.7].
Invalid if f is zero.

Examples

>>> from sympy.polys.distributedmodules import sdm_ecart

>>> sdm_ecart([((1, 2, 3), 1), ((1, 0, 1), 1)])
0
>>> sdm_ecart([((2, 2, 1), 1), ((1, 5, 1), 1)])
3

sympy.polys.distributedmodules.sdm_nf_mora(f, G, O, K, phantom=None)
Compute a weak normal form of f with respect to G and order O.
The ground field is assumed to be K, and monomials ordered according to O.
Weak normal forms are defined in [SCA, defn 2.3.3]. They are not unique. This function
deterministically computes a weak normal form, depending on the order of G.
The most important property of a weak normal form is the following: if R is the ring asso-
ciated with the monomial ordering (if the ordering is global, we just have R = K[x1 , . . . , xn ],
otherwise it is a certain localization thereof), I any ideal of R and G a standard basis for
I, then for any f ∈ R, we have f ∈ I if and only if N F (f |G) = 0.
This is the generalized Mora algorithm for computing weak normal forms with respect
to arbitrary monomial orders [SCA, algorithm 2.3.9].
If phantom is not None, it should be a pair of “phantom” arguments on which to perform
the same computations as on f, G, both results are then returned.
sympy.polys.distributedmodules.sdm_groebner(G, NF, O, K, extended=False)
Compute a minimal standard basis of G with respect to order O.
The algorithm uses a normal form NF, for example sdm_nf_mora. The ground field is
assumed to be K, and monomials ordered according to O.

5.19. Polynomials Manipulation Module 1025

SymPy Documentation, Release 1.3

Let N denote the submodule generated by elements of G. A standard basis for N is a

subset S of N , such that in(S) = in(N ), where for any subset X of F , in(X) denotes the
submodule generated by the initial forms of elements of X. [SCA, defn 2.3.2]
A standard basis is called minimal if no subset of it is a standard basis.
One may show that standard bases are always generating sets.
Minimal standard bases are not unique. This algorithm computes a deterministic result,
depending on the particular order of G.
If extended=True, also compute the transition matrix from the initial generators to the
groebner basis. That is, return a list of coefficient vectors, expressing the elements of
the groebner basis in terms of the elements of G.
This functions implements the “sugar” strategy, see
Giovini et al: “One sugar cube, please” OR Selection strategies in Buchberger algorithm.

Exceptions

These are exceptions defined by the polynomials module.

TODO sort and explain
class sympy.polys.polyerrors.BasePolynomialError
Base class for polynomial related exceptions.
class sympy.polys.polyerrors.ExactQuotientFailed(f, g, dom=None)
class sympy.polys.polyerrors.OperationNotSupported(poly, func)
class sympy.polys.polyerrors.HeuristicGCDFailed
class sympy.polys.polyerrors.HomomorphismFailed
class sympy.polys.polyerrors.IsomorphismFailed
class sympy.polys.polyerrors.ExtraneousFactors
class sympy.polys.polyerrors.EvaluationFailed
class sympy.polys.polyerrors.RefinementFailed
class sympy.polys.polyerrors.CoercionFailed
class sympy.polys.polyerrors.NotInvertible
class sympy.polys.polyerrors.NotReversible
class sympy.polys.polyerrors.NotAlgebraic
class sympy.polys.polyerrors.DomainError
class sympy.polys.polyerrors.PolynomialError
class sympy.polys.polyerrors.UnificationFailed
class sympy.polys.polyerrors.GeneratorsNeeded
class sympy.polys.polyerrors.ComputationFailed(func, nargs, exc)
class sympy.polys.polyerrors.GeneratorsError
class sympy.polys.polyerrors.UnivariatePolynomialError
class sympy.polys.polyerrors.MultivariatePolynomialError

1026 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.polys.polyerrors.PolificationFailed(opt, origs, exprs, seq=False)

class sympy.polys.polyerrors.OptionError
class sympy.polys.polyerrors.FlagError

Reference

Modular GCD

sympy.polys.modulargcd.modgcd_univariate(f, g)
Computes the GCD of two polynomials in Z[x] using a modular algorithm.
The algorithm computes the GCD of two univariate integer polynomials f and g by com-
puting the GCD in Zp [x] for suitable primes p and then reconstructing the coefficients
with the Chinese Remainder Theorem. Trial division is only made for candidates which
are very likely the desired GCD.
Parameters f : PolyElement
univariate integer polynomial
g : PolyElement
univariate integer polynomial
Returns h : PolyElement
GCD of the polynomials f and g
cff : PolyElement
f
cofactor of f , i.e. h

cfg : PolyElement
g
cofactor of g, i.e. h

References

1. [Monagan00]

[Monagan00]

Examples

>>> from sympy.polys.modulargcd import modgcd_univariate

>>> from sympy.polys import ring, ZZ

>>> R, x = ring(”x”, ZZ)

>>> f = x**5 - 1
>>> g = x - 1

5.19. Polynomials Manipulation Module 1027

SymPy Documentation, Release 1.3

>>> h, cff, cfg = modgcd_univariate(f, g)

>>> h, cff, cfg
(x - 1, x**4 + x**3 + x**2 + x + 1, 1)

>>> cff * h == f
True
>>> cfg * h == g
True

>>> f = 6*x**2 - 6
>>> g = 2*x**2 + 4*x + 2

>>> h, cff, cfg = modgcd_univariate(f, g)

>>> h, cff, cfg
(2*x + 2, 3*x - 3, x + 1)

>>> cff * h == f
True
>>> cfg * h == g
True

sympy.polys.modulargcd.modgcd_bivariate(f, g)
Computes the GCD of two polynomials in Z[x, y] using a modular algorithm.
The algorithm computes the GCD of two bivariate integer polynomials f and g by calcu-
lating the GCD in Zp [x, y] for suitable primes p and then reconstructing the coefficients
with the Chinese Remainder Theorem. To compute the bivariate GCD over Zp , the poly-
nomials f mod p and g mod p are evaluated at y = a for certain a ∈ Zp and then their
univariate GCD in Zp [x] is computed. Interpolating those yields the bivariate GCD in
Zp [x, y]. To verify the result in Z[x, y], trial division is done, but only for candidates which
are very likely the desired GCD.
Parameters f : PolyElement
bivariate integer polynomial
g : PolyElement
bivariate integer polynomial
Returns h : PolyElement
GCD of the polynomials f and g
cff : PolyElement
f
cofactor of f , i.e. h

cfg : PolyElement
g
cofactor of g, i.e. h

References

1. [Monagan00]

[Monagan00]

1028 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.modulargcd import modgcd_bivariate

>>> from sympy.polys import ring, ZZ

>>> R, x, y = ring(”x, y”, ZZ)

>>> f = x**2 - y**2

>>> g = x**2 + 2*x*y + y**2

>>> h, cff, cfg = modgcd_bivariate(f, g)

>>> h, cff, cfg
(x + y, x - y, x + y)

>>> cff * h == f
True
>>> cfg * h == g
True

>>> f = x**2*y - x**2 - 4*y + 4

>>> g = x + 2

>>> h, cff, cfg = modgcd_bivariate(f, g)

>>> h, cff, cfg
(x + 2, x*y - x - 2*y + 2, 1)

>>> cff * h == f
True
>>> cfg * h == g
True

sympy.polys.modulargcd.modgcd_multivariate(f, g)
Compute the GCD of two polynomials in Z[x0 , . . . , xk−1 ] using a modular algorithm.
The algorithm computes the GCD of two multivariate integer polynomials f and g by
calculating the GCD in Zp [x0 , . . . , xk−1 ] for suitable primes p and then reconstructing the
coefficients with the Chinese Remainder Theorem. To compute the multivariate GCD
over Zp the recursive subroutine _modgcd_multivariate_p is used. To verify the result
in Z[x0 , . . . , xk−1 ], trial division is done, but only for candidates which are very likely the
desired GCD.
Parameters f : PolyElement
multivariate integer polynomial
g : PolyElement
multivariate integer polynomial
Returns h : PolyElement
GCD of the polynomials f and g
cff : PolyElement
f
cofactor of f , i.e. h

cfg : PolyElement

5.19. Polynomials Manipulation Module 1029

SymPy Documentation, Release 1.3

g
cofactor of g, i.e. h

See also:
_modgcd_multivariate_p

References

1. [Monagan00]
2. [Brown71]

[Monagan00], [Brown71]

Examples

>>> from sympy.polys.modulargcd import modgcd_multivariate

>>> from sympy.polys import ring, ZZ

>>> R, x, y = ring(”x, y”, ZZ)

>>> f = x**2 - y**2

>>> g = x**2 + 2*x*y + y**2

>>> h, cff, cfg = modgcd_multivariate(f, g)

>>> h, cff, cfg
(x + y, x - y, x + y)

>>> cff * h == f
True
>>> cfg * h == g
True

>>> R, x, y, z = ring(”x, y, z”, ZZ)

>>> f = x*z**2 - y*z**2

>>> g = x**2*z + z

>>> h, cff, cfg = modgcd_multivariate(f, g)

>>> h, cff, cfg
(z, x*z - y*z, x**2 + 1)

>>> cff * h == f
True
>>> cfg * h == g
True

sympy.polys.modulargcd.func_field_modgcd(f, g)
Compute the GCD of two polynomials f and g in Q(α)[x0 , . . . , xn−1 ] using a modular algo-
rithm.
The algorithm first computes the primitive associate m̌α (z) of the minimal polynomial
mα in Z[z] and the primitive associates of f and g in Z[x1 , . . . , xn−1 ][z]/(m̌α )[x0 ]. Then

1030 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

it computes the GCD in Q(x1 , . . . , xn−1 )[z]/(mα (z))[x0 ]. This is done by calculating the
GCD in Zp (x1 , . . . , xn−1 )[z]/(m̌α (z))[x0 ] for suitable primes p and then reconstructing the
coefficients with the Chinese Remainder Theorem and Rational Reconstuction. The
GCD over Zp (x1 , . . . , xn−1 )[z]/(m̌α (z))[x0 ] is computed with a recursive subroutine, which
evaluates the polynomials at xn−1 = a for suitable evaluation points a ∈ Zp and then
calls itself recursively until the ground domain does no longer contain any parame-
ters. For Zp [z]/(m̌α (z))[x0 ] the Euclidean Algorithm is used. The results of those re-
cursive calls are then interpolated and Rational Function Reconstruction is used to
obtain the correct coefficients. The results, both in Q(x1 , . . . , xn−1 )[z]/(mα (z))[x0 ] and
Zp (x1 , . . . , xn−1 )[z]/(m̌α (z))[x0 ], are verified by a fraction free trial division.
Apart from the above GCD computation some GCDs in Q(α)[x1 , . . . , xn−1 ] have to be cal-
culated, because treating the polynomials as univariate ones can result in a spurious
content of the GCD. For this func_field_modgcd is called recursively.
Parameters f, g : PolyElement
polynomials in Q(α)[x0 , . . . , xn−1 ]
Returns h : PolyElement
monic GCD of the polynomials f and g
cff : PolyElement
f
cofactor of f , i.e. h

cfg : PolyElement
g
cofactor of g, i.e. h

References

1. [Hoeij04]

[Hoeij04]

Examples

>>> from sympy.polys.modulargcd import func_field_modgcd

>>> from sympy.polys import AlgebraicField, QQ, ring
>>> from sympy import sqrt

>>> A = AlgebraicField(QQ, sqrt(2))

>>> R, x = ring('x', A)

>>> f = x**2 - 2
>>> g = x + sqrt(2)

>>> h, cff, cfg = func_field_modgcd(f, g)

>>> h == x + sqrt(2)
True
>>> cff * h == f
True
(continues on next page)

5.19. Polynomials Manipulation Module 1031

SymPy Documentation, Release 1.3

(continued from previous page)

>>> cfg * h == g
True

>>> R, x, y = ring('x, y', A)

>>> f = x**2 + 2*sqrt(2)*x*y + 2*y**2

>>> g = x + sqrt(2)*y

>>> h, cff, cfg = func_field_modgcd(f, g)

>>> h == x + sqrt(2)*y
True
>>> cff * h == f
True
>>> cfg * h == g
True

>>> f = x + sqrt(2)*y
>>> g = x + y

>>> h, cff, cfg = func_field_modgcd(f, g)

>>> h == R.one
True
>>> cff * h == f
True
>>> cfg * h == g
True

Undocumented

Many parts of the polys module are still undocumented, and even where there is documenta-
tion it is scarce. Please contribute!

Series Manipulation using Polynomials

Any finite Taylor series, for all practical purposes is, in fact a polynomial. This module makes
use of the efficient representation and operations of sparse polynomials for very fast multi-
variate series manipulations. Typical speedups compared to SymPy’s series method are in
the range 20-100, with the gap widening as the series being handled gets larger.
All the functions expand any given series on some ring specified by the user. Thus, the coef-
ficients of the calculated series depend on the ring being used. For example:

>>> from sympy.polys import ring, QQ, RR

>>> from sympy.polys.ring_series import rs_sin
>>> R, x, y = ring('x, y', QQ)
>>> rs_sin(x*y, x, 5)
-1/6*x**3*y**3 + x*y

1032 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

QQ stands for the Rational domain. Here all coefficients are rationals. It is recommended to
use QQ with ring series as it automatically chooses the fastest Rational type.
Similarly, if a Real domain is used:

>>> R, x, y = ring('x, y', RR)

>>> rs_sin(x*y, x, 5)
-0.166666666666667*x**3*y**3 + x*y

Though the definition of a polynomial limits the use of Polynomial module to Taylor series, we
extend it to allow Laurent and even Puiseux series (with fractional exponents):

>>> from sympy.polys.ring_series import rs_cos, rs_tan

>>> R, x, y = ring('x, y', QQ)

>>> rs_cos(x + x*y, x, 3)/x**3

-1/2*x**(-1)*y**2 - x**(-1)*y - 1/2*x**(-1) + x**(-3)

>>> rs_tan(x**QQ(2, 5)*y**QQ(1, 2), x, 2)

1/3*x**(6/5)*y**(3/2) + x**(2/5)*y**(1/2)

By default, PolyElement did not allow non-natural numbers as exponents. It converted a

fraction to an integer and raised an error on getting negative exponents. The goal of the ring
series module is fast series expansion, and not to use the polys module. The reason we use
it as our backend is simply because it implements a sparse representation and most of the
basic functions that we need. However, this default behaviour of polys was limiting for ring
series.
Note that there is no such constraint (in having rational exponents) in the data-structure used
by polys- dict. Sparse polynomials (PolyElement) use the Python dict to store a polynomial
term by term, where a tuple of exponents is the key and the coefficient of that term is the
value. There is no reason why we can’t have rational values in the dict so as to support
rational exponents.
So the approach we took was to modify sparse polys to allow non-natural exponents. And it
turned out to be quite simple. We only had to delete the conversion to int of exponents in
the __pow__ method of PolyElement. So:

>>> x**QQ(3, 4)
x**(3/4)

and not 1 as was the case earlier.

Though this change violates the definition of a polynomial, it doesn’t break anything yet.
Ideally, we shouldn’t modify polys in any way. But to have all the series capabilities we
want, no other simple way was found. If need be, we can separate the modified part of polys
from core polys. It would be great if any other elegant solution is found.
All series returned by the functions of this module are instances of the PolyElement class. To
use them with other SymPy types, convert them to Expr:

>>> from sympy.polys.ring_series import rs_exp

>>> from sympy.abc import a, b, c
>>> series = rs_exp(x, x, 5)
>>> a + series.as_expr()
a + x**4/24 + x**3/6 + x**2/2 + x + 1

5.19. Polynomials Manipulation Module 1033

SymPy Documentation, Release 1.3

rs_series

Direct use of elementary ring series functions does give more control, but is limiting at the
same time. Creating an appropriate ring for the desired series expansion and knowing which
ring series function to call, are things not everyone might be familiar with.
rs_series is a function that takes an arbitrary Expr and returns its expansion by calling the ap-
propriate ring series functions. The returned series is a polynomial over the simplest (almost)
possible ring that does the job. It recursively builds the ring as it parses the given expression,
adding generators to the ring when it needs them. Some examples:

>>> rs_series(sin(a + b), a, 5)

1/24*sin(b)*a**4 - 1/2*sin(b)*a**2 + sin(b) - 1/6*cos(b)*a**3 + cos(b)*a

>>> rs_series(sin(exp(a*b) + cos(a + c)), a, 2)

-sin(c)*cos(cos(c) + 1)*a + cos(cos(c) + 1)*a*b + sin(cos(c) + 1)

>>> rs_series(sin(a + b)*cos(a + c)*tan(a**2 + b), a, 2)

cos(b)*cos(c)*tan(b)*a - sin(b)*sin(c)*tan(b)*a + sin(b)*cos(c)*tan(b)

It can expand complicated multivariate expressions involving multiple functions and most
importantly, it does so blazingly fast:

>>> %timeit ((sin(a) + cos(a))**10).series(a, 0, 5)

1 loops, best of 3: 1.33 s per loop

>>> %timeit rs_series((sin(a) + cos(a))**10, a, 5)

100 loops, best of 3: 4.13 ms per loop

rs_series is over 300 times faster. Given an expression to expand, there is some fixed overhead
to parse it. Thus, for larger orders, the speed improvement becomes more prominent:

>>> %timeit rs_series((sin(a) + cos(a))**10, a, 100)

10 loops, best of 3: 32.8 ms per loop

To figure out the right ring for a given expression, rs_series uses the sring function, which
in turn uses other functions of polys. As explained above, non-natural exponents are not
allowed. But the restriction is on exponents and not generators. So, polys allows all sorts of
symbolic terms as generators to make sure that the exponent is a natural number:

>>> from sympy.polys.rings import sring

>>> R, expr = sring(1/a**3 + a**QQ(3, 7)); R
Polynomial ring in 1/a, a**(1/7) over ZZ with lex order

In the above example, 1/a and a ∗ ∗(1/7) will be treated as completely different atoms. For all
practical purposes, we could let b = 1/a and c = a ∗ ∗(1/7) and do the manipulations. Effectively,
expressions involving 1/a and a ∗ ∗(1/7) (and their powers) will never simplify:

>>> expr*R(1/a)
(1/a)**2 + (1/a)*(a**(1/7))**3

This leads to similar issues with manipulating Laurent and Puiseux series as faced earlier.
Fortunately, this time we have an elegant solution and are able to isolate the series and polys
behaviour from one another. We introduce a boolean flag series in the list of allowed Options
for polynomials (see sympy.polys.polyoptions.Options). Thus, when we want sring to
allow rational exponents we supply a series=True flag to sring:

1034 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> rs_series(sin(a**QQ(1, 2)), a, 3)

-1/5040*a**(7/3) + 1/120*a**(5/3) - 1/6*a + a**(1/3)

Contribute

rs_series is not fully implemented yet. As of now, it supports only multivariate Taylor ex-
pansions of expressions involving sin, cos, exp and tan. Adding the remaining functions is
not at all difficult and they will be gradually added. If you are interested in helping, read
the comments in ring_series.py. Currently, it does not support Puiseux series (though the
elementary functions do). This is expected to be fixed soon.
You can also add more functions to ring_series.py. Only elementary functions are supported
currently. The long term goal is to replace SymPy’s current series method with rs_series.

Manipulation of power series

Functions in this module carry the prefix rs_, standing for “ring series”. They manipulate
finite power series in the sparse representation provided by polys.ring.ring.
Elementary functions
sympy.polys.ring_series.rs_log(p, x, prec)
The Logarithm of p modulo O(x**prec).

Notes

Truncation of integral dx p**-1*d p/dx is used.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_log
>>> R, x = ring('x', QQ)
>>> rs_log(1 + x, x, 8)
1/7*x**7 - 1/6*x**6 + 1/5*x**5 - 1/4*x**4 + 1/3*x**3 - 1/2*x**2 + x
>>> rs_log(x**QQ(3, 2) + 1, x, 5)
1/3*x**(9/2) - 1/2*x**3 + x**(3/2)

sympy.polys.ring_series.rs_LambertW(p, x, prec)
Calculate the series expansion of the principal branch of the Lambert W function.
See also:
LambertW

Examples

5.19. Polynomials Manipulation Module 1035

SymPy Documentation, Release 1.3

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_LambertW
>>> R, x, y = ring('x, y', QQ)
>>> rs_LambertW(x + x*y, x, 3)
-x**2*y**2 - 2*x**2*y - x**2 + x*y + x

sympy.polys.ring_series.rs_exp(p, x, prec)
Exponentiation of a series modulo O(x**prec)

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_exp
>>> R, x = ring('x', QQ)
>>> rs_exp(x**2, x, 7)
1/6*x**6 + 1/2*x**4 + x**2 + 1

sympy.polys.ring_series.rs_atan(p, x, prec)
The arctangent of a series
Return the series expansion of the atan of p, about 0.
See also:
atan

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_atan
>>> R, x, y = ring('x, y', QQ)
>>> rs_atan(x + x*y, x, 4)
-1/3*x**3*y**3 - x**3*y**2 - x**3*y - 1/3*x**3 + x*y + x

sympy.polys.ring_series.rs_asin(p, x, prec)
Arcsine of a series
Return the series expansion of the asin of p, about 0.
See also:
asin

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_asin
>>> R, x, y = ring('x, y', QQ)
>>> rs_asin(x, x, 8)
5/112*x**7 + 3/40*x**5 + 1/6*x**3 + x

1036 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.polys.ring_series.rs_tan(p, x, prec)
Tangent of a series.
Return the series expansion of the tan of p, about 0.
See also:
_tan1, tan

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_tan
>>> R, x, y = ring('x, y', QQ)
>>> rs_tan(x + x*y, x, 4)
1/3*x**3*y**3 + x**3*y**2 + x**3*y + 1/3*x**3 + x*y + x

sympy.polys.ring_series.rs_cot(p, x, prec)
Cotangent of a series
Return the series expansion of the cot of p, about 0.
See also:
cot

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_cot
>>> R, x, y = ring('x, y', QQ)
>>> rs_cot(x, x, 6)
-2/945*x**5 - 1/45*x**3 - 1/3*x + x**(-1)

sympy.polys.ring_series.rs_sin(p, x, prec)
Sine of a series
Return the series expansion of the sin of p, about 0.
See also:
sin

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_sin
>>> R, x, y = ring('x, y', QQ)
>>> rs_sin(x + x*y, x, 4)
-1/6*x**3*y**3 - 1/2*x**3*y**2 - 1/2*x**3*y - 1/6*x**3 + x*y + x
>>> rs_sin(x**QQ(3, 2) + x*y**QQ(7, 5), x, 4)
-1/2*x**(7/2)*y**(14/5) - 1/6*x**3*y**(21/5) + x**(3/2) + x*y**(7/5)

5.19. Polynomials Manipulation Module 1037

SymPy Documentation, Release 1.3

sympy.polys.ring_series.rs_cos(p, x, prec)
Cosine of a series
Return the series expansion of the cos of p, about 0.
See also:
cos

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_cos
>>> R, x, y = ring('x, y', QQ)
>>> rs_cos(x + x*y, x, 4)
-1/2*x**2*y**2 - x**2*y - 1/2*x**2 + 1
>>> rs_cos(x + x*y, x, 4)/x**QQ(7, 5)
-1/2*x**(3/5)*y**2 - x**(3/5)*y - 1/2*x**(3/5) + x**(-7/5)

sympy.polys.ring_series.rs_cos_sin(p, x, prec)
Return the tuple (rs_cos(p, x, prec), rs_sin(p, x, prec)).
Is faster than calling rs_cos and rs_sin separately
sympy.polys.ring_series.rs_atanh(p, x, prec)
Hyperbolic arctangent of a series
Return the series expansion of the atanh of p, about 0.
See also:
atanh

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_atanh
>>> R, x, y = ring('x, y', QQ)
>>> rs_atanh(x + x*y, x, 4)
1/3*x**3*y**3 + x**3*y**2 + x**3*y + 1/3*x**3 + x*y + x

sympy.polys.ring_series.rs_sinh(p, x, prec)
Hyperbolic sine of a series
Return the series expansion of the sinh of p, about 0.
See also:
sinh

Examples

1038 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_sinh
>>> R, x, y = ring('x, y', QQ)
>>> rs_sinh(x + x*y, x, 4)
1/6*x**3*y**3 + 1/2*x**3*y**2 + 1/2*x**3*y + 1/6*x**3 + x*y + x

sympy.polys.ring_series.rs_cosh(p, x, prec)
Hyperbolic cosine of a series
Return the series expansion of the cosh of p, about 0.
See also:
cosh

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_cosh
>>> R, x, y = ring('x, y', QQ)
>>> rs_cosh(x + x*y, x, 4)
1/2*x**2*y**2 + x**2*y + 1/2*x**2 + 1

sympy.polys.ring_series.rs_tanh(p, x, prec)
Hyperbolic tangent of a series
Return the series expansion of the tanh of p, about 0.
See also:
tanh

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_tanh
>>> R, x, y = ring('x, y', QQ)
>>> rs_tanh(x + x*y, x, 4)
-1/3*x**3*y**3 - x**3*y**2 - x**3*y - 1/3*x**3 + x*y + x

sympy.polys.ring_series.rs_hadamard_exp(p1, inverse=False)
Return sum f_i/i!*x**i from sum f_i*x**i, where x is the first variable.
If invers=True return sum f_i*i!*x**i

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_hadamard_exp
>>> R, x = ring('x', QQ)
(continues on next page)

5.19. Polynomials Manipulation Module 1039

SymPy Documentation, Release 1.3

(continued from previous page)

>>> p = 1 + x + x**2 + x**3
>>> rs_hadamard_exp(p)
1/6*x**3 + 1/2*x**2 + x + 1

Operations
sympy.polys.ring_series.rs_mul(p1, p2, x, prec)
Return the product of the given two series, modulo O(x**prec).
x is the series variable or its position in the generators.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_mul
>>> R, x = ring('x', QQ)
>>> p1 = x**2 + 2*x + 1
>>> p2 = x + 1
>>> rs_mul(p1, p2, x, 3)
3*x**2 + 3*x + 1

sympy.polys.ring_series.rs_square(p1, x, prec)
Square the series modulo O(x**prec)

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_square
>>> R, x = ring('x', QQ)
>>> p = x**2 + 2*x + 1
>>> rs_square(p, x, 3)
6*x**2 + 4*x + 1

sympy.polys.ring_series.rs_pow(p1, n, x, prec)
Return p1**n modulo O(x**prec)

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_pow
>>> R, x = ring('x', QQ)
>>> p = x + 1
>>> rs_pow(p, 4, x, 3)
6*x**2 + 4*x + 1

sympy.polys.ring_series.rs_series_inversion(p, x, prec)
Multivariate series inversion 1/p modulo O(x**prec).

1040 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_series_inversion
>>> R, x, y = ring('x, y', QQ)
>>> rs_series_inversion(1 + x*y**2, x, 4)
-x**3*y**6 + x**2*y**4 - x*y**2 + 1
>>> rs_series_inversion(1 + x*y**2, y, 4)
-x*y**2 + 1
>>> rs_series_inversion(x + x**2, x, 4)
x**3 - x**2 + x - 1 + x**(-1)

sympy.polys.ring_series.rs_series_reversion(p, x, n, y)
Reversion of a series.
p is a series with O(x**n) of the form p = a ∗ x + f (x) where a is a number different from
0.
f (x) = sum(a_k ∗ x_k, kinrange(2, n))
a_k : Can depend polynomially on other variables, not indicated. x : Variable
with name x. y : Variable with name y.
Solve p = y, that is, given a ∗ x + f (x) − y = 0, find the solution x = r(y) up to O(y**n)
Algorithm:
If r_i is the solution at order i, then: a ∗ r_i + f (r_i) − y = O(y ∗ ∗(i + 1))
and if r_(i + 1) is the solution at order i + 1, then: a ∗ r_(i + 1) + f (r_(i + 1)) − y = O(y ∗ ∗(i + 2))
We have, r_(i + 1) = r_i + e, such that, a ∗ e + f (r_i) = O(y ∗ ∗(i + 2)) or e = −f (r_i)/a
So we use the recursion relation: r_(i + 1) = r_i − f (r_i)/a with the boundary condition:
r_1 = y

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_series_reversion, rs_trunc
>>> R, x, y, a, b = ring('x, y, a, b', QQ)
>>> p = x - x**2 - 2*b*x**2 + 2*a*b*x**2
>>> p1 = rs_series_reversion(p, x, 3, y); p1
-2*y**2*a*b + 2*y**2*b + y**2 + y
>>> rs_trunc(p.compose(x, p1), y, 3)
y

sympy.polys.ring_series.rs_nth_root(p, n, x, prec)
Multivariate series expansion of the nth root of p.
Parameters n : p ∗ ∗(1/n) is returned.
x : PolyElement
prec : Order of the expanded series.

5.19. Polynomials Manipulation Module 1041

SymPy Documentation, Release 1.3

Notes

The result of this function is dependent on the ring over which the polynomial has been
defined. If the answer involves a root of a constant, make sure that the polynomial is
over a real field. It can not yet handle roots of symbols.

Examples

>>> from sympy.polys.domains import QQ, RR

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_nth_root
>>> R, x, y = ring('x, y', QQ)
>>> rs_nth_root(1 + x + x*y, -3, x, 3)
2/9*x**2*y**2 + 4/9*x**2*y + 2/9*x**2 - 1/3*x*y - 1/3*x + 1
>>> R, x, y = ring('x, y', RR)
>>> rs_nth_root(3 + x + x*y, 3, x, 2)
0.160249952256379*x*y + 0.160249952256379*x + 1.44224957030741

sympy.polys.ring_series.rs_trunc(p1, x, prec)
Truncate the series in the x variable with precision prec, that is, modulo O(x**prec)

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_trunc
>>> R, x = ring('x', QQ)
>>> p = x**10 + x**5 + x + 1
>>> rs_trunc(p, x, 12)
x**10 + x**5 + x + 1
>>> rs_trunc(p, x, 10)
x**5 + x + 1

sympy.polys.ring_series.rs_subs(p, rules, x, prec)

Substitution with truncation according to the mapping in rules.
Return a series with precision prec in the generator x
Note that substitutions are not done one after the other

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_subs
>>> R, x, y = ring('x, y', QQ)
>>> p = x**2 + y**2
>>> rs_subs(p, {x: x+ y, y: x+ 2*y}, x, 3)
2*x**2 + 6*x*y + 5*y**2
>>> (x + y)**2 + (x + 2*y)**2
2*x**2 + 6*x*y + 5*y**2

which differs from

>>> rs_subs(rs_subs(p, {x: x+ y}, x, 3), {y: x+ 2*y}, x, 3)

5*x**2 + 12*x*y + 8*y**2

1042 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters p : PolyElement Input series.

rules : dict with substitution mappings.
x : PolyElement in which the series truncation is to be done.
prec : Integer order of the series after truncation.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_subs
>>> R, x, y = ring('x, y', QQ)
>>> rs_subs(x**2+y**2, {y: (x+y)**2}, x, 3)
6*x**2*y**2 + x**2 + 4*x*y**3 + y**4

sympy.polys.ring_series.rs_diff(p, x)
Return partial derivative of p with respect to x.
Parameters x : PolyElement with respect to which p is differentiated.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_diff
>>> R, x, y = ring('x, y', QQ)
>>> p = x + x**2*y**3
>>> rs_diff(p, x)
2*x*y**3 + 1

sympy.polys.ring_series.rs_integrate(p, x)
Integrate p with respect to x.
Parameters x : PolyElement with respect to which p is integrated.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_integrate
>>> R, x, y = ring('x, y', QQ)
>>> p = x + x**2*y**3
>>> rs_integrate(p, x)
1/3*x**3*y**3 + 1/2*x**2

sympy.polys.ring_series.rs_newton(p, x, prec)
Compute the truncated Newton sum of the polynomial p

5.19. Polynomials Manipulation Module 1043

SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_newton
>>> R, x = ring('x', QQ)
>>> p = x**2 - 2
>>> rs_newton(p, x, 5)
8*x**4 + 4*x**2 + 2

sympy.polys.ring_series.rs_compose_add(p1, p2)
compute the composed sum prod(p2(x - beta) for beta root of p1)

References

A. Bostan, P. Flajolet, B. Salvy and E. Schost “Fast Computation with Two Algebraic Num-
bers”, (2002) Research Report 4579, Institut National de Recherche en Informatique et
en Automatique

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_compose_add
>>> R, x = ring('x', QQ)
>>> f = x**2 - 2
>>> g = x**2 - 3
>>> rs_compose_add(f, g)
x**4 - 10*x**2 + 1

Utility functions
sympy.polys.ring_series.rs_is_puiseux(p, x)
Test if p is Puiseux series in x.
Raise an exception if it has a negative power in x.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_is_puiseux
>>> R, x = ring('x', QQ)
>>> p = x**QQ(2,5) + x**QQ(2,3) + x
>>> rs_is_puiseux(p, x)
True

sympy.polys.ring_series.rs_puiseux(f, p, x, prec)
Return the puiseux series for f (p, x, prec).
To be used when function f is implemented only for regular series.

1044 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_puiseux, rs_exp
>>> R, x = ring('x', QQ)
>>> p = x**QQ(2,5) + x**QQ(2,3) + x
>>> rs_puiseux(rs_exp,p, x, 1)
1/2*x**(4/5) + x**(2/3) + x**(2/5) + 1

sympy.polys.ring_series.rs_puiseux2(f, p, q, x, prec)
Return the puiseux series for f (p, q, x, prec).
To be used when function f is implemented only for regular series.
sympy.polys.ring_series.rs_series_from_list(p, c, x, prec, concur=1)
Return a series sumc[n] ∗ p ∗ ∗n modulo O(x ∗ ∗prec).
It reduces the number of multiplications by summing concurrently.
ax = [1, p, p ∗ ∗2, .., p ∗ ∗(J − 1)] s = sum(c[i] ∗ ax[i] for i in range(r, (r + 1) ∗ J)) ∗ p ∗ ∗((K − 1) ∗ J)
with K >= (n + 1)/J
See also:
sympy.polys.ring.compose

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_series_from_list, rs_trunc
>>> R, x = ring('x', QQ)
>>> p = x**2 + x + 1
>>> c = [1, 2, 3]
>>> rs_series_from_list(p, c, x, 4)
6*x**3 + 11*x**2 + 8*x + 6
>>> rs_trunc(1 + 2*p + 3*p**2, x, 4)
6*x**3 + 11*x**2 + 8*x + 6
>>> pc = R.from_list(list(reversed(c)))
>>> rs_trunc(pc.compose(x, p), x, 4)
6*x**3 + 11*x**2 + 8*x + 6

sympy.polys.ring_series.rs_fun(p, f, *args)
Function of a multivariate series computed by substitution.
The case with f method name is used to compute rs_tan and rs_nth_root of a multivariate
series:
rs_f un(p, tan, iv, prec)
tan series is first computed for a dummy variable _x, i.e, rs_tan(_x, iv, prec). Then
we substitute _x with p to get the desired series

Parameters p : PolyElement The multivariate series to be expanded.

f : ring_series function to be applied on p.
args[-2] : PolyElement with respect to which, the series is to be expanded.

5.19. Polynomials Manipulation Module 1045

SymPy Documentation, Release 1.3

args[-1] : Required order of the expanded series.

Examples

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import rs_fun, _tan1
>>> R, x, y = ring('x, y', QQ)
>>> p = x + x*y + x**2*y + x**3*y**2
>>> rs_fun(p, _tan1, x, 4)
1/3*x**3*y**3 + 2*x**3*y**2 + x**3*y + 1/3*x**3 + x**2*y + x*y + x

sympy.polys.ring_series.mul_xin(p, i, n)
Return p ∗ xi ∗ ∗n.
x_i is the ith variable in p.
sympy.polys.ring_series.pow_xin(p, i, n)

>>> from sympy.polys.domains import QQ

>>> from sympy.polys.rings import ring
>>> from sympy.polys.ring_series import pow_xin
>>> R, x, y = ring('x, y', QQ)
>>> p = x**QQ(2,5) + x + x**QQ(2,3)
>>> index = p.ring.gens.index(x)
>>> pow_xin(p, index, 15)
x**15 + x**10 + x**6

Literature

The following is a non-comprehensive list of publications that were used as a theoretical

foundation for implementing polynomials manipulation module.

5.20 Printing System

See the Printing (page 19) section in Tutorial for introduction into printing.
This guide documents the printing system in SymPy and how it works internally.

5.20.1 Printer Class

Printing subsystem driver

SymPy’s printing system works the following way: Any expression can be passed to a desig-
nated Printer who then is responsible to return an adequate representation of that expression.
The basic concept is the following:
1. Let the object print itself if it knows how.
2. Take the best fitting method defined in the printer.

1046 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

3. As fall-back use the emptyPrinter method for the printer.

Which Method is Responsible for Printing?

The whole printing process is started by calling .doprint(expr) on the printer which you
want to use. This method looks for an appropriate method which can print the given expres-
sion in the given style that the printer defines. While looking for the method, it follows these
steps:
1. Let the object print itself if it knows how.
The printer looks for a specific method in every object. The name of that method
depends on the specific printer and is defined under Printer.printmethod. For
example, StrPrinter calls _sympystr and LatexPrinter calls _latex. Look at the
documentation of the printer that you want to use. The name of the method is
specified there.
This was the original way of doing printing in sympy. Every class had its own
latex, mathml, str and repr methods, but it turned out that it is hard to produce
a high quality printer, if all the methods are spread out that far. Therefore all
printing code was combined into the different printers, which works great for
built-in sympy objects, but not that good for user defined classes where it is
inconvenient to patch the printers.
2. Take the best fitting method defined in the printer.
The printer loops through expr classes (class + its bases), and tries to dispatch
the work to _print_<EXPR_CLASS>
e.g., suppose we have the following class hierarchy:
Basic
|
Atom
|
Number
|
Rational

then, for expr=Rational(...), the Printer will try to call printer methods in the
order as shown in the figure below:
p._print(expr)
|
|-- p._print_Rational(expr)
|
|-- p._print_Number(expr)
|
|-- p._print_Atom(expr)
|
`-- p._print_Basic(expr)

if ._print_Rational method exists in the printer, then it is called, and the result
is returned back. Otherwise, the printer tries to call ._print_Number and so on.
3. As a fall-back use the emptyPrinter method for the printer.
As fall-back self.emptyPrinter will be called with the expression. If not de-
fined in the Printer subclass this will be the same as str(expr).

5.20. Printing System 1047

SymPy Documentation, Release 1.3

Example of Custom Printer

In the example below, we have a printer which prints the derivative of a function in a shorter
form.

from sympy import Symbol

from sympy.printing.latex import LatexPrinter, print_latex
from sympy.core.function import UndefinedFunction, Function

class MyLatexPrinter(LatexPrinter):
”””Print derivative of a function of symbols in a shorter form.
”””
def _print_Derivative(self, expr):
function, *vars = expr.args
if not isinstance(type(function), UndefinedFunction) or \
not all(isinstance(i, Symbol) for i in vars):
return super()._print_Derivative(expr)

# If you want the printer to work correctly for nested

# expressions then use self._print() instead of str() or latex().
# See the example of nested modulo below in the custom printing
# method section.
return ”{}_{{{}}}”.format(
self._print(Symbol(function.func.__name__)),
''.join(self._print(i) for i in vars))

def print_my_latex(expr):
””” Most of the printers define their own wrappers for print().
These wrappers usually take printer settings. Our printer does not have
any settings.
”””
print(MyLatexPrinter().doprint(expr))

y = Symbol(”y”)
x = Symbol(”x”)
f = Function(”f”)
expr = f(x, y).diff(x, y)

# Print the expression using the normal latex printer and our custom
# printer.
print_latex(expr)
print_my_latex(expr)

The output of the code above is:

\frac{\partial^{2}}{\partial x\partial y} f{\left (x,y \right )}

f_{xy}

Example of Custom Printing Method

In the example below, the latex printing of the modulo operator is modified. This is done by
overriding the method _latex of Mod.

1048 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

from sympy import Symbol, Mod, Integer

from sympy.printing.latex import print_latex

class ModOp(Mod):
def _latex(self, printer=None):
# Always use printer.doprint() otherwise nested expressions won't
# work. See the example of ModOpWrong.
a, b = [printer.doprint(i) for i in self.args]
return r”\operatorname{Mod}{\left( %s,%s \right)}” % (a,b)

class ModOpWrong(Mod):
def _latex(self, printer=None):
a, b = [str(i) for i in self.args]
return r”\operatorname{Mod}{\left( %s,%s \right)}” % (a,b)

x = Symbol('x')
m = Symbol('m')

print_latex(ModOp(x, m))
print_latex(Mod(x, m))

# Nested modulo.
print_latex(ModOp(ModOp(x, m), Integer(7)))
print_latex(ModOpWrong(ModOpWrong(x, m), Integer(7)))

The output of the code above is:

\operatorname{Mod}{\left( x,m \right)}

x\bmod{m}
\operatorname{Mod}{\left( \operatorname{Mod}{\left( x,m \right)},7 \right)}
\operatorname{Mod}{\left( ModOpWrong(x, m),7 \right)}

The main class responsible for printing is Printer (see also its source code):
class sympy.printing.printer.Printer(settings=None)
Generic printer
Its job is to provide infrastructure for implementing new printers easily.
If you want to define your custom Printer or your custom printing method for your custom
class then see the example above: printer_example (page 1048) .

Attributes

printmethod

printmethod = None
_print(expr, **kwargs)
Internal dispatcher
Tries the following concepts to print an expression:
1. Let the object print itself if it knows how.

5.20. Printing System 1049

SymPy Documentation, Release 1.3

2. Take the best fitting method defined in the printer.

3. As fall-back use the emptyPrinter method for the printer.
doprint(expr)
Returns printer’s representation for expr (as a string)
classmethod set_global_settings(**settings)
Set system-wide printing settings.

5.20.2 PrettyPrinter Class

The pretty printing subsystem is implemented in sympy.printing.pretty.pretty by the

PrettyPrinter class deriving from Printer. It relies on the modules sympy.printing.
pretty.stringPict, and sympy.printing.pretty.pretty_symbology for rendering nice-
looking formulas.
The module stringPict provides a base class stringPict and a derived class prettyForm
that ease the creation and manipulation of formulas that span across multiple lines.
The module pretty_symbology provides primitives to construct 2D shapes (hline, vline, etc)
together with a technique to use unicode automatically when possible.
class sympy.printing.pretty.pretty.PrettyPrinter(settings=None)
Printer, which converts an expression into 2D ASCII-art figure.
printmethod = '_pretty'
sympy.printing.pretty.pretty.pretty(expr, **settings)
Returns a string containing the prettified form of expr.
For information on keyword arguments see pretty_print function.
sympy.printing.pretty.pretty.pretty_print(expr, wrap_line=True,
num_columns=None,
use_unicode=None,
full_prec=’auto’, order=None,
use_unicode_sqrt_char=True)
Prints expr in pretty form.
pprint is just a shortcut for this function.
Parameters expr : expression
The expression to print.
wrap_line : bool, optional (default=True)
Line wrapping enabled/disabled.
num_columns : int or None, optional (default=None)
Number of columns before line breaking (default to None which reads
the terminal width), useful when using SymPy without terminal.
use_unicode : bool or None, optional (default=None)
Use unicode characters, such as the Greek letter pi instead of the
string pi.
full_prec : bool or string, optional (default=”auto”)
Use full precision.

1050 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

order : bool or string, optional (default=None)

Set to ‘none’ for long expressions if slow; default is None.
use_unicode_sqrt_char : bool, optional (default=True)
Use compact single-character square root symbol (when unambigu-
ous).

5.20.3 C code printers

This class implements C code printing, i.e. it converts Python expressions to strings of C code
(see also C89CodePrinter).
Usage:

>>> from sympy.printing import print_ccode

>>> from sympy.functions import sin, cos, Abs, gamma
>>> from sympy.abc import x
>>> print_ccode(sin(x)**2 + cos(x)**2, standard='C89')
pow(sin(x), 2) + pow(cos(x), 2)
>>> print_ccode(2*x + cos(x), assign_to=”result”, standard='C89')
result = 2*x + cos(x);
>>> print_ccode(Abs(x**2), standard='C89')
fabs(pow(x, 2))
>>> print_ccode(gamma(x**2), standard='C99')
tgamma(pow(x, 2))

sympy.printing.ccode.known_functions_C89 = {'Abs': [(<function <lambda>>, 'fabs'), (<functi

sympy.printing.ccode.known_functions_C99 = {'Abs': [(<function <lambda>>, 'fabs'), (<functi
class sympy.printing.ccode.C89CodePrinter(settings={})
A printer to convert python expressions to strings of c code

Attributes

math_macros

printmethod = '_ccode'
indent_code(code)
Accepts a string of code or a list of code lines
class sympy.printing.ccode.C99CodePrinter(settings={})

Attributes

math_macros

printmethod = '_ccode'
sympy.printing.ccode.ccode(expr, assign_to=None, standard=’c99’, **settings)
Converts an expr to a string of c code

5.20. Printing System 1051

SymPy Documentation, Release 1.3

Parameters expr : Expr

A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This is helpful in case of line-wrapping,
or for expressions that generate multi-line statements.
standard : str, optional
String specifying the standard. If your compiler supports a more mod-
ern standard you may set this to ‘c99’ to allow the printer to use more
math functions. [default=’c89’].
precision : integer, optional
The precision for numbers such as pi [default=17].
user_functions : dict, optional
A dictionary where the keys are string representations of either Func-
tionClass or UndefinedFunction instances and the values are their
desired C string representations. Alternatively, the dictionary value
can be a list of tuples i.e. [(argument_test, cfunction_string)] or [(ar-
gument_test, cfunction_formater)]. See below for examples.
dereference : iterable, optional
An iterable of symbols that should be dereferenced in the printed
code expression. These would be values passed by address to the
function. For example, if dereference=[a], the resulting code would
print (*a) instead of a.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the
same information is returned in a tuple of (symbols_to_declare,
not_supported_functions, code_text). [default=True].
contract: bool, optional
If True, Indexed instances are assumed to obey tensor contraction
rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].

Examples

>>> from sympy import ccode, symbols, Rational, sin, ceiling, Abs, Function
>>> x, tau = symbols(”x, tau”)
>>> expr = (2*tau)**Rational(7, 2)
>>> ccode(expr)
'8*M_SQRT2*pow(tau, 7.0/2.0)'
>>> ccode(expr, math_macros={})
'8*sqrt(2)*pow(tau, 7.0/2.0)'
(continues on next page)

1052 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> ccode(sin(x), assign_to=”s”)
's = sin(x);'
>>> from sympy.codegen.ast import real, float80
>>> ccode(expr, type_aliases={real: float80})
'8*M_SQRT2l*powl(tau, 7.0L/2.0L)'

Simple custom printing can be defined for certain types by passing a dictionary of {“type”
: “function”} to the user_functions kwarg. Alternatively, the dictionary value can be a
list of tuples i.e. [(argument_test, cfunction_string)].

>>> custom_functions = {
... ”ceiling”: ”CEIL”,
... ”Abs”: [(lambda x: not x.is_integer, ”fabs”),
... (lambda x: x.is_integer, ”ABS”)],
... ”func”: ”f”
... }
>>> func = Function('func')
>>> ccode(func(Abs(x) + ceiling(x)), standard='C89', user_functions=custom_
,→functions)

'f(fabs(x) + CEIL(x))'

or if the C-function takes a subset of the original arguments:

>>> ccode(2**x + 3**x, standard='C99', user_functions={'Pow': [

... (lambda b, e: b == 2, lambda b, e: 'exp2(%s)' % e),
... (lambda b, e: b != 2, 'pow')]})
'exp2(x) + pow(3, x)'

Piecewise expressions are converted into conditionals. If an assign_to variable is pro-

vided an if statement is created, otherwise the ternary operator is used. Note that if
the Piecewise lacks a default term, represented by (expr, True) then an error will be
thrown. This is to prevent generating an expression that may not evaluate to anything.

>>> from sympy import Piecewise

>>> expr = Piecewise((x + 1, x > 0), (x, True))
>>> print(ccode(expr, tau, standard='C89'))
if (x > 0) {
tau = x + 1;
}
else {
tau = x;
}

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e=Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> ccode(e.rhs, assign_to=e.lhs, contract=False, standard='C89')
'Dy[i] = (y[i + 1] - y[i])/(t[i + 1] - t[i]);'

5.20. Printing System 1053

SymPy Documentation, Release 1.3

Matrices are also supported, but a MatrixSymbol of the same dimensions must be pro-
vided to assign_to. Note that any expression that can be generated normally can also
exist inside a Matrix:

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([x**2, Piecewise((x + 1, x > 0), (x, True)), sin(x)])
>>> A = MatrixSymbol('A', 3, 1)
>>> print(ccode(mat, A, standard='C89'))
A[0] = pow(x, 2);
if (x > 0) {
A[1] = x + 1;
}
else {
A[1] = x;
}
A[2] = sin(x);

sympy.printing.ccode.print_ccode(expr, **settings)
Prints C representation of the given expression.

5.20.4 C++ code printers

This module contains printers for C++ code, i.e. functions to convert SymPy expressions to
strings of C++ code.
Usage:

>>> from sympy.printing.cxxcode import cxxcode

>>> from sympy.functions import Min, gamma
>>> from sympy.abc import x
>>> print(cxxcode(Min(gamma(x) - 1, x), standard='C++11'))
std::min(x, std::tgamma(x) - 1)

class sympy.printing.cxxcode.CXX98CodePrinter(settings=None)

Attributes

math_macros

printmethod = '_cxxcode'
class sympy.printing.cxxcode.CXX11CodePrinter(settings=None)

Attributes

math_macros

printmethod = '_cxxcode'
sympy.printing.cxxcode.cxxcode(expr, assign_to=None, standard=’c++11’, **set-
tings)
C++ equivalent of sympy.ccode().

1054 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.20.5 RCodePrinter

This class implements R code printing (i.e. it converts Python expressions to strings of R
code).
Usage:

>>> from sympy.printing import print_rcode

>>> from sympy.functions import sin, cos, Abs
>>> from sympy.abc import x
>>> print_rcode(sin(x)**2 + cos(x)**2)
sin(x)^2 + cos(x)^2
>>> print_rcode(2*x + cos(x), assign_to=”result”)
result = 2*x + cos(x);
>>> print_rcode(Abs(x**2))
abs(x^2)

sympy.printing.rcode.known_functions = {'Abs': 'abs', 'Max': 'max', 'Min': 'min', 'acos': '

class sympy.printing.rcode.RCodePrinter(settings={})
A printer to convert python expressions to strings of R code
printmethod = '_rcode'
indent_code(code)
Accepts a string of code or a list of code lines
sympy.printing.rcode.rcode(expr, assign_to=None, **settings)
Converts an expr to a string of r code
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This is helpful in case of line-wrapping,
or for expressions that generate multi-line statements.
precision : integer, optional
The precision for numbers such as pi [default=15].
user_functions : dict, optional
A dictionary where the keys are string representations of either Func-
tionClass or UndefinedFunction instances and the values are their
desired R string representations. Alternatively, the dictionary value
can be a list of tuples i.e. [(argument_test, rfunction_string)] or [(ar-
gument_test, rfunction_formater)]. See below for examples.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the
same information is returned in a tuple of (symbols_to_declare,
not_supported_functions, code_text). [default=True].
contract: bool, optional

5.20. Printing System 1055

SymPy Documentation, Release 1.3

If True, Indexed instances are assumed to obey tensor contraction

rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].

Examples

>>> from sympy import rcode, symbols, Rational, sin, ceiling, Abs, Function
>>> x, tau = symbols(”x, tau”)
>>> rcode((2*tau)**Rational(7, 2))
'8*sqrt(2)*tau^(7.0/2.0)'
>>> rcode(sin(x), assign_to=”s”)
's = sin(x);'

Simple custom printing can be defined for certain types by passing a dictionary of {“type”
: “function”} to the user_functions kwarg. Alternatively, the dictionary value can be a
list of tuples i.e. [(argument_test, cfunction_string)].
>>> custom_functions = {
... ”ceiling”: ”CEIL”,
... ”Abs”: [(lambda x: not x.is_integer, ”fabs”),
... (lambda x: x.is_integer, ”ABS”)],
... ”func”: ”f”
... }
>>> func = Function('func')
>>> rcode(func(Abs(x) + ceiling(x)), user_functions=custom_functions)
'f(fabs(x) + CEIL(x))'

or if the R-function takes a subset of the original arguments:

>>> rcode(2**x + 3**x, user_functions={'Pow': [
... (lambda b, e: b == 2, lambda b, e: 'exp2(%s)' % e),
... (lambda b, e: b != 2, 'pow')]})
'exp2(x) + pow(3, x)'

Piecewise expressions are converted into conditionals. If an assign_to variable is pro-

vided an if statement is created, otherwise the ternary operator is used. Note that if
the Piecewise lacks a default term, represented by (expr, True) then an error will be
thrown. This is to prevent generating an expression that may not evaluate to anything.
>>> from sympy import Piecewise
>>> expr = Piecewise((x + 1, x > 0), (x, True))
>>> print(rcode(expr, assign_to=tau))
tau = ifelse(x > 0,x + 1,x);

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:
>>> from sympy import Eq, IndexedBase, Idx
>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
(continues on next page)

1056 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> i = Idx('i', len_y-1)
>>> e=Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> rcode(e.rhs, assign_to=e.lhs, contract=False)
'Dy[i] = (y[i + 1] - y[i])/(t[i + 1] - t[i]);'

Matrices are also supported, but a MatrixSymbol of the same dimensions must be pro-
vided to assign_to. Note that any expression that can be generated normally can also
exist inside a Matrix:

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([x**2, Piecewise((x + 1, x > 0), (x, True)), sin(x)])
>>> A = MatrixSymbol('A', 3, 1)
>>> print(rcode(mat, A))
A[0] = x^2;
A[1] = ifelse(x > 0,x + 1,x);
A[2] = sin(x);

sympy.printing.rcode.print_rcode(expr, **settings)
Prints R representation of the given expression.

5.20.6 Fortran Printing

The fcode function translates a sympy expression into Fortran code. The main purpose is
to take away the burden of manually translating long mathematical expressions. Therefore
the resulting expression should also require no (or very little) manual tweaking to make it
compilable. The optional arguments of fcode can be used to fine-tune the behavior of fcode
in such a way that manual changes in the result are no longer needed.
sympy.printing.fcode.fcode(expr, assign_to=None, **settings)
Converts an expr to a string of fortran code
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This is helpful in case of line-wrapping,
or for expressions that generate multi-line statements.
precision : integer, optional
DEPRECATED. Use type_mappings instead. The precision for num-
bers such as pi [default=17].
user_functions : dict, optional
A dictionary where keys are FunctionClass instances and values are
their string representations. Alternatively, the dictionary value can
be a list of tuples i.e. [(argument_test, cfunction_string)]. See below
for examples.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the

5.20. Printing System 1057

SymPy Documentation, Release 1.3

same information is returned in a tuple of (symbols_to_declare,

not_supported_functions, code_text). [default=True].
contract: bool, optional
If True, Indexed instances are assumed to obey tensor contraction
rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].
source_format : optional
The source format can be either ‘fixed’ or ‘free’. [default=’fixed’]
standard : integer, optional
The Fortran standard to be followed. This is specified as an integer.
Acceptable standards are 66, 77, 90, 95, 2003, and 2008. Default
is 77. Note that currently the only distinction internally is between
standards before 95, and those 95 and after. This may change later
as more features are added.
name_mangling : bool, optional
If True, then the variables that would become identical in case-
insensitive Fortran are mangled by appending different number of _
at the end. If False, SymPy won’t interfere with naming of variables.
[default=True]

Examples

>>> from sympy import fcode, symbols, Rational, sin, ceiling, floor
>>> x, tau = symbols(”x, tau”)
>>> fcode((2*tau)**Rational(7, 2))
' 8*sqrt(2.0d0)*tau**(7.0d0/2.0d0)'
>>> fcode(sin(x), assign_to=”s”)
' s = sin(x)'

Custom printing can be defined for certain types by passing a dictionary of “type” :
“function” to the user_functions kwarg. Alternatively, the dictionary value can be a list
of tuples i.e. [(argument_test, cfunction_string)].

>>> custom_functions = {
... ”ceiling”: ”CEIL”,
... ”floor”: [(lambda x: not x.is_integer, ”FLOOR1”),
... (lambda x: x.is_integer, ”FLOOR2”)]
... }
>>> fcode(floor(x) + ceiling(x), user_functions=custom_functions)
' CEIL(x) + FLOOR1(x)'

Piecewise expressions are converted into conditionals. If an assign_to variable is pro-

vided an if statement is created, otherwise the ternary operator is used. Note that if
the Piecewise lacks a default term, represented by (expr, True) then an error will be
thrown. This is to prevent generating an expression that may not evaluate to anything.

1058 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Piecewise

>>> expr = Piecewise((x + 1, x > 0), (x, True))
>>> print(fcode(expr, tau))
if (x > 0) then
tau = x + 1
else
tau = x
end if

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e=Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> fcode(e.rhs, assign_to=e.lhs, contract=False)
' Dy(i) = (y(i + 1) - y(i))/(t(i + 1) - t(i))'

Matrices are also supported, but a MatrixSymbol of the same dimensions must be pro-
vided to assign_to. Note that any expression that can be generated normally can also
exist inside a Matrix:

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([x**2, Piecewise((x + 1, x > 0), (x, True)), sin(x)])
>>> A = MatrixSymbol('A', 3, 1)
>>> print(fcode(mat, A))
A(1, 1) = x**2
if (x > 0) then
A(2, 1) = x + 1
else
A(2, 1) = x
end if
A(3, 1) = sin(x)

sympy.printing.fcode.print_fcode(expr, **settings)
Prints the Fortran representation of the given expression.
See fcode for the meaning of the optional arguments.
class sympy.printing.fcode.FCodePrinter(settings={})
A printer to convert sympy expressions to strings of Fortran code
printmethod = '_fcode'
indent_code(code)
Accepts a string of code or a list of code lines
Two basic examples:

>>> from sympy import *

>>> x = symbols(”x”)
>>> fcode(sqrt(1-x**2))
' sqrt(-x**2 + 1)'
(continues on next page)

5.20. Printing System 1059

SymPy Documentation, Release 1.3

(continued from previous page)

>>> fcode((3 + 4*I)/(1 - conjugate(x)))
' (cmplx(3,4))/(-conjg(x) + 1)'

An example where line wrapping is required:

>>> expr = sqrt(1-x**2).series(x,n=20).removeO()

>>> print(fcode(expr))
-715.0d0/65536.0d0*x**18 - 429.0d0/32768.0d0*x**16 - 33.0d0/
@ 2048.0d0*x**14 - 21.0d0/1024.0d0*x**12 - 7.0d0/256.0d0*x**10 -
@ 5.0d0/128.0d0*x**8 - 1.0d0/16.0d0*x**6 - 1.0d0/8.0d0*x**4 - 1.0d0
@ /2.0d0*x**2 + 1

In case of line wrapping, it is handy to include the assignment so that lines are wrapped
properly when the assignment part is added.

>>> print(fcode(expr, assign_to=”var”))

var = -715.0d0/65536.0d0*x**18 - 429.0d0/32768.0d0*x**16 - 33.0d0/
@ 2048.0d0*x**14 - 21.0d0/1024.0d0*x**12 - 7.0d0/256.0d0*x**10 -
@ 5.0d0/128.0d0*x**8 - 1.0d0/16.0d0*x**6 - 1.0d0/8.0d0*x**4 - 1.0d0
@ /2.0d0*x**2 + 1

For piecewise functions, the assign_to option is mandatory:

>>> print(fcode(Piecewise((x,x<1),(x**2,True)), assign_to=”var”))

if (x < 1) then
var = x
else
var = x**2
end if

Note that by default only top-level piecewise functions are supported due to the lack of a
conditional operator in Fortran 77. Inline conditionals can be supported using the merge
function introduced in Fortran 95 by setting of the kwarg standard=95:

>>> print(fcode(Piecewise((x,x<1),(x**2,True)), standard=95))

merge(x, x**2, x < 1)

Loops are generated if there are Indexed objects in the expression. This also requires use of
the assign_to option.

>>> A, B = map(IndexedBase, ['A', 'B'])

>>> m = Symbol('m', integer=True)
>>> i = Idx('i', m)
>>> print(fcode(2*B[i], assign_to=A[i]))
do i = 1, m
A(i) = 2*B(i)
end do

Repeated indices in an expression with Indexed objects are interpreted as summation. For
instance, code for the trace of a matrix can be generated with

>>> print(fcode(A[i, i], assign_to=x))

x = 0
do i = 1, m
x = x + A(i, i)
end do

1060 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

By default, number symbols such as pi and E are detected and defined as Fortran parame-
ters. The precision of the constants can be tuned with the precision argument. Parameter
definitions are easily avoided using the N function.

>>> print(fcode(x - pi**2 - E))

parameter (E = 2.7182818284590452d0)
parameter (pi = 3.1415926535897932d0)
x - pi**2 - E
>>> print(fcode(x - pi**2 - E, precision=25))
parameter (E = 2.718281828459045235360287d0)
parameter (pi = 3.141592653589793238462643d0)
x - pi**2 - E
>>> print(fcode(N(x - pi**2, 25)))
x - 9.869604401089358618834491d0

When some functions are not part of the Fortran standard, it might be desirable to introduce
the names of user-defined functions in the Fortran expression.

>>> print(fcode(1 - gamma(x)**2, user_functions={'gamma': 'mygamma'}))

-mygamma(x)**2 + 1

However, when the user_functions argument is not provided, fcode will generate code which
assumes that a function of the same name will be provided by the user. A comment will be
added to inform the user of the issue:

>>> print(fcode(1 - gamma(x)**2))

C Not supported in Fortran:
C gamma
-gamma(x)**2 + 1

The printer can be configured to omit these comments:

>>> print(fcode(1 - gamma(x)**2, allow_unknown_functions=True))

-gamma(x)**2 + 1

By default the output is human readable code, ready for copy and paste. With the option
human=False, the return value is suitable for post-processing with source code generators
that write routines with multiple instructions. The return value is a three-tuple containing:
(i) a set of number symbols that must be defined as ‘Fortran parameters’, (ii) a list functions
that cannot be translated in pure Fortran and (iii) a string of Fortran code. A few examples:

>>> fcode(1 - gamma(x)**2, human=False)

(set(), {gamma(x)}, ' -gamma(x)**2 + 1')
>>> fcode(1 - sin(x)**2, human=False)
(set(), set(), ' -sin(x)**2 + 1')
>>> fcode(x - pi**2, human=False)
({(pi, '3.1415926535897932d0')}, set(), ' x - pi**2')

5.20.7 Mathematica code printing

sympy.printing.mathematica.known_functions = {'acos': [(<function <lambda>>, 'ArcCos')], 'a

class sympy.printing.mathematica.MCodePrinter(settings={})
A printer to convert python expressions to strings of the Wolfram’s Mathematica code
printmethod = '_mcode'

5.20. Printing System 1061

SymPy Documentation, Release 1.3

doprint(expr)
Returns printer’s representation for expr (as a string)
sympy.printing.mathematica.mathematica_code(expr, **settings)
Converts an expr to a string of the Wolfram Mathematica code

Examples

>>> from sympy import mathematica_code as mcode, symbols, sin

>>> x = symbols('x')
>>> mcode(sin(x).series(x).removeO())
'(1/120)*x^5 - 1/6*x^3 + x'

5.20.8 Javascript Code printing

sympy.printing.jscode.known_functions = {'Abs': 'Math.abs', 'Max': 'Math.max', 'Min': 'Math

class sympy.printing.jscode.JavascriptCodePrinter(settings={})
“A Printer to convert python expressions to strings of javascript code
printmethod = '_javascript'
indent_code(code)
Accepts a string of code or a list of code lines
sympy.printing.jscode.jscode(expr, assign_to=None, **settings)
Converts an expr to a string of javascript code
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This is helpful in case of line-wrapping,
or for expressions that generate multi-line statements.
precision : integer, optional
The precision for numbers such as pi [default=15].
user_functions : dict, optional
A dictionary where keys are FunctionClass instances and values are
their string representations. Alternatively, the dictionary value can
be a list of tuples i.e. [(argument_test, js_function_string)]. See below
for examples.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the
same information is returned in a tuple of (symbols_to_declare,
not_supported_functions, code_text). [default=True].
contract: bool, optional

1062 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If True, Indexed instances are assumed to obey tensor contraction

rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].

Examples

>>> from sympy import jscode, symbols, Rational, sin, ceiling, Abs
>>> x, tau = symbols(”x, tau”)
>>> jscode((2*tau)**Rational(7, 2))
'8*Math.sqrt(2)*Math.pow(tau, 7/2)'
>>> jscode(sin(x), assign_to=”s”)
's = Math.sin(x);'

Custom printing can be defined for certain types by passing a dictionary of “type” :
“function” to the user_functions kwarg. Alternatively, the dictionary value can be a list
of tuples i.e. [(argument_test, js_function_string)].

>>> custom_functions = {
... ”ceiling”: ”CEIL”,
... ”Abs”: [(lambda x: not x.is_integer, ”fabs”),
... (lambda x: x.is_integer, ”ABS”)]
... }
>>> jscode(Abs(x) + ceiling(x), user_functions=custom_functions)
'fabs(x) + CEIL(x)'

Piecewise expressions are converted into conditionals. If an assign_to variable is pro-

vided an if statement is created, otherwise the ternary operator is used. Note that if
the Piecewise lacks a default term, represented by (expr, True) then an error will be
thrown. This is to prevent generating an expression that may not evaluate to anything.

>>> from sympy import Piecewise

>>> expr = Piecewise((x + 1, x > 0), (x, True))
>>> print(jscode(expr, tau))
if (x > 0) {
tau = x + 1;
}
else {
tau = x;
}

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e=Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> jscode(e.rhs, assign_to=e.lhs, contract=False)
'Dy[i] = (y[i + 1] - y[i])/(t[i + 1] - t[i]);'

5.20. Printing System 1063

SymPy Documentation, Release 1.3

Matrices are also supported, but a MatrixSymbol of the same dimensions must be pro-
vided to assign_to. Note that any expression that can be generated normally can also
exist inside a Matrix:

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([x**2, Piecewise((x + 1, x > 0), (x, True)), sin(x)])
>>> A = MatrixSymbol('A', 3, 1)
>>> print(jscode(mat, A))
A[0] = Math.pow(x, 2);
if (x > 0) {
A[1] = x + 1;
}
else {
A[1] = x;
}
A[2] = Math.sin(x);

5.20.9 Julia code printing

sympy.printing.julia.known_fcns_src1 = ['sin', 'cos', 'tan', 'cot', 'sec', 'csc', 'asin', '

list() -> new empty list list(iterable) -> new list initialized from iterable’s items
sympy.printing.julia.known_fcns_src2 = {'Abs': 'abs', 'ceiling': 'ceil', 'conjugate': 'conj
class sympy.printing.julia.JuliaCodePrinter(settings={})
A printer to convert expressions to strings of Julia code.
printmethod = '_julia'
indent_code(code)
Accepts a string of code or a list of code lines
sympy.printing.julia.julia_code(expr, assign_to=None, **settings)
Converts expr to a string of Julia code.
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This can be helpful for expressions
that generate multi-line statements.
precision : integer, optional
The precision for numbers such as pi [default=16].
user_functions : dict, optional
A dictionary where keys are FunctionClass instances and values are
their string representations. Alternatively, the dictionary value can
be a list of tuples i.e. [(argument_test, cfunction_string)]. See below
for examples.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the

1064 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

same information is returned in a tuple of (symbols_to_declare,

not_supported_functions, code_text). [default=True].
contract: bool, optional
If True, Indexed instances are assumed to obey tensor contraction
rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].
inline: bool, optional
If True, we try to create single-statement code instead of multiple
statements. [default=True].

Examples

>>> from sympy import julia_code, symbols, sin, pi

>>> x = symbols('x')
>>> julia_code(sin(x).series(x).removeO())
'x.^5/120 - x.^3/6 + x'

>>> from sympy import Rational, ceiling, Abs

>>> x, y, tau = symbols(”x, y, tau”)
>>> julia_code((2*tau)**Rational(7, 2))
'8*sqrt(2)*tau.^(7/2)'

Note that element-wise (Hadamard) operations are used by default between symbols.
This is because its possible in Julia to write “vectorized” code. It is harmless if the
values are scalars.
>>> julia_code(sin(pi*x*y), assign_to=”s”)
's = sin(pi*x.*y)'

If you need a matrix product “*” or matrix power “^”, you can specify the symbol as a
MatrixSymbol.
>>> from sympy import Symbol, MatrixSymbol
>>> n = Symbol('n', integer=True, positive=True)
>>> A = MatrixSymbol('A', n, n)
>>> julia_code(3*pi*A**3)
'(3*pi)*A^3'

This class uses several rules to decide which symbol to use a product. Pure numbers
use “*”, Symbols use “.*” and MatrixSymbols use “*”. A HadamardProduct can be used
to specify componentwise multiplication “.*” of two MatrixSymbols. There is currently
there is no easy way to specify scalar symbols, so sometimes the code might have some
minor cosmetic issues. For example, suppose x and y are scalars and A is a Matrix, then
while a human programmer might write “(x^2*y)*A^3”, we generate:
>>> julia_code(x**2*y*A**3)
'(x.^2.*y)*A^3'

Matrices are supported using Julia inline notation. When using assign_to with matrices,
the name can be specified either as a string or as a MatrixSymbol. The dimensions must
align in the latter case.

5.20. Printing System 1065

SymPy Documentation, Release 1.3

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([[x**2, sin(x), ceiling(x)]])
>>> julia_code(mat, assign_to='A')
'A = [x.^2 sin(x) ceil(x)]'

Piecewise expressions are implemented with logical masking by default. Alternatively,

you can pass “inline=False” to use if-else conditionals. Note that if the Piecewise lacks
a default term, represented by (expr, True) then an error will be thrown. This is to
prevent generating an expression that may not evaluate to anything.

>>> from sympy import Piecewise

>>> pw = Piecewise((x + 1, x > 0), (x, True))
>>> julia_code(pw, assign_to=tau)
'tau = ((x > 0) ? (x + 1) : (x))'

Note that any expression that can be generated normally can also exist inside a Matrix:

>>> mat = Matrix([[x**2, pw, sin(x)]])

>>> julia_code(mat, assign_to='A')
'A = [x.^2 ((x > 0) ? (x + 1) : (x)) sin(x)]'

Custom printing can be defined for certain types by passing a dictionary of “type” :
“function” to the user_functions kwarg. Alternatively, the dictionary value can be a list
of tuples i.e., [(argument_test, cfunction_string)]. This can be used to call a custom Julia
function.

>>> from sympy import Function

>>> f = Function('f')
>>> g = Function('g')
>>> custom_functions = {
... ”f”: ”existing_julia_fcn”,
... ”g”: [(lambda x: x.is_Matrix, ”my_mat_fcn”),
... (lambda x: not x.is_Matrix, ”my_fcn”)]
... }
>>> mat = Matrix([[1, x]])
>>> julia_code(f(x) + g(x) + g(mat), user_functions=custom_functions)
'existing_julia_fcn(x) + my_fcn(x) + my_mat_fcn([1 x])'

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx, ccode

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e = Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> julia_code(e.rhs, assign_to=e.lhs, contract=False)
'Dy[i] = (y[i + 1] - y[i])./(t[i + 1] - t[i])'

1066 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.20.10 Octave (and Matlab) Code printing

sympy.printing.octave.known_fcns_src1 = ['sin', 'cos', 'tan', 'cot', 'sec', 'csc', 'asin',

list() -> new empty list list(iterable) -> new list initialized from iterable’s items
sympy.printing.octave.known_fcns_src2 = {'Abs': 'abs', 'Chi': 'coshint', 'Ci': 'cosint', 'D
class sympy.printing.octave.OctaveCodePrinter(settings={})
A printer to convert expressions to strings of Octave/Matlab code.
printmethod = '_octave'
indent_code(code)
Accepts a string of code or a list of code lines
sympy.printing.octave.octave_code(expr, assign_to=None, **settings)
Converts expr to a string of Octave (or Matlab) code.
The string uses a subset of the Octave language for Matlab compatibility.
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional
When given, the argument is used as the name of the variable to
which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This can be helpful for expressions
that generate multi-line statements.
precision : integer, optional
The precision for numbers such as pi [default=16].
user_functions : dict, optional
A dictionary where keys are FunctionClass instances and values are
their string representations. Alternatively, the dictionary value can
be a list of tuples i.e. [(argument_test, cfunction_string)]. See below
for examples.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the
same information is returned in a tuple of (symbols_to_declare,
not_supported_functions, code_text). [default=True].
contract: bool, optional
If True, Indexed instances are assumed to obey tensor contraction
rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].
inline: bool, optional
If True, we try to create single-statement code instead of multiple
statements. [default=True].

5.20. Printing System 1067

SymPy Documentation, Release 1.3

Examples

>>> from sympy import octave_code, symbols, sin, pi

>>> x = symbols('x')
>>> octave_code(sin(x).series(x).removeO())
'x.^5/120 - x.^3/6 + x'

>>> from sympy import Rational, ceiling, Abs

>>> x, y, tau = symbols(”x, y, tau”)
>>> octave_code((2*tau)**Rational(7, 2))
'8*sqrt(2)*tau.^(7/2)'

Note that element-wise (Hadamard) operations are used by default between symbols.
This is because its very common in Octave to write “vectorized” code. It is harmless if
the values are scalars.

>>> octave_code(sin(pi*x*y), assign_to=”s”)

's = sin(pi*x.*y);'

If you need a matrix product “*” or matrix power “^”, you can specify the symbol as a
MatrixSymbol.

>>> from sympy import Symbol, MatrixSymbol

>>> n = Symbol('n', integer=True, positive=True)
>>> A = MatrixSymbol('A', n, n)
>>> octave_code(3*pi*A**3)
'(3*pi)*A^3'

This class uses several rules to decide which symbol to use a product. Pure numbers
use “*”, Symbols use “.*” and MatrixSymbols use “*”. A HadamardProduct can be used
to specify componentwise multiplication “.*” of two MatrixSymbols. There is currently
there is no easy way to specify scalar symbols, so sometimes the code might have some
minor cosmetic issues. For example, suppose x and y are scalars and A is a Matrix, then
while a human programmer might write “(x^2*y)*A^3”, we generate:

>>> octave_code(x**2*y*A**3)
'(x.^2.*y)*A^3'

Matrices are supported using Octave inline notation. When using assign_to with matri-
ces, the name can be specified either as a string or as a MatrixSymbol. The dimensions
must align in the latter case.

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([[x**2, sin(x), ceiling(x)]])
>>> octave_code(mat, assign_to='A')
'A = [x.^2 sin(x) ceil(x)];'

Piecewise expressions are implemented with logical masking by default. Alternatively,

you can pass “inline=False” to use if-else conditionals. Note that if the Piecewise lacks
a default term, represented by (expr, True) then an error will be thrown. This is to
prevent generating an expression that may not evaluate to anything.

>>> from sympy import Piecewise

>>> pw = Piecewise((x + 1, x > 0), (x, True))
>>> octave_code(pw, assign_to=tau)
'tau = ((x > 0).*(x + 1) + (~(x > 0)).*(x));'

1068 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Note that any expression that can be generated normally can also exist inside a Matrix:

>>> mat = Matrix([[x**2, pw, sin(x)]])

>>> octave_code(mat, assign_to='A')
'A = [x.^2 ((x > 0).*(x + 1) + (~(x > 0)).*(x)) sin(x)];'

Custom printing can be defined for certain types by passing a dictionary of “type” :
“function” to the user_functions kwarg. Alternatively, the dictionary value can be a
list of tuples i.e., [(argument_test, cfunction_string)]. This can be used to call a custom
Octave function.

>>> from sympy import Function

>>> f = Function('f')
>>> g = Function('g')
>>> custom_functions = {
... ”f”: ”existing_octave_fcn”,
... ”g”: [(lambda x: x.is_Matrix, ”my_mat_fcn”),
... (lambda x: not x.is_Matrix, ”my_fcn”)]
... }
>>> mat = Matrix([[1, x]])
>>> octave_code(f(x) + g(x) + g(mat), user_functions=custom_functions)
'existing_octave_fcn(x) + my_fcn(x) + my_mat_fcn([1 x])'

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx, ccode

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e = Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> octave_code(e.rhs, assign_to=e.lhs, contract=False)
'Dy(i) = (y(i + 1) - y(i))./(t(i + 1) - t(i));'

5.20.11 Rust code printing

sympy.printing.rust.known_functions = {'': 'ln_1p', 'Abs': 'abs', 'Max': 'max', 'Min': 'min

class sympy.printing.rust.RustCodePrinter(settings={})
A printer to convert python expressions to strings of Rust code
printmethod = '_rust_code'
indent_code(code)
Accepts a string of code or a list of code lines
sympy.printing.rust.rust_code(expr, assign_to=None, **settings)
Converts an expr to a string of Rust code
Parameters expr : Expr
A sympy expression to be converted.
assign_to : optional

5.20. Printing System 1069

SymPy Documentation, Release 1.3

When given, the argument is used as the name of the variable to

which the expression is assigned. Can be a string, Symbol, Ma-
trixSymbol, or Indexed type. This is helpful in case of line-wrapping,
or for expressions that generate multi-line statements.
precision : integer, optional
The precision for numbers such as pi [default=15].
user_functions : dict, optional
A dictionary where the keys are string representations of either Func-
tionClass or UndefinedFunction instances and the values are their
desired C string representations. Alternatively, the dictionary value
can be a list of tuples i.e. [(argument_test, cfunction_string)]. See
below for examples.
dereference : iterable, optional
An iterable of symbols that should be dereferenced in the printed
code expression. These would be values passed by address to the
function. For example, if dereference=[a], the resulting code would
print (*a) instead of a.
human : bool, optional
If True, the result is a single string that may contain some
constant declarations for the number symbols. If False, the
same information is returned in a tuple of (symbols_to_declare,
not_supported_functions, code_text). [default=True].
contract: bool, optional
If True, Indexed instances are assumed to obey tensor contraction
rules and the corresponding nested loops over indices are gener-
ated. Setting contract=False will not generate loops, instead the
user is responsible to provide values for the indices in the code. [de-
fault=True].

Examples

>>> from sympy import rust_code, symbols, Rational, sin, ceiling, Abs, Function
>>> x, tau = symbols(”x, tau”)
>>> rust_code((2*tau)**Rational(7, 2))
'8*1.4142135623731*tau.powf(7_f64/2.0)'
>>> rust_code(sin(x), assign_to=”s”)
's = x.sin();'

Simple custom printing can be defined for certain types by passing a dictionary of {“type”
: “function”} to the user_functions kwarg. Alternatively, the dictionary value can be a
list of tuples i.e. [(argument_test, cfunction_string)].

>>> custom_functions = {
... ”ceiling”: ”CEIL”,
... ”Abs”: [(lambda x: not x.is_integer, ”fabs”, 4),
... (lambda x: x.is_integer, ”ABS”, 4)],
... ”func”: ”f”
... }
(continues on next page)

1070 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> func = Function('func')
>>> rust_code(func(Abs(x) + ceiling(x)), user_functions=custom_functions)
'(fabs(x) + x.CEIL()).f()'

Piecewise expressions are converted into conditionals. If an assign_to variable is pro-

vided an if statement is created, otherwise the ternary operator is used. Note that if
the Piecewise lacks a default term, represented by (expr, True) then an error will be
thrown. This is to prevent generating an expression that may not evaluate to anything.

>>> from sympy import Piecewise

>>> expr = Piecewise((x + 1, x > 0), (x, True))
>>> print(rust_code(expr, tau))
tau = if (x > 0) {
x + 1
} else {
x
};

Support for loops is provided through Indexed types. With contract=True these expres-
sions will be turned into loops, whereas contract=False will just print the assignment
expression that should be looped over:

>>> from sympy import Eq, IndexedBase, Idx

>>> len_y = 5
>>> y = IndexedBase('y', shape=(len_y,))
>>> t = IndexedBase('t', shape=(len_y,))
>>> Dy = IndexedBase('Dy', shape=(len_y-1,))
>>> i = Idx('i', len_y-1)
>>> e=Eq(Dy[i], (y[i+1]-y[i])/(t[i+1]-t[i]))
>>> rust_code(e.rhs, assign_to=e.lhs, contract=False)
'Dy[i] = (y[i + 1] - y[i])/(t[i + 1] - t[i]);'

Matrices are also supported, but a MatrixSymbol of the same dimensions must be pro-
vided to assign_to. Note that any expression that can be generated normally can also
exist inside a Matrix:

>>> from sympy import Matrix, MatrixSymbol

>>> mat = Matrix([x**2, Piecewise((x + 1, x > 0), (x, True)), sin(x)])
>>> A = MatrixSymbol('A', 3, 1)
>>> print(rust_code(mat, A))
A = [x.powi(2), if (x > 0) {
x + 1
} else {
x
}, x.sin()];

5.20.12 Theano Code printing

class sympy.printing.theanocode.TheanoPrinter(*args, **kwargs)

Code printer for Theano computations
printmethod = '_theano'
doprint(expr, **kwargs)
Returns printer’s representation for expr (as a string)

5.20. Printing System 1071

SymPy Documentation, Release 1.3

sympy.printing.theanocode.theano_function(inputs, outputs, dtypes={},

cache=None, **kwargs)
Create Theano function from SymPy expressions

5.20.13 Gtk

You can print to a gtkmathview widget using the function print_gtk located in sympy.
printing.gtk (it requires to have installed gtkmathview and libgtkmathview-bin in some
systems).
GtkMathView accepts MathML, so this rendering depends on the MathML representation of
the expression.
Usage:

from sympy import *

print_gtk(x**2 + 2*exp(x**3))

sympy.printing.gtk.print_gtk(x, start_viewer=True)
Print to Gtkmathview, a gtk widget capable of rendering MathML.
Needs libgtkmathview-bin

5.20.14 LambdaPrinter

This classes implements printing to strings that can be used by the sympy.utilities.
lambdify.lambdify() (page 1479) function.
class sympy.printing.lambdarepr.LambdaPrinter(settings=None)
This printer converts expressions into strings that can be used by lambdify.

Attributes

modules

printmethod = '_lambdacode'
sympy.printing.lambdarepr.lambdarepr(expr, **settings)
Returns a string usable for lambdifying.

5.20.15 LatexPrinter

This class implements LaTeX printing. See sympy.printing.latex.

sympy.printing.latex.accepted_latex_functions = ['arcsin', 'arccos', 'arctan', 'sin', 'cos'
list() -> new empty list list(iterable) -> new list initialized from iterable’s items
class sympy.printing.latex.LatexPrinter(settings=None)

printmethod = '_latex'

1072 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.printing.latex.latex(expr, fold_frac_powers=False,
fold_func_brackets=False, fold_short_frac=None,
inv_trig_style=’abbreviated’, itex=False,
ln_notation=False, long_frac_ratio=None,
mat_delim=’[’, mat_str=None, mode=’plain’,
mul_symbol=None, order=None, sym-
bol_names=None)
Convert the given expression to LaTeX string representation.
Parameters fold_frac_powers : boolean, optional
Emit ^{p/q} instead of ^{\frac{p}{q}} for fractional powers.
fold_func_brackets : boolean, optional
Fold function brackets where applicable.
fold_short_frac : boolean, optional
Emit p / q instead of \frac{p}{q} when the denominator is simple
enough (at most two terms and no powers). The default value is True
for inline mode, False otherwise.
inv_trig_style : string, optional
How inverse trig functions should be displayed. Can be one of ab-
breviated, full, or power. Defaults to abbreviated.
itex : boolean, optional
Specifies if itex-specific syntax is used, including emitting $$...$$.
ln_notation : boolean, optional
If set to True, \ln is used instead of default \log.
long_frac_ratio : float or None, optional
The allowed ratio of the width of the numerator to the width of the
denominator before the printer breaks off long fractions. If None (the
default value), long fractions are not broken up.
mat_delim : string, optional
The delimiter to wrap around matrices. Can be one of [, (, or the
empty string. Defaults to [.
mat_str : string, optional
Which matrix environment string to emit. smallmatrix, matrix, ar-
ray, etc. Defaults to smallmatrix for inline mode, matrix for matri-
ces of no more than 10 columns, and array otherwise.
mode: string, optional
Specifies how the generated code will be delimited. mode can be one
of plain, inline, equation or equation*. If mode is set to plain,
then the resulting code will not be delimited at all (this is the de-
fault). If mode is set to inline then inline LaTeX $...$ will be used.
If mode is set to equation or equation*, the resulting code will be
enclosed in the equation or equation* environment (remember to
import amsmath for equation*), unless the itex option is set. In the
latter case, the $$...$$ syntax is used.

5.20. Printing System 1073

SymPy Documentation, Release 1.3

mul_symbol : string or None, optional

The symbol to use for multiplication. Can be one of None, ldot, dot,
or times.
order: string, optional
Any of the supported monomial orderings (currently lex, grlex, or
grevlex), old, and none. This parameter does nothing for Mul ob-
jects. Setting order to old uses the compatibility ordering for Add
defined in Printer. For very large expressions, set the order keyword
to none if speed is a concern.
symbol_names : dictionary of strings mapped to symbols, optional
Dictionary of symbols and the custom strings they should be emitted
as.

Notes

Not using a print statement for printing, results in double backslashes for latex com-
mands since that’s the way Python escapes backslashes in strings.

>>> from sympy import latex, Rational

>>> from sympy.abc import tau
>>> latex((2*tau)**Rational(7,2))
'8 \\sqrt{2} \\tau^{\\frac{7}{2}}'
>>> print(latex((2*tau)**Rational(7,2)))
8 \sqrt{2} \tau^{\frac{7}{2}}

Examples

>>> from sympy import latex, pi, sin, asin, Integral, Matrix, Rational, log
>>> from sympy.abc import x, y, mu, r, tau

Basic usage:

>>> print(latex((2*tau)**Rational(7,2)))
8 \sqrt{2} \tau^{\frac{7}{2}}

mode and itex options:

>>> print(latex((2*mu)**Rational(7,2), mode='plain'))

8 \sqrt{2} \mu^{\frac{7}{2}}
>>> print(latex((2*tau)**Rational(7,2), mode='inline'))
$8 \sqrt{2} \tau^{7 / 2}$
>>> print(latex((2*mu)**Rational(7,2), mode='equation*'))
\begin{equation*}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation*}
>>> print(latex((2*mu)**Rational(7,2), mode='equation'))
\begin{equation}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation}
>>> print(latex((2*mu)**Rational(7,2), mode='equation', itex=True))
$$8 \sqrt{2} \mu^{\frac{7}{2}}$$
>>> print(latex((2*mu)**Rational(7,2), mode='plain'))
8 \sqrt{2} \mu^{\frac{7}{2}}
>>> print(latex((2*tau)**Rational(7,2), mode='inline'))
(continues on next page)

1074 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

$8 \sqrt{2} \tau^{7 / 2}$
>>> print(latex((2*mu)**Rational(7,2), mode='equation*'))
\begin{equation*}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation*}
>>> print(latex((2*mu)**Rational(7,2), mode='equation'))
\begin{equation}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation}
>>> print(latex((2*mu)**Rational(7,2), mode='equation', itex=True))
$$8 \sqrt{2} \mu^{\frac{7}{2}}$$

Fraction options:

>>> print(latex((2*tau)**Rational(7,2), fold_frac_powers=True))

8 \sqrt{2} \tau^{7/2}
>>> print(latex((2*tau)**sin(Rational(7,2))))
\left(2 \tau\right)^{\sin{\left (\frac{7}{2} \right )}}
>>> print(latex((2*tau)**sin(Rational(7,2)), fold_func_brackets=True))
\left(2 \tau\right)^{\sin {\frac{7}{2}}}
>>> print(latex(3*x**2/y))
\frac{3 x^{2}}{y}
>>> print(latex(3*x**2/y, fold_short_frac=True))
3 x^{2} / y
>>> print(latex(Integral(r, r)/2/pi, long_frac_ratio=2))
\frac{\int r\, dr}{2 \pi}
>>> print(latex(Integral(r, r)/2/pi, long_frac_ratio=0))
\frac{1}{2 \pi} \int r\, dr

Multiplication options:

>>> print(latex((2*tau)**sin(Rational(7,2)), mul_symbol=”times”))

\left(2 \times \tau\right)^{\sin{\left (\frac{7}{2} \right )}}

Trig options:

>>> print(latex(asin(Rational(7,2))))
\operatorname{asin}{\left (\frac{7}{2} \right )}
>>> print(latex(asin(Rational(7,2)), inv_trig_style=”full”))
\arcsin{\left (\frac{7}{2} \right )}
>>> print(latex(asin(Rational(7,2)), inv_trig_style=”power”))
\sin^{-1}{\left (\frac{7}{2} \right )}

Matrix options:

>>> print(latex(Matrix(2, 1, [x, y])))

\left[\begin{matrix}x\\y\end{matrix}\right]
>>> print(latex(Matrix(2, 1, [x, y]), mat_str = ”array”))
\left[\begin{array}{c}x\\y\end{array}\right]
>>> print(latex(Matrix(2, 1, [x, y]), mat_delim=”(”))
\left(\begin{matrix}x\\y\end{matrix}\right)

Custom printing of symbols:

>>> print(latex(x**2, symbol_names={x: 'x_i'}))

x_i^{2}

Logarithms:

5.20. Printing System 1075

SymPy Documentation, Release 1.3

>>> print(latex(log(10)))
\log{\left (10 \right )}
>>> print(latex(log(10), ln_notation=True))
\ln{\left (10 \right )}

latex() also supports the builtin container types list, tuple, and dictionary.

>>> print(latex([2/x, y], mode='inline'))

$\left [ 2 / x, \quad y\right ]$

sympy.printing.latex.print_latex(expr, **settings)
Prints LaTeX representation of the given expression. Takes the same settings as latex().

5.20.16 MathMLPrinter

This class is responsible for MathML printing. See sympy.printing.mathml.

More info on mathml : http://www.w3.org/TR/MathML2
class sympy.printing.mathml.MathMLPrinterBase(settings=None)
Contains common code required for MathMLContentPrinter and MathMLPresentation-
Printer.

Attributes

printmethod

class sympy.printing.mathml.MathMLContentPrinter(settings=None)
Prints an expression to the Content MathML markup language.
References: https://www.w3.org/TR/MathML2/chapter4.html
printmethod = '_mathml_content'
mathml_tag(e)
Returns the MathML tag for an expression.
class sympy.printing.mathml.MathMLPresentationPrinter(settings=None)
Prints an expression to the Presentation MathML markup language.
References: https://www.w3.org/TR/MathML2/chapter3.html
printmethod = '_mathml_presentation'
mathml_tag(e)
Returns the MathML tag for an expression.
sympy.printing.mathml.mathml(expr, printer=’content’, **settings)
Returns the MathML representation of expr. If printer is presentation then prints Pre-
sentation MathML else prints content MathML.
sympy.printing.mathml.print_mathml(expr, printer=’content’, **settings)
Prints a pretty representation of the MathML code for expr. If printer is presentation
then prints Presentation MathML else prints content MathML.

1076 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> ##
>>> from sympy.printing.mathml import print_mathml
>>> from sympy.abc import x
>>> print_mathml(x+1) #doctest: +NORMALIZE_WHITESPACE
<apply>
<plus/>
<ci>x</ci>
<cn>1</cn>
</apply>
>>> print_mathml(x+1, printer='presentation')
<mrow>
<mi>x</mi>
<mo>+</mo>
<mn>1</mn>
</mrow>

5.20.17 PythonCodePrinter

Python code printers

This module contains python code printers for plain python as well as NumPy & SciPy enabled
code.
class sympy.printing.pycode.MpmathPrinter(settings=None)
Lambda printer for mpmath which maintains precision for floats

Attributes

modules

class sympy.printing.pycode.NumPyPrinter(settings=None)
Numpy printer which handles vectorized piecewise functions, logical operators, etc.

Attributes

modules

sympy.printing.pycode.pycode(expr, **settings)
Converts an expr to a string of Python code
Parameters expr : Expr
A SymPy expression.
fully_qualified_modules : bool
Whether or not to write out full module names of functions (math.sin
vs. sin). default: True.

5.20. Printing System 1077

SymPy Documentation, Release 1.3

Examples

>>> from sympy import tan, Symbol

>>> from sympy.printing.pycode import pycode
>>> pycode(tan(Symbol('x')) + 1)
'math.tan(x) + 1'

5.20.18 PythonPrinter

This class implements Python printing. Usage:

>>> from sympy import print_python, sin

>>> from sympy.abc import x

>>> print_python(5*x**3 + sin(x))

x = Symbol('x')
e = 5*x**3 + sin(x)

5.20.19 srepr

This printer generates executable code. This code satisfies the identity eval(srepr(expr))
== expr.
srepr() gives more low level textual output than repr()
Example:

>>> repr(5*x**3 + sin(x))

'5*x**3 + sin(x)'

>>> srepr(5*x**3 + sin(x))

”Add(Mul(Integer(5), Pow(Symbol('x'), Integer(3))), sin(Symbol('x')))”

srepr() gives the repr form, which is what repr() would normally give but for SymPy we
don’t actually use srepr() for __repr__ because it’s is so verbose, it is unlikely that anyone
would want it called by default. Another reason is that lists call repr on their elements, like
print([a, b, c]) calls repr(a), repr(b), repr(c). So if we used srepr for ‘‘ __repr__‘‘ any
list with SymPy objects would include the srepr form, even if we used str() or print().
class sympy.printing.repr.ReprPrinter(settings=None)

printmethod = '_sympyrepr'
emptyPrinter(expr)
The fallback printer.
reprify(args, sep)
Prints each item in args and joins them with sep.
sympy.printing.repr.srepr(expr, **settings)
return expr in repr form

1078 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.20.20 StrPrinter

This module generates readable representations of SymPy expressions.

class sympy.printing.str.StrPrinter(settings=None)

printmethod = '_sympystr'
sympy.printing.str.sstrrepr(expr, **settings)
return expr in mixed str/repr form
i.e. strings are returned in repr form with quotes, and everything else is returned in str
form.
This function could be useful for hooking into sys.displayhook

5.20.21 Tree Printing

The functions in this module create a representation of an expression as a tree.

sympy.printing.tree.pprint_nodes(subtrees)
Prettyprints systems of nodes.

Examples

>>> from sympy.printing.tree import pprint_nodes

>>> print(pprint_nodes([”a”, ”b1\nb2”, ”c”]))
+-a
+-b1
| b2
+-c

sympy.printing.tree.print_node(node)
Returns information about the “node”.
This includes class name, string representation and assumptions.
sympy.printing.tree.tree(node)
Returns a tree representation of “node” as a string.
It uses print_node() together with pprint_nodes() on node.args recursively.
See also: print_tree()
sympy.printing.tree.print_tree(node)
Prints a tree representation of “node”.

Examples

>>> from sympy.printing import print_tree

>>> from sympy import Symbol
>>> x = Symbol('x', odd=True)
>>> y = Symbol('y', even=True)
>>> print_tree(y**x)
(continues on next page)

5.20. Printing System 1079

SymPy Documentation, Release 1.3

(continued from previous page)

Pow: y**x
+-Symbol: y
| algebraic: True
| commutative: True
| complex: True
| even: True
| hermitian: True
| imaginary: False
| integer: True
| irrational: False
| noninteger: False
| odd: False
| rational: True
| real: True
| transcendental: False
+-Symbol: x
algebraic: True
commutative: True
complex: True
even: False
hermitian: True
imaginary: False
integer: True
irrational: False
noninteger: False
nonzero: True
odd: True
rational: True
real: True
transcendental: False
zero: False

See also: tree()

5.20.22 Preview

A useful function is preview:

sympy.printing.preview.preview(expr, output=’png’, viewer=None, euler=True,
packages=(), filename=None, outputbuffer=None,
preamble=None, dvioptions=None, outputTex-
File=None, **latex_settings)
View expression or LaTeX markup in PNG, DVI, PostScript or PDF form.
If the expr argument is an expression, it will be exported to LaTeX and then compiled
using the available TeX distribution. The first argument, ‘expr’, may also be a LaTeX
string. The function will then run the appropriate viewer for the given output format or
use the user defined one. By default png output is generated.
By default pretty Euler fonts are used for typesetting (they were used to typeset the
well known “Concrete Mathematics” book). For that to work, you need the ‘eulervm.sty’
LaTeX style (in Debian/Ubuntu, install the texlive-fonts-extra package). If you prefer
default AMS fonts or your system lacks ‘eulervm’ LaTeX package then unset the ‘euler’
keyword argument.
To use viewer auto-detection, lets say for ‘png’ output, issue

1080 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import symbols, preview, Symbol

>>> x, y = symbols(”x,y”)

>>> preview(x + y, output='png')

This will choose ‘pyglet’ by default. To select a different one, do

>>> preview(x + y, output='png', viewer='gimp')

The ‘png’ format is considered special. For all other formats the rules are slightly differ-
ent. As an example we will take ‘dvi’ output format. If you would run

>>> preview(x + y, output='dvi')

then ‘view’ will look for available ‘dvi’ viewers on your system (predefined in the function,
so it will try evince, first, then kdvi and xdvi). If nothing is found you will need to set the
viewer explicitly.

>>> preview(x + y, output='dvi', viewer='superior-dvi-viewer')

This will skip auto-detection and will run user specified ‘superior-dvi-viewer’. If ‘view’
fails to find it on your system it will gracefully raise an exception.
You may also enter ‘file’ for the viewer argument. Doing so will cause this function to
return a file object in read-only mode, if ‘filename’ is unset. However, if it was set, then
‘preview’ writes the genereted file to this filename instead.
There is also support for writing to a BytesIO like object, which needs to be passed to
the ‘outputbuffer’ argument.

>>> from io import BytesIO

>>> obj = BytesIO()
>>> preview(x + y, output='png', viewer='BytesIO',
... outputbuffer=obj)

The LaTeX preamble can be customized by setting the ‘preamble’ keyword argument.
This can be used, e.g., to set a different font size, use a custom documentclass or import
certain set of LaTeX packages.

>>> preamble = ”\\documentclass[10pt]{article}\n” \

... ”\\usepackage{amsmath,amsfonts}\\begin{document}”
>>> preview(x + y, output='png', preamble=preamble)

If the value of ‘output’ is different from ‘dvi’ then command line options can be set (‘dviop-
tions’ argument) for the execution of the ‘dvi’+output conversion tool. These options
have to be in the form of a list of strings (see subprocess.Popen).
Additional keyword args will be passed to the latex call, e.g., the symbol_names flag.

>>> phidd = Symbol('phidd')

>>> preview(phidd, symbol_names={phidd:r'\ddot{\varphi}'})

For post-processing the generated TeX File can be written to a file by passing the desired
filename to the ‘outputTexFile’ keyword argument. To write the TeX code to a file named
“sample.tex” and run the default png viewer to display the resulting bitmap, do

5.20. Printing System 1081

SymPy Documentation, Release 1.3

>>> preview(x + y, outputTexFile=”sample.tex”)

5.20.23 Implementation - Helper Classes/Functions

sympy.printing.conventions.split_super_sub(text)
Split a symbol name into a name, superscripts and subscripts
The first part of the symbol name is considered to be its actual ‘name’, followed by
super- and subscripts. Each superscript is preceded with a “^” character or by “__”.
Each subscript is preceded by a “_” character. The three return values are the actual
name, a list with superscripts and a list with subscripts.

>>> from sympy.printing.conventions import split_super_sub

>>> split_super_sub('a_x^1')
('a', ['1'], ['x'])
>>> split_super_sub('var_sub1__sup_sub2')
('var', ['sup'], ['sub1', 'sub2'])

CodePrinter

This class is a base class for other classes that implement code-printing functionality, and
additionally lists a number of functions that cannot be easily translated to C or Fortran.
class sympy.printing.codeprinter.Assignment
Represents variable assignment for code generation.
Parameters lhs : Expr
Sympy object representing the lhs of the expression. These should
be singular objects, such as one would use in writing code. Notable
types include Symbol, MatrixSymbol, MatrixElement, and Indexed.
Types that subclass these types are also supported.
rhs : Expr
Sympy object representing the rhs of the expression. This can be any
type, provided its shape corresponds to that of the lhs. For example,
a Matrix type can be assigned to MatrixSymbol, but not to Symbol,
as the dimensions will not align.

Examples

>>> from sympy import symbols, MatrixSymbol, Matrix

>>> from sympy.codegen.ast import Assignment
>>> x, y, z = symbols('x, y, z')
>>> Assignment(x, y)
Assignment(x, y)
>>> Assignment(x, 0)
Assignment(x, 0)
>>> A = MatrixSymbol('A', 1, 3)
>>> mat = Matrix([x, y, z]).T
>>> Assignment(A, mat)
(continues on next page)

1082 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Assignment(A, Matrix([[x, y, z]]))
>>> Assignment(A[0, 1], x)
Assignment(A[0, 1], x)

class sympy.printing.codeprinter.CodePrinter(settings=None)
The base class for code-printing subclasses.
printmethod = '_sympystr'
exception sympy.printing.codeprinter.AssignmentError
Raised if an assignment variable for a loop is missing.

Precedence

sympy.printing.precedence.PRECEDENCE = {'Add': 40, 'And': 30, 'Atom': 1000, 'BitwiseAnd': 3

Default precedence values for some basic types.
sympy.printing.precedence.PRECEDENCE_VALUES = {'Add': 40, 'And': 30, 'Equality': 50, 'Equiv
A dictionary assigning precedence values to certain classes. These values are treated
like they were inherited, so not every single class has to be named here.
sympy.printing.precedence.PRECEDENCE_FUNCTIONS = {'Float': <function precedence_Float>, 'Fr
Sometimes it’s not enough to assign a fixed precedence value to a class. Then a function
can be inserted in this dictionary that takes an instance of this class as argument and
returns the appropriate precedence value.
sympy.printing.precedence.precedence(item)
Returns the precedence of a given object.

5.20.24 Pretty-Printing Implementation Helpers

sympy.printing.pretty.pretty_symbology.U(name)
unicode character by name or None if not found
sympy.printing.pretty.pretty_symbology.pretty_use_unicode(flag=None)
Set whether pretty-printer should use unicode by default
sympy.printing.pretty.pretty_symbology.pretty_try_use_unicode()
See if unicode output is available and leverage it if possible
sympy.printing.pretty.pretty_symbology.xstr(*args)
call str or unicode depending on current mode
The following two functions return the Unicode version of the inputted Greek letter.
sympy.printing.pretty.pretty_symbology.g(l)
sympy.printing.pretty.pretty_symbology.G(l)
sympy.printing.pretty.pretty_symbology.greek_letters = ['alpha', 'beta', 'gamma', 'delta',
list() -> new empty list list(iterable) -> new list initialized from iterable’s items
sympy.printing.pretty.pretty_symbology.digit_2txt = {'0': 'ZERO', '1': 'ONE', '2': 'TWO', '
sympy.printing.pretty.pretty_symbology.symb_2txt = {'(': 'LEFT PARENTHESIS', ')': 'RIGHT PA
The following functions return the Unicode subscript/superscript version of the character.
sympy.printing.pretty.pretty_symbology.sub = {'(': '₍', ')': '₎', '+': '₊', '-': '₋', '0':

5.20. Printing System 1083

SymPy Documentation, Release 1.3

sympy.printing.pretty.pretty_symbology.sup = {'(': '⁽', ')': '⁾', '+': '⁺', '-': '⁻', '0':
The following functions return Unicode vertical objects.
sympy.printing.pretty.pretty_symbology.xobj(symb, length)
Construct spatial object of given length.
return: [] of equal-length strings
sympy.printing.pretty.pretty_symbology.vobj(symb, height)
Construct vertical object of a given height
see: xobj
sympy.printing.pretty.pretty_symbology.hobj(symb, width)
Construct horizontal object of a given width
see: xobj
The following constants are for rendering roots and fractions.
sympy.printing.pretty.pretty_symbology.root = {2: '√', 3: '∛', 4: '∜'}
sympy.printing.pretty.pretty_symbology.VF(txt)
sympy.printing.pretty.pretty_symbology.frac = {(1, 2): '½', (1, 3): '⅓', (1, 4): '¼', (1, 5
The following constants/functions are for rendering atoms and symbols.
sympy.printing.pretty.pretty_symbology.xsym(sym)
get symbology for a ‘character’
sympy.printing.pretty.pretty_symbology.atoms_table = {'Complexes': 'ℂ', 'EmptySet': '∅', 'E
sympy.printing.pretty.pretty_symbology.pretty_atom(atom_name, de-
fault=None)
return pretty representation of an atom
sympy.printing.pretty.pretty_symbology.pretty_symbol(symb_name)
return pretty representation of a symbol
sympy.printing.pretty.pretty_symbology.annotated(letter)
Return a stylised drawing of the letter letter, together with information on how to put
annotations (super- and subscripts to the left and to the right) on it.
See pretty.py functions _print_meijerg, _print_hyper on how to use this information.
Prettyprinter by Jurjen Bos. (I hate spammers: mail me at pietjepuk314 at the reverse of
ku.oc.oohay). All objects have a method that create a “stringPict”, that can be used in the str
method for pretty printing.
Updates by Jason Gedge (email <my last name> at cs mun ca)
• terminal_string() method
• minor fixes and changes (mostly to prettyForm)
TODO:
• Allow left/center/right alignment options for above/below and top/center/bottom
alignment options for left/right
class sympy.printing.pretty.stringpict.stringPict(s, baseline=0)
An ASCII picture. The pictures are represented as a list of equal length strings.

1084 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

above(*args)
Put pictures above this picture. Returns string, baseline arguments for stringPict.
Baseline is baseline of bottom picture.
below(*args)
Put pictures under this picture. Returns string, baseline arguments for stringPict.
Baseline is baseline of top picture

Examples

>>> from sympy.printing.pretty.stringpict import stringPict

>>> print(stringPict(”x+3”).below(
... stringPict.LINE, '3')[0]) #doctest: +NORMALIZE_WHITESPACE
x+3
---
3

height()
The height of the picture in characters.
left(*args)
Put pictures (left to right) at left. Returns string, baseline arguments for stringPict.
leftslash()
Precede object by a slash of the proper size.
static next(*args)
Put a string of stringPicts next to each other. Returns string, baseline arguments
for stringPict.
parens(left=’(’, right=’)’, ifascii_nougly=False)
Put parentheses around self. Returns string, baseline arguments for stringPict.
left or right can be None or empty string which means ‘no paren from that side’
render(*args, **kwargs)
Return the string form of self.
Unless the argument line_break is set to False, it will break the expression in a form
that can be printed on the terminal without being broken up.
right(*args)
Put pictures next to this one. Returns string, baseline arguments for stringPict.
(Multiline) strings are allowed, and are given a baseline of 0.

Examples

>>> from sympy.printing.pretty.stringpict import stringPict

>>> print(stringPict(”10”).right(” + ”,stringPict(”1\r-\r2”,1))[0])
1
10 + -
2

root(n=None)
Produce a nice root symbol. Produces ugly results for big n inserts.

5.20. Printing System 1085

SymPy Documentation, Release 1.3

static stack(*args)
Put pictures on top of each other, from top to bottom. Returns string, baseline argu-
ments for stringPict. The baseline is the baseline of the second picture. Everything
is centered. Baseline is the baseline of the second picture. Strings are allowed. The
special value stringPict.LINE is a row of ‘-‘ extended to the width.
terminal_width()
Return the terminal width if possible, otherwise return 0.
width()
The width of the picture in characters.
class sympy.printing.pretty.stringpict.prettyForm(s, baseline=0, binding=0,
unicode=None)
Extension of the stringPict class that knows about basic math applications, optimizing
double minus signs.
“Binding” is interpreted as follows:

ATOM this is an atom: never needs to be parenthesized

FUNC this is a function application: parenthesize if added (?)
DIV this is a division: make wider division if divided
POW this is a power: only parenthesize if exponent
MUL this is a multiplication: parenthesize if powered
ADD this is an addition: parenthesize if multiplied or powered
NEG this is a negative number: optimize if added, parenthesize if
multiplied or powered
OPEN this is an open object: parenthesize if added, multiplied, or
powered (example: Piecewise)

static apply(function, *args)

Functions of one or more variables.

5.20.25 dotprint

sympy.printing.dot.dotprint(expr, styles=((<class ’sympy.core.basic.Basic’>,

{’color’: ’blue’, ’shape’: ’ellipse’}), (<class
’sympy.core.expr.Expr’>, {’color’: ’black’})),
atom=<function <lambda>>, maxdepth=None,
repeat=True, labelfunc=<class ’str’>, **kwargs)
DOT description of a SymPy expression tree
Options are
styles: Styles for different classes. The default is:

[(Basic, {'color': 'blue', 'shape': 'ellipse'}),

(Expr, {'color': 'black'})]``

atom: Function used to determine if an arg is an atom. The default is lambda

x: not isinstance(x, Basic). Another good choice is lambda x: not x.args.

maxdepth: The maximum depth. The default is None, meaning no limit.

repeat: Whether to different nodes for separate common subexpressions. The
default is True. For example, for x + x*y with repeat=True, it will have two nodes
for x and with repeat=False, it will have one (warning: even if it appears twice

1086 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

in the same object, like Pow(x, x), it will still only appear only once. Hence, with
repeat=False, the number of arrows out of an object might not equal the number of
args it has).
labelfunc: How to label leaf nodes. The default is str. Another good option is
srepr. For example with str, the leaf nodes of x + 1 are labeled, x and 1. With
srepr, they are labeled Symbol('x') and Integer(1).
Additional keyword arguments are included as styles for the graph.

Examples

>>> from sympy.printing.dot import dotprint

>>> from sympy.abc import x
>>> print(dotprint(x+2)) # doctest: +NORMALIZE_WHITESPACE
digraph{
<BLANKLINE>
# Graph style
”ordering”=”out”
”rankdir”=”TD”
<BLANKLINE>
#########
# Nodes #
#########
<BLANKLINE>
”Add(Integer(2), Symbol(x))_()” [”color”=”black”, ”label”=”Add”, ”shape”=”ellipse
,→”];

”Integer(2)_(0,)” [”color”=”black”, ”label”=”2”, ”shape”=”ellipse”];

”Symbol(x)_(1,)” [”color”=”black”, ”label”=”x”, ”shape”=”ellipse”];
<BLANKLINE>
#########
# Edges #
#########
<BLANKLINE>
”Add(Integer(2), Symbol(x))_()” -> ”Integer(2)_(0,)”;
”Add(Integer(2), Symbol(x))_()” -> ”Symbol(x)_(1,)”;
}

5.21 Plotting Module

5.21.1 Introduction

The plotting module allows you to make 2-dimensional and 3-dimensional plots. Presently the
plots are rendered using matplotlib as a backend. It is also possible to plot 2-dimensional
plots using a TextBackend if you don’t have matplotlib.
The plotting module has the following functions:
• plot: Plots 2D line plots.
• plot_parametric: Plots 2D parametric plots.
• plot_implicit: Plots 2D implicit and region plots.
• plot3d: Plots 3D plots of functions in two variables.

5.21. Plotting Module 1087

SymPy Documentation, Release 1.3

• plot3d_parametric_line: Plots 3D line plots, defined by a parameter.

• plot3d_parametric_surface: Plots 3D parametric surface plots.
The above functions are only for convenience and ease of use. It is possible to plot any plot
by passing the corresponding Series class to Plot as argument.

5.21.2 Plot Class

class sympy.plotting.plot.Plot(*args, **kwargs)

The central class of the plotting module.
For interactive work the function plot is better suited.
This class permits the plotting of sympy expressions using numerous backends (mat-
plotlib, textplot, the old pyglet module for sympy, Google charts api, etc).
The figure can contain an arbitrary number of plots of sympy expressions, lists of coor-
dinates of points, etc. Plot has a private attribute _series that contains all data series
to be plotted (expressions for lines or surfaces, lists of points, etc (all subclasses of
BaseSeries)). Those data series are instances of classes not imported by from sympy
import *.
The customization of the figure is on two levels. Global options that concern the figure as
a whole (eg title, xlabel, scale, etc) and per-data series options (eg name) and aesthetics
(eg. color, point shape, line type, etc.).
The difference between options and aesthetics is that an aesthetic can be a function
of the coordinates (or parameters in a parametric plot). The supported values for an
aesthetic are: - None (the backend uses default values) - a constant - a function of one
variable (the first coordinate or parameter) - a function of two variables (the first and
second coordinate or parameters) - a function of three variables (only in nonparametric
3D plots) Their implementation depends on the backend so they may not work in some
backends.
If the plot is parametric and the arity of the aesthetic function permits it the aesthetic
is calculated over parameters and not over coordinates. If the arity does not permit
calculation over parameters the calculation is done over coordinates.
Only cartesian coordinates are supported for the moment, but you can use the parametric
plots to plot in polar, spherical and cylindrical coordinates.
The arguments for the constructor Plot must be subclasses of BaseSeries.
Any global option can be specified as a keyword argument.
The global options for a figure are:
• title : str
• xlabel : str
• ylabel : str
• legend : bool
• xscale : {‘linear’, ‘log’}
• yscale : {‘linear’, ‘log’}
• axis : bool
• axis_center : tuple of two floats or {‘center’, ‘auto’}

1088 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• xlim : tuple of two floats

• ylim : tuple of two floats
• aspect_ratio : tuple of two floats or {‘auto’}
• autoscale : bool
• margin : float in [0, 1]
The per data series options and aesthetics are: There are none in the base series. See
below for options for subclasses.
Some data series support additional aesthetics or options:
ListSeries, LineOver1DRangeSeries, Parametric2DLineSeries, Parametric3DLineSeries
support the following:
Aesthetics:
• line_color : function which returns a float.
options:
• label : str
• steps : bool
• integers_only : bool
SurfaceOver2DRangeSeries, ParametricSurfaceSeries support the following:
aesthetics:
• surface_color : function which returns a float.
append(arg)
Adds an element from a plot’s series to an existing plot.
See also:
extend (page 1089)

Examples

Consider two Plot objects, p1 and p2. To add the second plot’s first series object to
the first, use the append method, like so:

>>> from sympy import symbols

>>> from sympy.plotting import plot
>>> x = symbols('x')
>>> p1 = plot(x*x)
>>> p2 = plot(x)
>>> p1.append(p2[0])
>>> p1
Plot object containing:
[0]: cartesian line: x**2 for x over (-10.0, 10.0)
[1]: cartesian line: x for x over (-10.0, 10.0)

extend(arg)
Adds all series from another plot.

5.21. Plotting Module 1089

SymPy Documentation, Release 1.3

Examples

Consider two Plot objects, p1 and p2. To add the second plot to the first, use the
extend method, like so:

>>> from sympy import symbols

>>> from sympy.plotting import plot
>>> x = symbols('x')
>>> p1 = plot(x*x)
>>> p2 = plot(x)
>>> p1.extend(p2)
>>> p1
Plot object containing:
[0]: cartesian line: x**2 for x over (-10.0, 10.0)
[1]: cartesian line: x for x over (-10.0, 10.0)

5.21.3 Plotting Function Reference

sympy.plotting.plot.plot(*args, **kwargs)
Plots a function of a single variable and returns an instance of the Plot class (also, see
the description of the show keyword argument below).
The plotting uses an adaptive algorithm which samples recursively to accurately plot the
plot. The adaptive algorithm uses a random point near the midpoint of two points that
has to be further sampled. Hence the same plots can appear slightly different.
See also:
Plot (page 1088), LineOver1DRangeSeries.

Examples

>>> from sympy import symbols

>>> from sympy.plotting import plot
>>> x = symbols('x')

Single Plot

>>> plot(x**2, (x, -5, 5))

Plot object containing:
[0]: cartesian line: x**2 for x over (-5.0, 5.0)

Multiple plots with single range.

>>> plot(x, x**2, x**3, (x, -5, 5))

Plot object containing:
[0]: cartesian line: x for x over (-5.0, 5.0)
[1]: cartesian line: x**2 for x over (-5.0, 5.0)
[2]: cartesian line: x**3 for x over (-5.0, 5.0)

Multiple plots with different ranges.

1090 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> plot((x**2, (x, -6, 6)), (x, (x, -5, 5)))

Plot object containing:
[0]: cartesian line: x**2 for x over (-6.0, 6.0)
[1]: cartesian line: x for x over (-5.0, 5.0)

No adaptive sampling.

>>> plot(x**2, adaptive=False, nb_of_points=400)

Plot object containing:
[0]: cartesian line: x**2 for x over (-10.0, 10.0)

Usage

Single Plot
plot(expr, range, **kwargs)
If the range is not specified, then a default range of (-10, 10) is used.
Multiple plots with same range.
plot(expr1, expr2, ..., range, **kwargs)
If the range is not specified, then a default range of (-10, 10) is used.
Multiple plots with different ranges.
plot((expr1, range), (expr2, range), ..., **kwargs)
Range has to be specified for every expression.
Default range may change in the future if a more advanced default range detection al-
gorithm is implemented.

Arguments

expr : Expression representing the function of single variable

range: (x, 0, 5), A 3-tuple denoting the range of the free variable.

Keyword Arguments

Arguments for plot function:

show: Boolean. The default value is set to True. Set show to False and the function will
not display the plot. The returned instance of the Plot class can then be used to save or
display the plot by calling the save() and show() methods respectively.
Arguments for LineOver1DRangeSeries class:
adaptive: Boolean. The default value is set to True. Set adaptive to False and specify
nb_of_points if uniform sampling is required.
depth: int Recursion depth of the adaptive algorithm. A depth of value n samples a
maximum of 2n points.
nb_of_points: int. Used when the adaptive is set to False. The function is uniformly
sampled at nb_of_points number of points.

5.21. Plotting Module 1091

SymPy Documentation, Release 1.3

Aesthetics options:
line_color: float. Specifies the color for the plot. See Plot to see how to set color for
the plots.
If there are multiple plots, then the same series series are applied to all the plots. If you
want to set these options separately, you can index the Plot object returned and set it.
Arguments for Plot class:
title : str. Title of the plot. It is set to the latex representation of the expression, if the
plot has only one expression.
xlabel : str. Label for the x-axis.
ylabel : str. Label for the y-axis.
xscale: {‘linear’, ‘log’} Sets the scaling of the x-axis.
yscale: {‘linear’, ‘log’} Sets the scaling if the y-axis.
axis_center: tuple of two floats denoting the coordinates of the center or {‘center’,
‘auto’}
xlim : tuple of two floats, denoting the x-axis limits.
ylim : tuple of two floats, denoting the y-axis limits.
sympy.plotting.plot.plot_parametric(*args, **kwargs)
Plots a 2D parametric plot.
The plotting uses an adaptive algorithm which samples recursively to accurately plot the
plot. The adaptive algorithm uses a random point near the midpoint of two points that
has to be further sampled. Hence the same plots can appear slightly different.
See also:
Plot (page 1088), Parametric2DLineSeries (page 1100)

Examples

>>> from sympy import symbols, cos, sin

>>> from sympy.plotting import plot_parametric
>>> u = symbols('u')

Single Parametric plot

>>> plot_parametric(cos(u), sin(u), (u, -5, 5))

Plot object containing:
[0]: parametric cartesian line: (cos(u), sin(u)) for u over (-5.0, 5.0)

Multiple parametric plot with single range.

>>> plot_parametric((cos(u), sin(u)), (u, cos(u)))

Plot object containing:
[0]: parametric cartesian line: (cos(u), sin(u)) for u over (-10.0, 10.0)
[1]: parametric cartesian line: (u, cos(u)) for u over (-10.0, 10.0)

Multiple parametric plots.

1092 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> plot_parametric((cos(u), sin(u), (u, -5, 5)),

... (cos(u), u, (u, -5, 5)))
Plot object containing:
[0]: parametric cartesian line: (cos(u), sin(u)) for u over (-5.0, 5.0)
[1]: parametric cartesian line: (cos(u), u) for u over (-5.0, 5.0)

Usage

Single plot.
plot_parametric(expr_x, expr_y, range, **kwargs)
If the range is not specified, then a default range of (-10, 10) is used.
Multiple plots with same range.
plot_parametric((expr1_x, expr1_y), (expr2_x, expr2_y), range, **kwargs)
If the range is not specified, then a default range of (-10, 10) is used.
Multiple plots with different ranges.
plot_parametric((expr_x, expr_y, range), ..., **kwargs)
Range has to be specified for every expression.
Default range may change in the future if a more advanced default range detection al-
gorithm is implemented.

Arguments

expr_x : Expression representing the function along x.

expr_y : Expression representing the function along y.
range: (u, 0, 5), A 3-tuple denoting the range of the parameter variable.

Keyword Arguments

Arguments for Parametric2DLineSeries class:

adaptive: Boolean. The default value is set to True. Set adaptive to False and specify
nb_of_points if uniform sampling is required.
depth: int Recursion depth of the adaptive algorithm. A depth of value n samples a
maximum of 2n points.
nb_of_points: int. Used when the adaptive is set to False. The function is uniformly
sampled at nb_of_points number of points.

Aesthetics

line_color: function which returns a float. Specifies the color for the plot. See sympy.
plotting.Plot for more details.

5.21. Plotting Module 1093

SymPy Documentation, Release 1.3

If there are multiple plots, then the same Series arguments are applied to all the plots.
If you want to set these options separately, you can index the returned Plot object and
set it.
Arguments for Plot class:
xlabel : str. Label for the x-axis.
ylabel : str. Label for the y-axis.
xscale: {‘linear’, ‘log’} Sets the scaling of the x-axis.
yscale: {‘linear’, ‘log’} Sets the scaling if the y-axis.
axis_center: tuple of two floats denoting the coordinates of the center or {‘center’,
‘auto’}
xlim : tuple of two floats, denoting the x-axis limits.
ylim : tuple of two floats, denoting the y-axis limits.
sympy.plotting.plot.plot3d(*args, **kwargs)
Plots a 3D surface plot.
See also:
Plot (page 1088), SurfaceOver2DRangeSeries (page 1100)

Examples

>>> from sympy import symbols

>>> from sympy.plotting import plot3d
>>> x, y = symbols('x y')

Single plot

>>> plot3d(x*y, (x, -5, 5), (y, -5, 5))

Plot object containing:
[0]: cartesian surface: x*y for x over (-5.0, 5.0) and y over (-5.0, 5.0)

Multiple plots with same range

>>> plot3d(x*y, -x*y, (x, -5, 5), (y, -5, 5))

Plot object containing:
[0]: cartesian surface: x*y for x over (-5.0, 5.0) and y over (-5.0, 5.0)
[1]: cartesian surface: -x*y for x over (-5.0, 5.0) and y over (-5.0, 5.0)

Multiple plots with different ranges.

>>> plot3d((x**2 + y**2, (x, -5, 5), (y, -5, 5)),

... (x*y, (x, -3, 3), (y, -3, 3)))
Plot object containing:
[0]: cartesian surface: x**2 + y**2 for x over (-5.0, 5.0) and y over (-5.0, 5.0)
[1]: cartesian surface: x*y for x over (-3.0, 3.0) and y over (-3.0, 3.0)

Usage

Single plot

1094 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

plot3d(expr, range_x, range_y, **kwargs)

If the ranges are not specified, then a default range of (-10, 10) is used.
Multiple plot with the same range.
plot3d(expr1, expr2, range_x, range_y, **kwargs)
If the ranges are not specified, then a default range of (-10, 10) is used.
Multiple plots with different ranges.
plot3d((expr1, range_x, range_y), (expr2, range_x, range_y), ...,
**kwargs)
Ranges have to be specified for every expression.
Default range may change in the future if a more advanced default range detection al-
gorithm is implemented.

Arguments

expr : Expression representing the function along x.

range_x: (x, 0, 5), A 3-tuple denoting the range of the x variable.
range_y: (y, 0, 5), A 3-tuple denoting the range of the y variable.

Keyword Arguments

Arguments for SurfaceOver2DRangeSeries class:

nb_of_points_x: int. The x range is sampled uniformly at nb_of_points_x of points.
nb_of_points_y: int. The y range is sampled uniformly at nb_of_points_y of points.
Aesthetics:
surface_color: Function which returns a float. Specifies the color for the surface of
the plot. See sympy.plotting.Plot for more details.
If there are multiple plots, then the same series arguments are applied to all the plots.
If you want to set these options separately, you can index the returned Plot object and
set it.
Arguments for Plot class:
title : str. Title of the plot.
sympy.plotting.plot.plot3d_parametric_line(*args, **kwargs)
Plots a 3D parametric line plot.
See also:
Plot (page 1088), Parametric3DLineSeries (page 1100)

Examples

5.21. Plotting Module 1095

SymPy Documentation, Release 1.3

>>> from sympy import symbols, cos, sin

>>> from sympy.plotting import plot3d_parametric_line
>>> u = symbols('u')

Single plot.

>>> plot3d_parametric_line(cos(u), sin(u), u, (u, -5, 5))

Plot object containing:
[0]: 3D parametric cartesian line: (cos(u), sin(u), u) for u over (-5.0, 5.0)

Multiple plots.

>>> plot3d_parametric_line((cos(u), sin(u), u, (u, -5, 5)),

... (sin(u), u**2, u, (u, -5, 5)))
Plot object containing:
[0]: 3D parametric cartesian line: (cos(u), sin(u), u) for u over (-5.0, 5.0)
[1]: 3D parametric cartesian line: (sin(u), u**2, u) for u over (-5.0, 5.0)

Usage

Single plot:
plot3d_parametric_line(expr_x, expr_y, expr_z, range, **kwargs)
If the range is not specified, then a default range of (-10, 10) is used.
Multiple plots.
plot3d_parametric_line((expr_x, expr_y, expr_z, range), ..., **kwargs)
Ranges have to be specified for every expression.
Default range may change in the future if a more advanced default range detection al-
gorithm is implemented.

Arguments

expr_x : Expression representing the function along x.

expr_y : Expression representing the function along y.
expr_z : Expression representing the function along z.
range: (u, 0, 5), A 3-tuple denoting the range of the parameter variable.

Keyword Arguments

Arguments for Parametric3DLineSeries class.

nb_of_points: The range is uniformly sampled at nb_of_points number of points.
Aesthetics:
line_color: function which returns a float. Specifies the color for the plot. See sympy.
plotting.Plot for more details.

1096 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If there are multiple plots, then the same series arguments are applied to all the plots.
If you want to set these options separately, you can index the returned Plot object and
set it.
Arguments for Plot class.
title : str. Title of the plot.
sympy.plotting.plot.plot3d_parametric_surface(*args, **kwargs)
Plots a 3D parametric surface plot.
See also:
Plot (page 1088), ParametricSurfaceSeries (page 1101)

Examples

>>> from sympy import symbols, cos, sin

>>> from sympy.plotting import plot3d_parametric_surface
>>> u, v = symbols('u v')

Single plot.
>>> plot3d_parametric_surface(cos(u + v), sin(u - v), u - v,
... (u, -5, 5), (v, -5, 5))
Plot object containing:
[0]: parametric cartesian surface: (cos(u + v), sin(u - v), u - v) for u over (-5.
,→0, 5.0) and v over (-5.0, 5.0)

Usage

Single plot.
plot3d_parametric_surface(expr_x, expr_y, expr_z, range_u, range_v,
**kwargs)
If the ranges is not specified, then a default range of (-10, 10) is used.
Multiple plots.
plot3d_parametric_surface((expr_x, expr_y, expr_z, range_u, range_v), ...
, **kwargs)
Ranges have to be specified for every expression.
Default range may change in the future if a more advanced default range detection al-
gorithm is implemented.

Arguments

expr_x: Expression representing the function along x.

expr_y: Expression representing the function along y.
expr_z: Expression representing the function along z.
range_u: (u, 0, 5), A 3-tuple denoting the range of the u variable.
range_v: (v, 0, 5), A 3-tuple denoting the range of the v variable.

5.21. Plotting Module 1097

SymPy Documentation, Release 1.3

Keyword Arguments

Arguments for ParametricSurfaceSeries class:

nb_of_points_u: int. The u range is sampled uniformly at nb_of_points_v of points
nb_of_points_y: int. The v range is sampled uniformly at nb_of_points_y of points
Aesthetics:
surface_color: Function which returns a float. Specifies the color for the surface of
the plot. See sympy.plotting.Plot for more details.
If there are multiple plots, then the same series arguments are applied for all the plots.
If you want to set these options separately, you can index the returned Plot object and
set it.
Arguments for Plot class:
title : str. Title of the plot.
sympy.plotting.plot_implicit.plot_implicit(expr, x_var=None, y_var=None,
**kwargs)
A plot function to plot implicit equations / inequalities.

Examples

Plot expressions:

>>> from sympy import plot_implicit, cos, sin, symbols, Eq, And
>>> x, y = symbols('x y')

Without any ranges for the symbols in the expression

>>> p1 = plot_implicit(Eq(x**2 + y**2, 5))

With the range for the symbols

>>> p2 = plot_implicit(Eq(x**2 + y**2, 3),

... (x, -3, 3), (y, -3, 3))

With depth of recursion as argument.

>>> p3 = plot_implicit(Eq(x**2 + y**2, 5),

... (x, -4, 4), (y, -4, 4), depth = 2)

Using mesh grid and not using adaptive meshing.

>>> p4 = plot_implicit(Eq(x**2 + y**2, 5),

... (x, -5, 5), (y, -2, 2), adaptive=False)

Using mesh grid with number of points as input.

>>> p5 = plot_implicit(Eq(x**2 + y**2, 5),

... (x, -5, 5), (y, -2, 2),
... adaptive=False, points=400)

Plotting regions.

1098 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> p6 = plot_implicit(y > x**2)

Plotting Using boolean conjunctions.

>>> p7 = plot_implicit(And(y > x, y > -x))

When plotting an expression with a single variable (y - 1, for example), specify the x or
the y variable explicitly:

>>> p8 = plot_implicit(y - 1, y_var=y)

>>> p9 = plot_implicit(x - 1, x_var=x)

Arguments

• expr : The equation / inequality that is to be plotted.

• x_var (optional) : symbol to plot on x-axis or tuple giving symbol and range as
(symbol, xmin, xmax)
• y_var (optional) : symbol to plot on y-axis or tuple giving symbol and range as
(symbol, ymin, ymax)

If neither x_var nor y_var are given then the free symbols in the expression will be
assigned in the order they are sorted.
The following keyword arguments can also be used:
• adaptive. Boolean. The default value is set to True. It has to be set to False
if you want to use a mesh grid.
• depth integer. The depth of recursion for adaptive mesh grid. Default value
is 0. Takes value in the range (0, 4).
• points integer. The number of points if adaptive mesh grid is not used. De-
fault value is 200.
• title string .The title for the plot.
• xlabel string. The label for the x-axis
• ylabel string. The label for the y-axis
Aesthetics options:
• line_color: float or string. Specifies the color for the plot. See Plot to see
how to set color for the plots.
plot_implicit, by default, uses interval arithmetic to plot functions. If the expression can-
not be plotted using interval arithmetic, it defaults to a generating a contour using a mesh
grid of fixed number of points. By setting adaptive to False, you can force plot_implicit
to use the mesh grid. The mesh grid method can be effective when adaptive plotting
using interval arithmetic, fails to plot with small line width.

5.21.4 Series Classes

class sympy.plotting.plot.BaseSeries
Base class for the data objects containing stuff to be plotted.

5.21. Plotting Module 1099

SymPy Documentation, Release 1.3

The backend should check if it supports the data series that it’s given. (eg TextBackend
supports only LineOver1DRange). It’s the backend responsibility to know how to use the
class of data series that it’s given.
Some data series classes are grouped (using a class attribute like is_2Dline) according
to the api they present (based only on convention). The backend is not obliged to use
that api (eg. The LineOver1DRange belongs to the is_2Dline group and presents the
get_points method, but the TextBackend does not use the get_points method).
class sympy.plotting.plot.Line2DBaseSeries
A base class for 2D lines.
• adding the label, steps and only_integers options
• making is_2Dline true
• defining get_segments and get_color_array
class sympy.plotting.plot.LineOver1DRangeSeries(expr, var_start_end, **kwargs)
Representation for a line consisting of a SymPy expression over a range.
get_segments()
Adaptively gets segments for plotting.
The adaptive sampling is done by recursively checking if three points are almost
collinear. If they are not collinear, then more points are added between those points.

References

[1] Adaptive polygonal approximation of parametric curves, Luiz Henrique

de Figueiredo.

class sympy.plotting.plot.Parametric2DLineSeries(expr_x, expr_y, var_start_end,

**kwargs)
Representation for a line consisting of two parametric sympy expressions over a range.
get_segments()
Adaptively gets segments for plotting.
The adaptive sampling is done by recursively checking if three points are almost
collinear. If they are not collinear, then more points are added between those points.

References

[1] Adaptive polygonal approximation of parametric curves, Luiz Henrique

de Figueiredo.

class sympy.plotting.plot.Line3DBaseSeries
A base class for 3D lines.
Most of the stuff is derived from Line2DBaseSeries.
class sympy.plotting.plot.Parametric3DLineSeries(expr_x, expr_y, expr_z,
var_start_end, **kwargs)
Representation for a 3D line consisting of two parametric sympy expressions and a range.
class sympy.plotting.plot.SurfaceBaseSeries
A base class for 3D surfaces.

1100 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.plotting.plot.SurfaceOver2DRangeSeries(expr, var_start_end_x,

var_start_end_y, **kwargs)
Representation for a 3D surface consisting of a sympy expression and 2D range.
class sympy.plotting.plot.ParametricSurfaceSeries(expr_x, expr_y, expr_z,
var_start_end_u,
var_start_end_v, **kwargs)
Representation for a 3D surface consisting of three parametric sympy expressions and
a range.
class sympy.plotting.plot_implicit.ImplicitSeries(expr, var_start_end_x,
var_start_end_y,
has_equality,
use_interval_math, depth,
nb_of_points, line_color)
Representation for Implicit plot

5.22 Pyglet Plotting Module

This is the documentation for the old plotting module that uses pyglet. This module has some
limitations and is not actively developed anymore. For an alternative you can look at the new
plotting module.
The pyglet plotting module can do nice 2D and 3D plots that can be controlled by console
commands as well as keyboard and mouse, with the only dependency being pyglet.
Here is the simplest usage:

>>> from sympy import var, Plot

>>> var('x y z')
>>> Plot(x*y**3-y*x**3)

To see lots of plotting examples, see examples/pyglet_plotting.py and try running it in

interactive mode (python -i plotting.py):

$ python -i examples/pyglet_plotting.py

And type for instance example(7) or example(11).

See also the Plotting Module wiki page for screenshots.

5.22. Pyglet Plotting Module 1101

SymPy Documentation, Release 1.3

5.22.1 Plot Window Controls

Camera Keys
Sensitivity Modifier SHIFT
Zoom R and F, Page Up and Down, Numpad + and -
Rotate View X,Y axis Arrow Keys, A,S,D,W, Numpad 4,6,8,2
Rotate View Z axis Q and E, Numpad 7 and 9
Rotate Ordinate Z axis Z and C, Numpad 1 and 3
View XY F1
View XZ F2
View YZ F3
View Perspective F4
Reset X, Numpad 5

Axes Keys
Toggle Visible F5
Toggle Colors F6

Window Keys
Close ESCAPE
Screenshot F8

The mouse can be used to rotate, zoom, and translate by dragging the left, middle, and right
mouse buttons respectively.

5.22.2 Coordinate Modes

Plot supports several curvilinear coordinate modes, and they are independent for each plot-
ted function. You can specify a coordinate mode explicitly with the ‘mode’ named argument,
but it can be automatically determined for cartesian or parametric plots, and therefore must
only be specified for polar, cylindrical, and spherical modes.
Specifically, Plot(function arguments) and Plot.__setitem__(i, function arguments)
(accessed using array-index syntax on the Plot instance) will interpret your arguments as a
cartesian plot if you provide one function and a parametric plot if you provide two or three
functions. Similarly, the arguments will be interpreted as a curve is one variable is used, and
a surface if two are used.
Supported mode names by number of variables:
• 1 (curves): parametric, cartesian, polar
• 2 (surfaces): parametric, cartesian, cylindrical, spherical

>>> Plot(1, 'mode=spherical; color=zfade4')

Note that function parameters are given as option strings of the form “key1=value1; key2 =
value2” (spaces are truncated). Keyword arguments given directly to plot apply to the plot
itself.

1102 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.22.3 Specifying Intervals for Variables

The basic format for variable intervals is [var, min, max, steps]. However, the syntax is quite
flexible, and arguments not specified are taken from the defaults for the current coordinate
mode:

>>> Plot(x**2) # implies [x,-5,5,100]

>>> Plot(x**2, [], []) # [x,-1,1,40], [y,-1,1,40]
>>> Plot(x**2-y**2, [100], [100]) # [x,-1,1,100], [y,-1,1,100]
>>> Plot(x**2, [x,-13,13,100])
>>> Plot(x**2, [-13,13]) # [x,-13,13,100]
>>> Plot(x**2, [x,-13,13]) # [x,-13,13,100]
>>> Plot(1*x, [], [x], 'mode=cylindrical') # [unbound_theta,0,2*Pi,40], [x,-1,1,20]

5.22.4 Using the Interactive Interface

>>> p = Plot(visible=False)
>>> f = x**2
>>> p[1] = f
>>> p[2] = f.diff(x)
>>> p[3] = f.diff(x).diff(x)
>>> p
[1]: x**2, 'mode=cartesian'
[2]: 2*x, 'mode=cartesian'
[3]: 2, 'mode=cartesian'
>>> p.show()
>>> p.clear()
>>> p
<blank plot>
>>> p[1] = x**2+y**2
>>> p[1].style = 'solid'
>>> p[2] = -x**2-y**2
>>> p[2].style = 'wireframe'
>>> p[1].color = z, (0.4,0.4,0.9), (0.9,0.4,0.4)
>>> p[1].style = 'both'
>>> p[2].style = 'both'
>>> p.close()

5.22.5 Using Custom Color Functions

The following code plots a saddle and color it by the magnitude of its gradient:

>>> fz = x**2-y**2
>>> Fx, Fy, Fz = fz.diff(x), fz.diff(y), 0
>>> p[1] = fz, 'style=solid'
>>> p[1].color = (Fx**2 + Fy**2 + Fz**2)**(0.5)

The coloring algorithm works like this:

1. Evaluate the color function(s) across the curve or surface.
2. Find the minimum and maximum value of each component.
3. Scale each component to the color gradient.

5.22. Pyglet Plotting Module 1103

SymPy Documentation, Release 1.3

When not specified explicitly, the default color gradient is f(0.0)=(0.4,0.4,0.4) ->
f(1.0)=(0.9,0.9,0.9). In our case, everything is gray-scale because we have applied the de-
fault color gradient uniformly for each color component. When defining a color scheme in
this way, you might want to supply a color gradient as well:

>>> p[1].color = (Fx**2 + Fy**2 + Fz**2)**(0.5), (0.1,0.1,0.9), (0.9,0.1,0.1)

Here’s a color gradient with four steps:

>>> gradient = [ 0.0, (0.1,0.1,0.9), 0.3, (0.1,0.9,0.1),

... 0.7, (0.9,0.9,0.1), 1.0, (1.0,0.0,0.0) ]
>>> p[1].color = (Fx**2 + Fy**2 + Fz**2)**(0.5), gradient

The other way to specify a color scheme is to give a separate function for each component r,
g, b. With this syntax, the default color scheme is defined:

>>> p[1].color = z,y,x, (0.4,0.4,0.4), (0.9,0.9,0.9)

This maps z->red, y->green, and x->blue. In some cases, you might prefer to use the following
alternative syntax:

>>> p[1].color = z,(0.4,0.9), y,(0.4,0.9), x,(0.4,0.9)

You can still use multi-step gradients with three-function color schemes.

5.22.6 Plotting Geometric Entities

The plotting module is capable of plotting some 2D geometric entities like line, circle and
ellipse. The following example plots a circle and a tangent line at a random point on the
ellipse.

In [1]: p = Plot(axes='label_axes=True')

In [2]: c = Circle(Point(0,0), 1)

In [3]: t = c.tangent_line(c.random_point())

In [4]: p[0] = c

In [5]: p[1] = t

Plotting polygons (Polygon, RegularPolygon, Triangle) are not supported directly. However a
polygon can be plotted through a loop as follows.

In [6]: p = Plot(axes='label_axes=True')

In [7]: t = RegularPolygon(Point(0,0), 1, 5)

In [8]: for i in range(len(t.sides)):

....: p[i] = t.sides[i]

1104 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.23 Assumptions Module

5.23.1 Contents

Ask

Module for querying SymPy objects about assumptions.

class sympy.assumptions.ask.AssumptionKeys
This class contains all the supported keys by ask.
algebraic
Algebraic number predicate.
Q.algebraic(x) is true iff x belongs to the set of algebraic numbers. x is algebraic
if there is some polynomial in p(x)\in \mathbb\{Q\}[x] such that p(x) = 0.

References

[R1]

Examples

>>> from sympy import ask, Q, sqrt, I, pi

>>> ask(Q.algebraic(sqrt(2)))
True
>>> ask(Q.algebraic(I))
True
>>> ask(Q.algebraic(pi))
False

antihermitian
Antihermitian predicate.
Q.antihermitian(x) is true iff x belongs to the field of antihermitian operators, i.e.,
operators in the form x*I, where x is Hermitian.

References

[R2]
bounded
See documentation of Q.finite.
commutative
Commutative predicate.
ask(Q.commutative(x)) is true iff x commutes with any other object with respect
to multiplication operation.
complex
Complex number predicate.

5.23. Assumptions Module 1105

SymPy Documentation, Release 1.3

Q.complex(x) is true iff x belongs to the set of complex numbers. Note that every
complex number is finite.

References

[R3]

Examples

>>> from sympy import Q, Symbol, ask, I, oo

>>> x = Symbol('x')
>>> ask(Q.complex(0))
True
>>> ask(Q.complex(2 + 3*I))
True
>>> ask(Q.complex(oo))
False

complex_elements
Complex elements matrix predicate.
Q.complex_elements(x) is true iff all the elements of x are complex numbers.

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.complex(X[1, 2]), Q.complex_elements(X))
True
>>> ask(Q.complex_elements(X), Q.integer_elements(X))
True

composite
Composite number predicate.
ask(Q.composite(x)) is true iff x is a positive integer and has at least one positive
divisor other than 1 and the number itself.

Examples

>>> from sympy import Q, ask

>>> ask(Q.composite(0))
False
>>> ask(Q.composite(1))
False
>>> ask(Q.composite(2))
False
>>> ask(Q.composite(20))
True

1106 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

diagonal
Diagonal matrix predicate.
Q.diagonal(x) is true iff x is a diagonal matrix. A diagonal matrix is a matrix in
which the entries outside the main diagonal are all zero.

References

[R4]

Examples

>>> from sympy import Q, ask, MatrixSymbol, ZeroMatrix

>>> X = MatrixSymbol('X', 2, 2)
>>> ask(Q.diagonal(ZeroMatrix(3, 3)))
True
>>> ask(Q.diagonal(X), Q.lower_triangular(X) &
... Q.upper_triangular(X))
True

even
Even number predicate.
ask(Q.even(x)) is true iff x belongs to the set of even integers.

Examples

>>> from sympy import Q, ask, pi

>>> ask(Q.even(0))
True
>>> ask(Q.even(2))
True
>>> ask(Q.even(3))
False
>>> ask(Q.even(pi))
False

extended_real
Extended real predicate.
Q.extended_real(x) is true iff x is a real number or {−∞, ∞}.
See documentation of Q.real for more information about related facts.

Examples

>>> from sympy import ask, Q, oo, I

>>> ask(Q.extended_real(1))
True
>>> ask(Q.extended_real(I))
False
>>> ask(Q.extended_real(oo))
True

5.23. Assumptions Module 1107

SymPy Documentation, Release 1.3

finite
Finite predicate.
Q.finite(x) is true if x is neither an infinity nor a NaN. In other words, ask(Q.
finite(x)) is true for all x having a bounded absolute value.

References

[R5]

Examples

>>> from sympy import Q, ask, Symbol, S, oo, I

>>> x = Symbol('x')
>>> ask(Q.finite(S.NaN))
False
>>> ask(Q.finite(oo))
False
>>> ask(Q.finite(1))
True
>>> ask(Q.finite(2 + 3*I))
True

fullrank
Fullrank matrix predicate.
Q.fullrank(x) is true iff x is a full rank matrix. A matrix is full rank if all rows and
columns of the matrix are linearly independent. A square matrix is full rank iff its
determinant is nonzero.

Examples

>>> from sympy import Q, ask, MatrixSymbol, ZeroMatrix, Identity

>>> X = MatrixSymbol('X', 2, 2)
>>> ask(Q.fullrank(X.T), Q.fullrank(X))
True
>>> ask(Q.fullrank(ZeroMatrix(3, 3)))
False
>>> ask(Q.fullrank(Identity(3)))
True

hermitian
Hermitian predicate.
ask(Q.hermitian(x)) is true iff x belongs to the set of Hermitian operators.

References

[R6]
imaginary
Imaginary number predicate.

1108 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Q.imaginary(x) is true iff x can be written as a real number multiplied by the imag-

inary unit I. Please note that 0 is not considered to be an imaginary number.

References

[R7]

Examples

>>> from sympy import Q, ask, I

>>> ask(Q.imaginary(3*I))
True
>>> ask(Q.imaginary(2 + 3*I))
False
>>> ask(Q.imaginary(0))
False

infinite
Infinite number predicate.
Q.infinite(x) is true iff the absolute value of x is infinity.
infinitesimal
See documentation of Q.zero.
infinity
See documentation of Q.infinite.
integer
Integer predicate.
Q.integer(x) is true iff x belongs to the set of integer numbers.

References

[R8]

Examples

>>> from sympy import Q, ask, S

>>> ask(Q.integer(5))
True
>>> ask(Q.integer(S(1)/2))
False

integer_elements
Integer elements matrix predicate.
Q.integer_elements(x) is true iff all the elements of x are integers.

5.23. Assumptions Module 1109

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.integer(X[1, 2]), Q.integer_elements(X))
True

invertible
Invertible matrix predicate.
Q.invertible(x) is true iff x is an invertible matrix. A square matrix is called in-
vertible only if its determinant is 0.

References

[R9]

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('Y', 2, 3)
>>> Z = MatrixSymbol('Z', 2, 2)
>>> ask(Q.invertible(X*Y), Q.invertible(X))
False
>>> ask(Q.invertible(X*Z), Q.invertible(X) & Q.invertible(Z))
True
>>> ask(Q.invertible(X), Q.fullrank(X) & Q.square(X))
True

irrational
Irrational number predicate.
Q.irrational(x) is true iff x is any real number that cannot be expressed as a ratio
of integers.

References

[R10]

Examples

>>> from sympy import ask, Q, pi, S, I

>>> ask(Q.irrational(0))
False
>>> ask(Q.irrational(S(1)/2))
False
>>> ask(Q.irrational(pi))
True
>>> ask(Q.irrational(I))
False

1110 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

is_true
Generic predicate.
ask(Q.is_true(x)) is true iff x is true. This only makes sense if x is a predicate.

Examples

>>> from sympy import ask, Q, symbols

>>> x = symbols('x')
>>> ask(Q.is_true(True))
True

lower_triangular
Lower triangular matrix predicate.
A matrix M is called lower triangular matrix if aij = 0 for i > j.

References

[R11]

Examples

>>> from sympy import Q, ask, ZeroMatrix, Identity

>>> ask(Q.lower_triangular(Identity(3)))
True
>>> ask(Q.lower_triangular(ZeroMatrix(3, 3)))
True

negative
Negative number predicate.
Q.negative(x) is true iff x is a real number and x < 0, that is, it is in the interval
(−∞, 0). Note in particular that negative infinity is not negative.
A few important facts about negative numbers:
• Note that Q.nonnegative and ~Q.negative are not the same thing. ~Q.
negative(x) simply means that x is not negative, whereas Q.nonnegative(x)
means that x is real and not negative, i.e., Q.nonnegative(x) is logically equiv-
alent to Q.zero(x) | Q.positive(x). So for example, ~Q.negative(I) is true,
whereas Q.nonnegative(I) is false.
• See the documentation of Q.real for more information about related facts.

Examples

>>> from sympy import Q, ask, symbols, I

>>> x = symbols('x')
>>> ask(Q.negative(x), Q.real(x) & ~Q.positive(x) & ~Q.zero(x))
True
>>> ask(Q.negative(-1))
(continues on next page)

5.23. Assumptions Module 1111

SymPy Documentation, Release 1.3

(continued from previous page)

True
>>> ask(Q.nonnegative(I))
False
>>> ask(~Q.negative(I))
True

nonnegative
Nonnegative real number predicate.
ask(Q.nonnegative(x)) is true iff x belongs to the set of positive numbers including
zero.
• Note that Q.nonnegative and ~Q.negative are not the same thing. ~Q.
negative(x) simply means that x is not negative, whereas Q.nonnegative(x)
means that x is real and not negative, i.e., Q.nonnegative(x) is logically equiv-
alent to Q.zero(x) | Q.positive(x). So for example, ~Q.negative(I) is true,
whereas Q.nonnegative(I) is false.

Examples

>>> from sympy import Q, ask, I

>>> ask(Q.nonnegative(1))
True
>>> ask(Q.nonnegative(0))
True
>>> ask(Q.nonnegative(-1))
False
>>> ask(Q.nonnegative(I))
False
>>> ask(Q.nonnegative(-I))
False

nonpositive
Nonpositive real number predicate.
ask(Q.nonpositive(x)) is true iff x belongs to the set of negative numbers includ-
ing zero.
• Note that Q.nonpositive and ~Q.positive are not the same thing. ~Q.
positive(x) simply means that x is not positive, whereas Q.nonpositive(x)
means that x is real and not positive, i.e., Q.nonpositive(x) is logically equiva-
lent to Q.negative(x)|Q.zero(x). So for example, ~Q.positive(I) is true, whereas
Q.nonpositive(I) is false.

Examples

>>> from sympy import Q, ask, I

>>> ask(Q.nonpositive(-1))
True
>>> ask(Q.nonpositive(0))
True
>>> ask(Q.nonpositive(1))
False
(continues on next page)

1112 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> ask(Q.nonpositive(I))
False
>>> ask(Q.nonpositive(-I))
False

nonzero
Nonzero real number predicate.
ask(Q.nonzero(x)) is true iff x is real and x is not zero. Note in particular that
Q.nonzero(x) is false if x is not real. Use ~Q.zero(x) if you want the negation of
being zero without any real assumptions.
A few important facts about nonzero numbers:
• Q.nonzero is logically equivalent to Q.positive | Q.negative.
• See the documentation of Q.real for more information about related facts.

Examples

>>> from sympy import Q, ask, symbols, I, oo

>>> x = symbols('x')
>>> print(ask(Q.nonzero(x), ~Q.zero(x)))
None
>>> ask(Q.nonzero(x), Q.positive(x))
True
>>> ask(Q.nonzero(x), Q.zero(x))
False
>>> ask(Q.nonzero(0))
False
>>> ask(Q.nonzero(I))
False
>>> ask(~Q.zero(I))
True
>>> ask(Q.nonzero(oo)) #doctest: +SKIP
False

normal
Normal matrix predicate.
A matrix is normal if it commutes with its conjugate transpose.

References

[R12]

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.normal(X), Q.unitary(X))
True

5.23. Assumptions Module 1113

SymPy Documentation, Release 1.3

odd
Odd number predicate.
ask(Q.odd(x)) is true iff x belongs to the set of odd numbers.

Examples

>>> from sympy import Q, ask, pi

>>> ask(Q.odd(0))
False
>>> ask(Q.odd(2))
False
>>> ask(Q.odd(3))
True
>>> ask(Q.odd(pi))
False

orthogonal
Orthogonal matrix predicate.
Q.orthogonal(x) is true iff x is an orthogonal matrix. A square matrix M is an or-
thogonal matrix if it satisfies M^TM = MM^T = I where M^T is the transpose matrix of
M and I is an identity matrix. Note that an orthogonal matrix is necessarily invertible.

References

[R13]

Examples

>>> from sympy import Q, ask, MatrixSymbol, Identity

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('Y', 2, 3)
>>> Z = MatrixSymbol('Z', 2, 2)
>>> ask(Q.orthogonal(Y))
False
>>> ask(Q.orthogonal(X*Z*X), Q.orthogonal(X) & Q.orthogonal(Z))
True
>>> ask(Q.orthogonal(Identity(3)))
True
>>> ask(Q.invertible(X), Q.orthogonal(X))
True

positive
Positive real number predicate.
Q.positive(x) is true iff x is real and x > 0, that is if x is in the interval (0, ∞). In
particular, infinity is not positive.
A few important facts about positive numbers:
• Note that Q.nonpositive and ~Q.positive are not the same thing. ~Q.
positive(x) simply means that x is not positive, whereas Q.nonpositive(x)

1114 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

means that x is real and not positive, i.e., Q.nonpositive(x) is logically equiva-
lent to Q.negative(x)|Q.zero(x). So for example, ~Q.positive(I) is true, whereas
Q.nonpositive(I) is false.
• See the documentation of Q.real for more information about related facts.

Examples

>>> from sympy import Q, ask, symbols, I

>>> x = symbols('x')
>>> ask(Q.positive(x), Q.real(x) & ~Q.negative(x) & ~Q.zero(x))
True
>>> ask(Q.positive(1))
True
>>> ask(Q.nonpositive(I))
False
>>> ask(~Q.positive(I))
True

positive_definite
Positive definite matrix predicate.
If M is a :math:n \times n symmetric real matrix, it is said to be positive definite if
Z T M Z is positive for every non-zero column vector Z of n real numbers.

References

[R14]

Examples

>>> from sympy import Q, ask, MatrixSymbol, Identity

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('Y', 2, 3)
>>> Z = MatrixSymbol('Z', 2, 2)
>>> ask(Q.positive_definite(Y))
False
>>> ask(Q.positive_definite(Identity(3)))
True
>>> ask(Q.positive_definite(X + Z), Q.positive_definite(X) &
... Q.positive_definite(Z))
True

prime
Prime number predicate.
ask(Q.prime(x)) is true iff x is a natural number greater than 1 that has no positive
divisors other than 1 and the number itself.

5.23. Assumptions Module 1115

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Q, ask

>>> ask(Q.prime(0))
False
>>> ask(Q.prime(1))
False
>>> ask(Q.prime(2))
True
>>> ask(Q.prime(20))
False
>>> ask(Q.prime(-3))
False

rational
Rational number predicate.
Q.rational(x) is true iff x belongs to the set of rational numbers.

References

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

Examples

>>> from sympy import ask, Q, pi, S

>>> ask(Q.rational(0))
True
>>> ask(Q.rational(S(1)/2))
True
>>> ask(Q.rational(pi))
False

real
Real number predicate.
Q.real(x) is true iff x is a real number, i.e., it is in the interval (−∞, ∞). Note that, in
particular the infinities are not real. Use Q.extended_real if you want to consider
those as well.
A few important facts about reals:
• Every real number is positive, negative, or zero. Furthermore, because these
sets are pairwise disjoint, each real number is exactly one of those three.
• Every real number is also complex.
• Every real number is finite.
• Every real number is either rational or irrational.
• Every real number is either algebraic or transcendental.
• The facts Q.negative, Q.zero, Q.positive, Q.nonnegative, Q.nonpositive, Q.
nonzero, Q.integer, Q.rational, and Q.irrational all imply Q.real, as do all
facts that imply those facts.

1116 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• The facts Q.algebraic, and Q.transcendental do not imply Q.real; they imply
Q.complex. An algebraic or transcendental number may or may not be real.
• The “non” facts (i.e., Q.nonnegative, Q.nonzero, Q.nonpositive and Q.
noninteger) are not equivalent to not the fact, but rather, not the fact and
Q.real. For example, Q.nonnegative means ~Q.negative & Q.real. So for
example, I is not nonnegative, nonzero, or nonpositive.

References

[R15]

Examples

>>> from sympy import Q, ask, symbols

>>> x = symbols('x')
>>> ask(Q.real(x), Q.positive(x))
True
>>> ask(Q.real(0))
True

real_elements
Real elements matrix predicate.
Q.real_elements(x) is true iff all the elements of x are real numbers.

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.real(X[1, 2]), Q.real_elements(X))
True

singular
Singular matrix predicate.
A matrix is singular iff the value of its determinant is 0.

References

[R16]

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.singular(X), Q.invertible(X))
False
>>> ask(Q.singular(X), ~Q.invertible(X))
True

5.23. Assumptions Module 1117

SymPy Documentation, Release 1.3

square
Square matrix predicate.
Q.square(x) is true iff x is a square matrix. A square matrix is a matrix with the
same number of rows and columns.

References

[R17]

Examples

>>> from sympy import Q, ask, MatrixSymbol, ZeroMatrix, Identity

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('X', 2, 3)
>>> ask(Q.square(X))
True
>>> ask(Q.square(Y))
False
>>> ask(Q.square(ZeroMatrix(3, 3)))
True
>>> ask(Q.square(Identity(3)))
True

symmetric
Symmetric matrix predicate.
Q.symmetric(x) is true iff x is a square matrix and is equal to its transpose. Every
square diagonal matrix is a symmetric matrix.

References

[R18]

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('Y', 2, 3)
>>> Z = MatrixSymbol('Z', 2, 2)
>>> ask(Q.symmetric(X*Z), Q.symmetric(X) & Q.symmetric(Z))
True
>>> ask(Q.symmetric(X + Z), Q.symmetric(X) & Q.symmetric(Z))
True
>>> ask(Q.symmetric(Y))
False

transcendental
Transcedental number predicate.
Q.transcendental(x) is true iff x belongs to the set of transcendental numbers. A
transcendental number is a real or complex number that is not algebraic.

1118 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

triangular
Triangular matrix predicate.
Q.triangular(X) is true if X is one that is either lower triangular or upper triangular.

References

[R19]

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.triangular(X), Q.upper_triangular(X))
True
>>> ask(Q.triangular(X), Q.lower_triangular(X))
True

unit_triangular
Unit triangular matrix predicate.
A unit triangular matrix is a triangular matrix with 1s on the diagonal.

Examples

>>> from sympy import Q, ask, MatrixSymbol

>>> X = MatrixSymbol('X', 4, 4)
>>> ask(Q.triangular(X), Q.unit_triangular(X))
True

unitary
Unitary matrix predicate.
Q.unitary(x) is true iff x is a unitary matrix. Unitary matrix is an analogue to
orthogonal matrix. A square matrix M with complex elements is unitary if :math:M^TM
= MM^T= I where :math:M^T is the conjugate transpose matrix of M.

References

[R20]

Examples

>>> from sympy import Q, ask, MatrixSymbol, Identity

>>> X = MatrixSymbol('X', 2, 2)
>>> Y = MatrixSymbol('Y', 2, 3)
>>> Z = MatrixSymbol('Z', 2, 2)
>>> ask(Q.unitary(Y))
False
>>> ask(Q.unitary(X*Z*X), Q.unitary(X) & Q.unitary(Z))
(continues on next page)

5.23. Assumptions Module 1119

SymPy Documentation, Release 1.3

(continued from previous page)

True
>>> ask(Q.unitary(Identity(3)))
True

upper_triangular
Upper triangular matrix predicate.
A matrix M is called upper triangular matrix if Mij = 0 for i < j.

References

[R21]

Examples

>>> from sympy import Q, ask, ZeroMatrix, Identity

>>> ask(Q.upper_triangular(Identity(3)))
True
>>> ask(Q.upper_triangular(ZeroMatrix(3, 3)))
True

zero
Zero number predicate.
ask(Q.zero(x)) is true iff the value of x is zero.

Examples

>>> from sympy import ask, Q, oo, symbols

>>> x, y = symbols('x, y')
>>> ask(Q.zero(0))
True
>>> ask(Q.zero(1/oo))
True
>>> ask(Q.zero(0*oo))
False
>>> ask(Q.zero(1))
False
>>> ask(Q.zero(x*y), Q.zero(x) | Q.zero(y))
True

sympy.assumptions.ask.ask(proposition, assumptions=True, context={})

Method for inferring properties about objects.
Syntax
• ask(proposition)
• ask(proposition, assumptions)
where proposition is any boolean expression

1120 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import ask, Q, pi

>>> from sympy.abc import x, y
>>> ask(Q.rational(pi))
False
>>> ask(Q.even(x*y), Q.even(x) & Q.integer(y))
True
>>> ask(Q.prime(4*x), Q.integer(x))
False

Remarks Relations in assumptions are not implemented (yet), so the following will not
give a meaningful result.

>>> ask(Q.positive(x), Q.is_true(x > 0)) # doctest: +SKIP

It is however a work in progress.

sympy.assumptions.ask.ask_full_inference(proposition, assumptions,
known_facts_cnf)
Method for inferring properties about objects.
sympy.assumptions.ask.compute_known_facts(known_facts, known_facts_keys)
Compute the various forms of knowledge compilation used by the assumptions system.
This function is typically applied to the results of the get_known_facts and
get_known_facts_keys functions defined at the bottom of this file.
sympy.assumptions.ask.register_handler(key, handler)
Register a handler in the ask system. key must be a string and handler a class inheriting
from AskHandler:

>>> from sympy.assumptions import register_handler, ask, Q

>>> from sympy.assumptions.handlers import AskHandler
>>> class MersenneHandler(AskHandler):
... # Mersenne numbers are in the form 2**n - 1, n integer
... @staticmethod
... def Integer(expr, assumptions):
... from sympy import log
... return ask(Q.integer(log(expr + 1, 2)))
>>> register_handler('mersenne', MersenneHandler)
>>> ask(Q.mersenne(7))
True

sympy.assumptions.ask.remove_handler(key, handler)
Removes a handler from the ask system. Same syntax as register_handler

Assume

class sympy.assumptions.assume.AppliedPredicate
The class of expressions resulting from applying a Predicate.

5.23. Assumptions Module 1121

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Q, Symbol

>>> x = Symbol('x')
>>> Q.integer(x)
Q.integer(x)
>>> type(Q.integer(x))
<class 'sympy.assumptions.assume.AppliedPredicate'>

arg
Return the expression used by this assumption.

Examples

>>> from sympy import Q, Symbol

>>> x = Symbol('x')
>>> a = Q.integer(x + 1)
>>> a.arg
x + 1

class sympy.assumptions.assume.AssumptionsContext
Set representing assumptions.
This is used to represent global assumptions, but you can also use this class to create
your own local assumptions contexts. It is basically a thin wrapper to Python’s set, so
see its documentation for advanced usage.

Examples

>>> from sympy import AppliedPredicate, Q

>>> from sympy.assumptions.assume import global_assumptions
>>> global_assumptions
AssumptionsContext()
>>> from sympy.abc import x
>>> global_assumptions.add(Q.real(x))
>>> global_assumptions
AssumptionsContext({Q.real(x)})
>>> global_assumptions.remove(Q.real(x))
>>> global_assumptions
AssumptionsContext()
>>> global_assumptions.clear()

add(*assumptions)
Add an assumption.
class sympy.assumptions.assume.Predicate
A predicate is a function that returns a boolean value.
Predicates merely wrap their argument and remain unevaluated:
>>> from sympy import Q, ask
>>> type(Q.prime)
<class 'sympy.assumptions.assume.Predicate'>
>>> Q.prime.name
(continues on next page)

1122 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

'prime'
>>> Q.prime(7)
Q.prime(7)
>>> _.func.name
'prime'

To obtain the truth value of an expression containing predicates, use the function ask:
>>> ask(Q.prime(7))
True

The tautological predicate Q.is_true can be used to wrap other objects:

>>> from sympy.abc import x
>>> Q.is_true(x > 1)
Q.is_true(x > 1)

eval(expr, assumptions=True)
Evaluate self(expr) under the given assumptions.
This uses only direct resolution methods, not logical inference.
sympy.assumptions.assume.assuming(*assumptions)
Context manager for assumptions

Examples

>>> from sympy.assumptions import assuming, Q, ask

>>> from sympy.abc import x, y

>>> print(ask(Q.integer(x + y)))

None

>>> with assuming(Q.integer(x), Q.integer(y)):

... print(ask(Q.integer(x + y)))
True

Refine

sympy.assumptions.refine.refine(expr, assumptions=True)
Simplify an expression using assumptions.
Gives the form of expr that would be obtained if symbols in it were replaced by explicit
numerical expressions satisfying the assumptions.

Examples

>>> from sympy import refine, sqrt, Q

>>> from sympy.abc import x
>>> refine(sqrt(x**2), Q.real(x))
Abs(x)
(continues on next page)

5.23. Assumptions Module 1123

SymPy Documentation, Release 1.3

(continued from previous page)

>>> refine(sqrt(x**2), Q.positive(x))
x

sympy.assumptions.refine.refine_Pow(expr, assumptions)
Handler for instances of Pow.

>>> from sympy import Symbol, Q

>>> from sympy.assumptions.refine import refine_Pow
>>> from sympy.abc import x,y,z
>>> refine_Pow((-1)**x, Q.real(x))
>>> refine_Pow((-1)**x, Q.even(x))
1
>>> refine_Pow((-1)**x, Q.odd(x))
-1

For powers of -1, even parts of the exponent can be simplified:

>>> refine_Pow((-1)**(x+y), Q.even(x))

(-1)**y
>>> refine_Pow((-1)**(x+y+z), Q.odd(x) & Q.odd(z))
(-1)**y
>>> refine_Pow((-1)**(x+y+2), Q.odd(x))
(-1)**(y + 1)
>>> refine_Pow((-1)**(x+3), True)
(-1)**(x + 1)

sympy.assumptions.refine.refine_Relational(expr, assumptions)
Handler for Relational

>>> from sympy.assumptions.refine import refine_Relational

>>> from sympy.assumptions.ask import Q
>>> from sympy.abc import x
>>> refine_Relational(x<0, ~Q.is_true(x<0))
False

sympy.assumptions.refine.refine_abs(expr, assumptions)
Handler for the absolute value.

Examples

>>> from sympy import Symbol, Q, refine, Abs

>>> from sympy.assumptions.refine import refine_abs
>>> from sympy.abc import x
>>> refine_abs(Abs(x), Q.real(x))
>>> refine_abs(Abs(x), Q.positive(x))
x
>>> refine_abs(Abs(x), Q.negative(x))
-x

sympy.assumptions.refine.refine_atan2(expr, assumptions)
Handler for the atan2 function

1124 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Symbol, Q, refine, atan2

>>> from sympy.assumptions.refine import refine_atan2
>>> from sympy.abc import x, y
>>> refine_atan2(atan2(y,x), Q.real(y) & Q.positive(x))
atan(y/x)
>>> refine_atan2(atan2(y,x), Q.negative(y) & Q.negative(x))
atan(y/x) - pi
>>> refine_atan2(atan2(y,x), Q.positive(y) & Q.negative(x))
atan(y/x) + pi
>>> refine_atan2(atan2(y,x), Q.zero(y) & Q.negative(x))
pi
>>> refine_atan2(atan2(y,x), Q.positive(y) & Q.zero(x))
pi/2
>>> refine_atan2(atan2(y,x), Q.negative(y) & Q.zero(x))
-pi/2
>>> refine_atan2(atan2(y,x), Q.zero(y) & Q.zero(x))
nan

Handlers

Contents

Calculus

This module contains query handlers responsible for calculus queries: infinitesimal, finite,
etc.
class sympy.assumptions.handlers.calculus.AskFiniteHandler
Handler for key ‘finite’.
Test that an expression is bounded respect to all its variables.
Examples of usage:

>>> from sympy import Symbol, Q

>>> from sympy.assumptions.handlers.calculus import AskFiniteHandler
>>> from sympy.abc import x
>>> a = AskFiniteHandler()
>>> a.Symbol(x, Q.positive(x)) == None
True
>>> a.Symbol(x, Q.finite(x))
True

static Add(expr, assumptions)

Return True if expr is bounded, False if not and None if unknown.
Truth Table:

5.23. Assumptions Module 1125

SymPy Documentation, Release 1.3

B U ?
‘+’ ‘-‘ ‘x’ ‘+’ ‘-‘ ‘x’
B B U ?
U ‘+’ U ? ? U ? ?
‘-‘ ? U ? ? U ?
‘x’ ? ?
? ?

• ‘B’ = Bounded
• ‘U’ = Unbounded
• ‘?’ = unknown boundedness
• ‘+’ = positive sign
• ‘-‘ = negative sign
• ‘x’ = sign unknown

• All Bounded -> True

• 1 Unbounded and the rest Bounded -> False
• >1 Unbounded, all with same known sign -> False
• Any Unknown and unknown sign -> None
• Else -> None
When the signs are not the same you can have an undefined result as in oo -
oo, hence ‘bounded’ is also undefined.

static Mul(expr, assumptions)

Return True if expr is bounded, False if not and None if unknown.
Truth Table:

B U ?
s /s
B B U ?
U U U ?
? ?

• B = Bounded
• U = Unbounded
• ? = unknown boundedness
• s = signed (hence nonzero)
• /s = not signed

1126 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

static Pow(expr, assumptions)

Unbounded ** NonZero -> Unbounded Bounded ** Bounded -> Bounded Abs()<=1
** Positive -> Bounded Abs()>=1 ** Negative -> Bounded Otherwise unknown
static Symbol(expr, assumptions)
Handles Symbol.

Examples

>>> from sympy import Symbol, Q

>>> from sympy.assumptions.handlers.calculus import AskFiniteHandler
>>> from sympy.abc import x
>>> a = AskFiniteHandler()
>>> a.Symbol(x, Q.positive(x)) == None
True
>>> a.Symbol(x, Q.finite(x))
True

nTheory

Handlers for keys related to number theory: prime, even, odd, etc.
class sympy.assumptions.handlers.ntheory.AskOddHandler
Handler for key ‘odd’ Test that an expression represents an odd number
class sympy.assumptions.handlers.ntheory.AskPrimeHandler
Handler for key ‘prime’ Test that an expression represents a prime number. When the
expression is a number the result, when True, is subject to the limitations of isprime()
which is used to return the result.
static Pow(expr, assumptions)
Integer**Integer -> !Prime

Order

AskHandlers related to order relations: positive, negative, etc.

class sympy.assumptions.handlers.order.AskNegativeHandler
This is called by ask() when key=’negative’
Test that an expression is less (strict) than zero.

Examples

>>> from sympy import ask, Q, pi

>>> ask(Q.negative(pi+1)) # this calls AskNegativeHandler.Add
False
>>> ask(Q.negative(pi**2)) # this calls AskNegativeHandler.Pow
False

static Add(expr, assumptions)

Positive + Positive -> Positive, Negative + Negative -> Negative

5.23. Assumptions Module 1127

SymPy Documentation, Release 1.3

static Pow(expr, assumptions)

Real ** Even -> NonNegative Real ** Odd -> same_as_base NonNegative ** Positive
-> NonNegative
class sympy.assumptions.handlers.order.AskNonZeroHandler
Handler for key ‘zero’ Test that an expression is not identically zero
class sympy.assumptions.handlers.order.AskPositiveHandler
Handler for key ‘positive’ Test that an expression is greater (strict) than zero

Sets

Handlers for predicates related to set membership: integer, rational, etc.

class sympy.assumptions.handlers.sets.AskAlgebraicHandler
Handler for Q.algebraic key.
class sympy.assumptions.handlers.sets.AskAntiHermitianHandler
Handler for Q.antihermitian Test that an expression belongs to the field of anti-Hermitian
operators, that is, operators in the form x*I, where x is Hermitian
static Add(expr, assumptions)
Antihermitian + Antihermitian -> Antihermitian Antihermitian + !Antihermitian ->
!Antihermitian
static Mul(expr, assumptions)
As long as there is at most only one noncommutative term: Hermitian*Hermitian
-> !Antihermitian Hermitian*Antihermitian -> Antihermitian Antihermi-
tian*Antihermitian -> !Antihermitian
static Pow(expr, assumptions)
Hermitian**Integer -> !Antihermitian Antihermitian**Even -> !Antihermitian Anti-
hermitian**Odd -> Antihermitian
class sympy.assumptions.handlers.sets.AskComplexHandler
Handler for Q.complex Test that an expression belongs to the field of complex numbers
class sympy.assumptions.handlers.sets.AskExtendedRealHandler
Handler for Q.extended_real Test that an expression belongs to the field of extended real
numbers, that is real numbers union {Infinity, -Infinity}
class sympy.assumptions.handlers.sets.AskHermitianHandler
Handler for Q.hermitian Test that an expression belongs to the field of Hermitian oper-
ators
static Add(expr, assumptions)
Hermitian + Hermitian -> Hermitian Hermitian + !Hermitian -> !Hermitian
static Mul(expr, assumptions)
As long as there is at most only one noncommutative term: Hermitian*Hermitian ->
Hermitian Hermitian*Antihermitian -> !Hermitian Antihermitian*Antihermitian ->
Hermitian
static Pow(expr, assumptions)
Hermitian**Integer -> Hermitian
class sympy.assumptions.handlers.sets.AskImaginaryHandler
Handler for Q.imaginary Test that an expression belongs to the field of imaginary num-
bers, that is, numbers in the form x*I, where x is real

1128 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

static Add(expr, assumptions)

Imaginary + Imaginary -> Imaginary Imaginary + Complex -> ? Imaginary + Real
-> !Imaginary
static Mul(expr, assumptions)
Real*Imaginary -> Imaginary Imaginary*Imaginary -> Real
static Pow(expr, assumptions)
Imaginary**Odd -> Imaginary Imaginary**Even -> Real b**Imaginary -> !Imagi-
nary if exponent is an integer multiple of I*pi/log(b) Imaginary**Real -> ? Posi-
tive**Real -> Real Negative**Integer -> Real Negative**(Integer/2) -> Imaginary
Negative**Real -> not Imaginary if exponent is not Rational
class sympy.assumptions.handlers.sets.AskIntegerHandler
Handler for Q.integer Test that an expression belongs to the field of integer numbers
static Add(expr, assumptions)
Integer + Integer -> Integer Integer + !Integer -> !Integer !Integer + !Integer -> ?
static Mul(expr, assumptions)
Integer*Integer -> Integer Integer*Irrational -> !Integer Odd/Even -> !Integer In-
teger*Rational -> ?
static Pow(expr, assumptions)
Integer + Integer -> Integer Integer + !Integer -> !Integer !Integer + !Integer -> ?
class sympy.assumptions.handlers.sets.AskRationalHandler
Handler for Q.rational Test that an expression belongs to the field of rational numbers
static Add(expr, assumptions)
Rational + Rational -> Rational Rational + !Rational -> !Rational !Rational + !Ra-
tional -> ?
static Mul(expr, assumptions)
Rational + Rational -> Rational Rational + !Rational -> !Rational !Rational + !Ra-
tional -> ?
static Pow(expr, assumptions)
Rational ** Integer -> Rational Irrational ** Rational -> Irrational Rational ** Irra-
tional -> ?
class sympy.assumptions.handlers.sets.AskRealHandler
Handler for Q.real Test that an expression belongs to the field of real numbers
static Add(expr, assumptions)
Real + Real -> Real Real + (Complex & !Real) -> !Real
static Mul(expr, assumptions)
Real*Real -> Real Real*Imaginary -> !Real Imaginary*Imaginary -> Real
static Pow(expr, assumptions)
Real**Integer -> Real Positive**Real -> Real Real**(Integer/Even) -> Real if base is
nonnegative Real**(Integer/Odd) -> Real Imaginary**(Integer/Even) -> Real Imagi-
nary**(Integer/Odd) -> not Real Imaginary**Real -> ? since Real could be 0 (giving
real) or 1 (giving imaginary) b**Imaginary -> Real if log(b) is imaginary and b !=
0 and exponent != integer multiple of I*pi/log(b) Real**Real -> ? e.g. sqrt(-1) is
imaginary and sqrt(2) is not
Queries are used to ask information about expressions. Main method for this is ask():
sympy.assumptions.ask.ask(proposition, assumptions=True, context={})
Method for inferring properties about objects.

5.23. Assumptions Module 1129

SymPy Documentation, Release 1.3

Syntax
• ask(proposition)
• ask(proposition, assumptions)
where proposition is any boolean expression

Examples

>>> from sympy import ask, Q, pi

>>> from sympy.abc import x, y
>>> ask(Q.rational(pi))
False
>>> ask(Q.even(x*y), Q.even(x) & Q.integer(y))
True
>>> ask(Q.prime(4*x), Q.integer(x))
False

Remarks Relations in assumptions are not implemented (yet), so the following will not
give a meaningful result.

>>> ask(Q.positive(x), Q.is_true(x > 0)) # doctest: +SKIP

It is however a work in progress.

5.23.2 Querying

ask’s optional second argument should be a boolean expression involving assumptions about
objects in expr. Valid values include:
• Q.integer(x)
• Q.positive(x)
• Q.integer(x) & Q.positive(x)
• etc.
Q is an object holding known predicates.
See documentation for the logic module for a complete list of valid boolean expressions.
You can also define a context so you don’t have to pass that argument each time to function
ask(). This is done by using the assuming context manager from module sympy.assumptions.

>>> from sympy import *

>>> x = Symbol('x')
>>> y = Symbol('y')
>>> facts = Q.positive(x), Q.positive(y)
>>> with assuming(*facts):
... print(ask(Q.positive(2*x + y)))
True

1130 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.23.3 Design

Each time ask is called, the appropriate Handler for the current key is called. This is always
a subclass of sympy.assumptions.AskHandler. Its classmethods have the names of the classes
it supports. For example, a (simplified) AskHandler for the ask ‘positive’ would look like this:

class AskPositiveHandler(CommonHandler):

def Mul(self):
# return True if all argument's in self.expr.args are positive
...

def Add(self):
for arg in self.expr.args:
if not ask(arg, positive, self.assumptions):
break
else:
# if all argument's are positive
return True
...

The .Mul() method is called when self.expr is an instance of Mul, the Add method would be
called when self.expr is an instance of Add and so on.

5.23.4 Extensibility

You can define new queries or support new types by subclassing sympy.assumptions.AskHandler
and registering that handler for a particular key by calling register_handler:
sympy.assumptions.ask.register_handler(key, handler)
Register a handler in the ask system. key must be a string and handler a class inheriting
from AskHandler:

>>> from sympy.assumptions import register_handler, ask, Q

>>> from sympy.assumptions.handlers import AskHandler
>>> class MersenneHandler(AskHandler):
... # Mersenne numbers are in the form 2**n - 1, n integer
... @staticmethod
... def Integer(expr, assumptions):
... from sympy import log
... return ask(Q.integer(log(expr + 1, 2)))
>>> register_handler('mersenne', MersenneHandler)
>>> ask(Q.mersenne(7))
True

You can undo this operation by calling remove_handler.

sympy.assumptions.ask.remove_handler(key, handler)
Removes a handler from the ask system. Same syntax as register_handler
You can support new types1 by adding a handler to an existing key. In the following example,
we will create a new type MyType and extend the key ‘prime’ to accept this type (and return
True)
1 New type must inherit from Basic, otherwise an exception will be raised. This is a bug and should be fixed.

5.23. Assumptions Module 1131

SymPy Documentation, Release 1.3

>>> from sympy.core import Basic

>>> from sympy.assumptions import register_handler
>>> from sympy.assumptions.handlers import AskHandler
>>> class MyType(Basic):
... pass
>>> class MyAskHandler(AskHandler):
... @staticmethod
... def MyType(expr, assumptions):
... return True
>>> a = MyType()
>>> register_handler('prime', MyAskHandler)
>>> ask(Q.prime(a))
True

5.23.5 Performance improvements

On queries that involve symbolic coefficients, logical inference is used. Work on improving
satisfiable function (sympy.logic.inference.satisfiable) should result in notable speed improve-
ments.
Logic inference used in one ask could be used to speed up further queries, and current
system does not take advantage of this. For example, a truth maintenance system (http:
//en.wikipedia.org/wiki/Truth_maintenance_system) could be implemented.

5.23.6 Misc

You can find more examples in the in the form of test under directory
sympy/assumptions/tests/

5.24 Term rewriting

Term rewriting is a very general class of functionalities which are used to convert expres-
sions of one type in terms of expressions of different kind. For example expanding, com-
bining and converting expressions apply to term rewriting, and also simplification routines
can be included here. Currently SymPy has several functions and basic built-in methods for
performing various types of rewriting.

5.24.1 Expanding

The simplest rewrite rule is expanding expressions into a _sparse_ form. Expanding has sev-
eral flavors and include expanding complex valued expressions, arithmetic expand of prod-
ucts and powers but also expanding functions in terms of more general functions is possible.
Below are listed all currently available expand rules.
Expanding of arithmetic expressions involving products and powers:
>>> from sympy import *
>>> x, y, z = symbols('x,y,z')
>>> ((x + y)*(x - y)).expand(basic=True)
(continues on next page)

1132 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

x**2 - y**2
>>> ((x + y + z)**2).expand(basic=True)
x**2 + 2*x*y + 2*x*z + y**2 + 2*y*z + z**2

Arithmetic expand is done by default in expand() so the keyword basic can be omitted. How-
ever you can set basic=False to avoid this type of expand if you use rules described below.
This give complete control on what is done with the expression.
Another type of expand rule is expanding complex valued expressions and putting them into
a normal form. For this complex keyword is used. Note that it will always perform arithmetic
expand to obtain the desired normal form:
>>> (x + I*y).expand(complex=True)
re(x) + I*re(y) + I*im(x) - im(y)

>>> sin(x + I*y).expand(complex=True)

sin(re(x) - im(y))*cosh(re(y) + im(x)) + I*cos(re(x) - im(y))*sinh(re(y) + im(x))

Note also that the same behavior can be obtained by using as_real_imag() method. However
it will return a tuple containing the real part in the first place and the imaginary part in the
other. This can be also done in a two step process by using collect function:
>>> (x + I*y).as_real_imag()
(re(x) - im(y), re(y) + im(x))

>>> collect((x + I*y).expand(complex=True), I, evaluate=False)

{1: re(x) - im(y), I: re(y) + im(x)}

There is also possibility for expanding expressions in terms of expressions of different kind.
This is very general type of expanding and usually you would use rewrite() to do specific
type of rewrite:
>>> GoldenRatio.expand(func=True)
1/2 + sqrt(5)/2

5.24.2 Common Subexpression Detection and Collection

Before evaluating a large expression, it is often useful to identify common subexpressions,

collect them and evaluate them at once. This is implemented in the cse function. Examples:
>>> from sympy import cse, sqrt, sin, pprint
>>> from sympy.abc import x

>>> pprint(cse(sqrt(sin(x))), use_unicode=True)

⎛ ⎡ ________⎤⎞
⎝[], ⎣╲╱ sin(x) ⎦⎠

>>> pprint(cse(sqrt(sin(x)+5)*sqrt(sin(x)+4)), use_unicode=True)

⎛ ⎡ ________ ________⎤⎞
⎝[(x0 , sin(x))], ⎣╲╱ x0 + 4 ⋅╲╱ x0 + 5 ⎦⎠

>>> pprint(cse(sqrt(sin(x+1) + 5 + cos(y))*sqrt(sin(x+1) + 4 + cos(y))),

... use_unicode=True)
(continues on next page)

5.24. Term rewriting 1133

SymPy Documentation, Release 1.3

(continued from previous page)

⎛ ⎡ ________ ________⎤⎞
⎝[(x0 , sin(x + 1) + cos(y))], ⎣╲╱ x0 + 4 ⋅╲╱ x0 + 5 ⎦⎠

>>> pprint(cse((x-y)*(z-y) + sqrt((x-y)*(z-y))), use_unicode=True)

⎛ ⎡ ____ ⎤⎞
⎝[(x0 , -y), (x1 , (x + x0 )⋅(x0 + z))], ⎣╲╱ x1 + x1 ⎦⎠

Optimizations to be performed before and after common subexpressions elimination can be

passed in the‘‘optimizations‘‘ optional argument. A set of predefined basic optimizations can
be applied by passing optimizations='basic':

>>> pprint(cse((x-y)*(z-y) + sqrt((x-y)*(z-y)), optimizations='basic'),

... use_unicode=True)
⎛ ⎡ ____ ⎤⎞
⎝[(x0 , -(x - y)⋅(y - z))], ⎣╲╱ x0 + x0 ⎦⎠

However, these optimizations can be very slow for large expressions. Moreover, if speed is a
concern, one can pass the option order='none'. Order of terms will then be dependent on
hashing algorithm implementation, but speed will be greatly improved.
More information:
sympy.simplify.cse_main.cse(exprs, symbols=None, optimizations=None, postpro-
cess=None, order=’canonical’, ignore=())
Perform common subexpression elimination on an expression.
Parameters exprs : list of sympy expressions, or a single sympy expression
The expressions to reduce.
symbols : infinite iterator yielding unique Symbols
The symbols used to label the common subexpressions which are
pulled out. The numbered_symbols generator is useful. The default
is a stream of symbols of the form “x0”, “x1”, etc. This must be an
infinite iterator.
optimizations : list of (callable, callable) pairs
The (preprocessor, postprocessor) pairs of external optimization
functions. Optionally ‘basic’ can be passed for a set of predefined
basic optimizations. Such ‘basic’ optimizations were used by default
in old implementation, however they can be really slow on larger ex-
pressions. Now, no pre or post optimizations are made by default.
postprocess : a function which accepts the two return values of cse and
returns the desired form of output from cse, e.g. if you want the
replacements reversed the function might be the following lambda:
lambda r, e: return reversed(r), e
order : string, ‘none’ or ‘canonical’
The order by which Mul and Add arguments are processed. If set to
‘canonical’, arguments will be canonically ordered. If set to ‘none’,
ordering will be faster but dependent on expressions hashes, thus
machine dependent and variable. For large expressions where speed
is a concern, use the setting order=’none’.
ignore : iterable of Symbols

1134 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Substitutions containing any Symbol from ignore will be ignored.

Returns replacements : list of (Symbol, expression) pairs
All of the common subexpressions that were replaced. Subexpres-
sions earlier in this list might show up in subexpressions later in this
list.
reduced_exprs : list of sympy expressions
The reduced expressions with all of the replacements above.

Examples

>>> from sympy import cse, SparseMatrix

>>> from sympy.abc import x, y, z, w
>>> cse(((w + x + y + z)*(w + y + z))/(w + x)**3)
([(x0, y + z), (x1, w + x)], [(w + x0)*(x0 + x1)/x1**3])

Note that currently, y + z will not get substituted if -y - z is used.

>>> cse(((w + x + y + z)*(w - y - z))/(w + x)**3)
([(x0, w + x)], [(w - y - z)*(x0 + y + z)/x0**3])

List of expressions with recursive substitutions:

>>> m = SparseMatrix([x + y, x + y + z])
>>> cse([(x+y)**2, x + y + z, y + z, x + z + y, m])
([(x0, x + y), (x1, x0 + z)], [x0**2, x1, y + z, x1, Matrix([
[x0],
[x1]])])

Note: the type and mutability of input matrices is retained.

>>> isinstance(_[1][-1], SparseMatrix)
True

The user may disallow substitutions containing certain symbols:

>>> cse([y**2*(x + 1), 3*y**2*(x + 1)], ignore=(y,))
([(x0, x + 1)], [x0*y**2, 3*x0*y**2])

5.25 Series Module

The series module implements series expansions as a function and many related functions.

5.25.1 Contents

Series Expansions

Limits

The main purpose of this module is the computation of limits.

5.25. Series Module 1135

SymPy Documentation, Release 1.3

sympy.series.limits.limit(e, z, z0, dir=’+’)

Compute the limit of e(z) at the point z0.
z0 can be any expression, including oo and -oo.
For dir=”+-” it calculates the bi-directional limit; for dir=”+” (default) it calculates the
limit from the right (z->z0+) and for dir=”-” the limit from the left (z->z0-). For infinite
z0 (oo or -oo), the dir argument is determined from the direction of the infinity (i.e.,
dir=”-” for oo).

Notes

First we try some heuristics for easy and frequent cases like “x”, “1/x”, “x**2” and sim-
ilar, so that it’s fast. For all other cases, we use the Gruntz algorithm (see the gruntz()
function).

Examples

>>> from sympy import limit, sin, Symbol, oo

>>> from sympy.abc import x
>>> limit(sin(x)/x, x, 0)
1
>>> limit(1/x, x, 0) # default dir='+'
oo
>>> limit(1/x, x, 0, dir=”-”)
-oo
>>> limit(1/x, x, 0, dir='+-')
Traceback (most recent call last):
...
ValueError: The limit does not exist since left hand limit = -oo and right hand␣
,→limit = oo

>>> limit(1/x, x, oo)

0

class sympy.series.limits.Limit
Represents an unevaluated limit.

Examples

>>> from sympy import Limit, sin, Symbol

>>> from sympy.abc import x
>>> Limit(sin(x)/x, x, 0)
Limit(sin(x)/x, x, 0)
>>> Limit(1/x, x, 0, dir=”-”)
Limit(1/x, x, 0, dir='-')

doit(**hints)
Evaluates limit
As is explained above, the workhorse for limit computations is the function gruntz() which
implements Gruntz’ algorithm for computing limits.

1136 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The Gruntz Algorithm

This section explains the basics of the algorithm used for computing limits. Most of the time
the limit() function should just work. However it is still useful to keep in mind how it is
implemented in case something does not work as expected.
First we define an ordering on functions. Suppose f (x) and g(x) are two real-valued functions
such that limx→∞ f (x) = ∞ and similarly limx→∞ g(x) = ∞. We shall say that f (x) dominates
(x)a
g(x), written f (x) ≻ g(x), if for all a, b ∈ R>0 we have limx→∞ fg(x) b = ∞. We also say that f (x) and

g(x) are of the same comparability class if neither f (x) ≻ g(x) nor g(x) ≻ f (x) and shall denote
it as f (x) ≍ g(x).
Note that whenever a, b ∈ R>0 then af (x)b ≍ f (x), and we shall use this to extend the definition
of ≻ to all functions which tend to 0 or ±∞ as x → ∞. Thus we declare that f (x) ≍ 1/f (x) and
f (x) ≍ −f (x).
It is easy to show the following examples:
• ex ≻ xm
2
• ex ≻ emx
x m
• ee ≻ ex
• xm ≍ xn
1
• ex+ x ≍ ex+log x ≍ ex .
From the above definition, it is possible to prove the following property:
Suppose ω, g1 , g2 , . . . are functions of x, limx→∞ ω = 0 and ω ≻ gi for all i. Let c1 , c2 , . . . ∈
R with c1 < c2 < · · ·.
∑
Then limx→∞ i gi ω ci = limx→∞ g1 ω c1 .
For g1 = g and ω as above we also have the following easy result:
• limx→∞ gω c = 0 for c > 0
• limx→∞ gω c = ±∞ for c < 0, where the sign is determined by the (eventual) sign of g
• limx→∞ gω 0 = limx→∞ g.
Using these results yields the following strategy for computing limx→∞ f (x):
1. Find the set of most rapidly varying subexpressions (MRV set) of f (x). That is, from the
set of all subexpressions of f (x), find the elements that are maximal under the relation
≻.
2. Choose a function ω that is in the same comparability class as the elements in the MRV
set, such that limx→∞ ω = 0.
3. Expand f (x) as a series in ω in such a way that the antecedents of the above theorem are
satisfied.
4. Apply the theorem and conclude the computation of limx→∞ f (x), possibly by recursively
working on g1 (x).

Notes

This exposition glossed over several details. Many are described in the file gruntz.py, and all
can be found in Gruntz’ very readable thesis. The most important points that have not been

5.25. Series Module 1137

SymPy Documentation, Release 1.3

explained are:
1. Given f(x) and g(x), how do we determine if f (x) ≻ g(x), g(x) ≻ f (x) or g(x) ≍ f (x)?
2. How do we find the MRV set of an expression?
3. How do we compute series expansions?
4. Why does the algorithm terminate?
If you are interested, be sure to take a look at Gruntz Thesis.

Reference

sympy.series.gruntz.gruntz(e, z, z0, dir=’+’)

Compute the limit of e(z) at the point z0 using the Gruntz algorithm.
z0 can be any expression, including oo and -oo.
For dir=”+” (default) it calculates the limit from the right (z->z0+) and for dir=”-” the
limit from the left (z->z0-). For infinite z0 (oo or -oo), the dir argument doesn’t matter.
This algorithm is fully described in the module docstring in the gruntz.py file. It relies
heavily on the series expansion. Most frequently, gruntz() is only used if the faster limit()
function (which uses heuristics) fails.
sympy.series.gruntz.compare(a, b, x)
Returns “<” if a<b, “=” for a == b, “>” for a>b
sympy.series.gruntz.rewrite(e, Omega, x, wsym)
e(x) … the function Omega … the mrv set wsym … the symbol which is going to be used
for w
Returns the rewritten e in terms of w and log(w). See test_rewrite1() for examples and
correct results.
sympy.series.gruntz.build_expression_tree(Omega, rewrites)
Helper function for rewrite.
We need to sort Omega (mrv set) so that we replace an expression before we replace any
expression in terms of which it has to be rewritten:

e1 ---> e2 ---> e3
\
-> e4

Here we can do e1, e2, e3, e4 or e1, e2, e4, e3. To do this we assemble the nodes into a
tree, and sort them by height.
This function builds the tree, rewrites then sorts the nodes.
sympy.series.gruntz.mrv_leadterm(e, x)
Returns (c0, e0) for e.
sympy.series.gruntz.calculate_series(e, x, logx=None)
Calculates at least one term of the series of “e” in “x”.
This is a place that fails most often, so it is in its own function.
sympy.series.gruntz.limitinf(e, x)
Limit e(x) for x-> oo

1138 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.series.gruntz.sign(e, x)
Returns a sign of an expression e(x) for x->oo.
e > 0 for x sufficiently large ... 1
e == 0 for x sufficiently large ... 0
e < 0 for x sufficiently large ... -1

The result of this function is currently undefined if e changes sign arbitrarily often for
arbitrarily large x (e.g. sin(x)).
Note that this returns zero only if e is constantly zero for x sufficiently large. [If e is
constant, of course, this is just the same thing as the sign of e.]
sympy.series.gruntz.mrv(e, x)
Returns a SubsSet of most rapidly varying (mrv) subexpressions of ‘e’, and e rewritten
in terms of these
sympy.series.gruntz.mrv_max1(f, g, exps, x)
Computes the maximum of two sets of expressions f and g, which are in the same com-
parability class, i.e. mrv_max1() compares (two elements of) f and g and returns the set,
which is in the higher comparability class of the union of both, if they have the same
order of variation. Also returns exps, with the appropriate substitutions made.
sympy.series.gruntz.mrv_max3(f, expsf, g, expsg, union, expsboth, x)
Computes the maximum of two sets of expressions f and g, which are in the same compa-
rability class, i.e. max() compares (two elements of) f and g and returns either (f, expsf)
[if f is larger], (g, expsg) [if g is larger] or (union, expsboth) [if f, g are of the same class].
class sympy.series.gruntz.SubsSet
Stores (expr, dummy) pairs, and how to rewrite expr-s.
The gruntz algorithm needs to rewrite certain expressions in term of a new variable w.
We cannot use subs, because it is just too smart for us. For example:
> Omega=[exp(exp(_p - exp(-_p))/(1 - 1/_p)), exp(exp(_p))]
> O2=[exp(-exp(_p) + exp(-exp(-_p))*exp(_p)/(1 - 1/_p))/_w, 1/_w]
> e = exp(exp(_p - exp(-_p))/(1 - 1/_p)) - exp(exp(_p))
> e.subs(Omega[0],O2[0]).subs(Omega[1],O2[1])
-1/w + exp(exp(p)*exp(-exp(-p))/(1 - 1/p))

is really not what we want!

So we do it the hard way and keep track of all the things we potentially want to substitute
by dummy variables. Consider the expression:
exp(x - exp(-x)) + exp(x) + x.

The mrv set is {exp(x), exp(-x), exp(x - exp(-x))}. We introduce corresponding dummy
variables d1, d2, d3 and rewrite:
d3 + d1 + x.

This class first of all keeps track of the mapping expr->variable, i.e. will at this stage be
a dictionary:
{exp(x): d1, exp(-x): d2, exp(x - exp(-x)): d3}.

[It turns out to be more convenient this way round.] But sometimes expressions in the
mrv set have other expressions from the mrv set as subexpressions, and we need to keep
track of that as well. In this case, d3 is really exp(x - d2), so rewrites at this stage is:

5.25. Series Module 1139

SymPy Documentation, Release 1.3

{d3: exp(x-d2)}.

The function rewrite uses all this information to correctly rewrite our expression in terms
of w. In this case w can be chosen to be exp(-x), i.e. d2. The correct rewriting then is:

exp(-w)/w + 1/w + x.

copy()
Create a shallow copy of SubsSet
do_subs(e)
Substitute the variables with expressions
meets(s2)
Tell whether or not self and s2 have non-empty intersection
union(s2, exps=None)
Compute the union of self and s2, adjusting exps

More Intuitive Series Expansion

This is achieved by creating a wrapper around Basic.series(). This allows for the use of se-
ries(x*cos(x),x), which is possibly more intuitive than (x*cos(x)).series(x).

Examples

>>> from sympy import Symbol, cos, series

>>> x = Symbol('x')
>>> series(cos(x),x)
1 - x**2/2 + x**4/24 + O(x**6)

Reference

sympy.series.series.series(expr, x=None, x0=0, n=6, dir=’+’)

Series expansion of expr around point x = x0.
See the doctring of Expr.series() for complete details of this wrapper.

Order Terms

This module also implements automatic keeping track of the order of your expansion.

Examples

>>> from sympy import Symbol, Order

>>> x = Symbol('x')
>>> Order(x) + x**2
O(x)
(continues on next page)

1140 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> Order(x) + 1
1 + O(x)

Reference

class sympy.series.order.Order
Represents the limiting behavior of some function
The order of a function characterizes the function based on the limiting behavior of the
function as it goes to some limit. Only taking the limit point to be a number is currently
supported. This is expressed in big O notation [R497].
The formal definition for the order of a function g(x) about a point a is such that g(x) =
O(f (x)) as x → a if and only if for any δ > 0 there exists a M > 0 such that |g(x)| ≤ M |f (x)|
for |x − a| < δ. This is equivalent to limx→a sup |g(x)/f (x)| < ∞.
Let’s illustrate it on the following example by taking the expansion of sin(x) about 0:

sin(x) = x − x3 /3! + O(x5 )

where in this case O(x5 ) = x5 /5! − x7 /7! + · · ·. By the definition of O, for any δ > 0 there is
an M such that:

|x5 /5! − x7 /7! + ....| <= M |x5 | for |x| < δ

or by the alternate definition:

lim |(x5 /5! − x7 /7! + ....)/x5 | < ∞
x→0

which surely is true, because

lim |(x5 /5! − x7 /7! + ....)/x5 | = 1/5!
x→0

As it is usually used, the order of a function can be intuitively thought of representing

all terms of powers greater than the one specified. For example, O(x3 ) corresponds to
any terms proportional to x3 , x4 , . . . and any higher power. For a polynomial, this leaves
terms proportional to x2 , x and constants.

Notes

In O(f(x), x) the expression f(x) is assumed to have a leading term. O(f(x), x) is

automatically transformed to O(f(x).as_leading_term(x),x).
O(expr*f(x), x) is O(f(x), x)
O(expr, x) is O(1)
O(0, x) is 0.
Multivariate O is also supported:
O(f(x, y), x, y) is transformed to O(f(x, y).as_leading_term(x,y).
as_leading_term(y), x, y)
In the multivariate case, it is assumed the limits w.r.t. the various symbols commute.
If no symbols are passed then all symbols in the expression are used and the limit point
is assumed to be zero.

5.25. Series Module 1141

SymPy Documentation, Release 1.3

References

[R497]

Examples

>>> from sympy import O, oo, cos, pi

>>> from sympy.abc import x, y

>>> O(x + x**2)

O(x)
>>> O(x + x**2, (x, 0))
O(x)
>>> O(x + x**2, (x, oo))
O(x**2, (x, oo))

>>> O(1 + x*y)

O(1, x, y)
>>> O(1 + x*y, (x, 0), (y, 0))
O(1, x, y)
>>> O(1 + x*y, (x, oo), (y, oo))
O(x*y, (x, oo), (y, oo))

>>> O(1) in O(1, x)

True
>>> O(1, x) in O(1)
False
>>> O(x) in O(1, x)
True
>>> O(x**2) in O(x)
True

>>> O(x)*x
O(x**2)
>>> O(x) - O(x)
O(x)
>>> O(cos(x))
O(1)
>>> O(cos(x), (x, pi/2))
O(x - pi/2, (x, pi/2))

contains(expr)
Return True if expr belongs to Order(self.expr, *self.variables). Return False if self
belongs to expr. Return None if the inclusion relation cannot be determined (e.g.
when self and expr have different symbols).

Series Acceleration

TODO

1142 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Reference

sympy.series.acceleration.richardson(A, k, n, N)
Calculate an approximation for lim k->oo A(k) using Richardson extrapolation with the
terms A(n), A(n+1), …, A(n+N+1). Choosing N ~= 2*n often gives good results.
A simple example is to calculate exp(1) using the limit definition. This limit converges
slowly; n = 100 only produces two accurate digits:

>>> from sympy.abc import n

>>> e = (1 + 1/n)**n
>>> print(round(e.subs(n, 100).evalf(), 10))
2.7048138294

Richardson extrapolation with 11 appropriately chosen terms gives a value that is accu-
rate to the indicated precision:

>>> from sympy import E

>>> from sympy.series.acceleration import richardson
>>> print(round(richardson(e, n, 10, 20).evalf(), 10))
2.7182818285
>>> print(round(E.evalf(), 10))
2.7182818285

Another useful application is to speed up convergence of series. Computing 100 terms

of the zeta(2) series 1/k**2 yields only two accurate digits:

>>> from sympy.abc import k, n

>>> from sympy import Sum
>>> A = Sum(k**-2, (k, 1, n))
>>> print(round(A.subs(n, 100).evalf(), 10))
1.6349839002

Richardson extrapolation performs much better:

>>> from sympy import pi

>>> print(round(richardson(A, n, 10, 20).evalf(), 10))
1.6449340668
>>> print(round(((pi**2)/6).evalf(), 10)) # Exact value
1.6449340668

sympy.series.acceleration.shanks(A, k, n, m=1)
Calculate an approximation for lim k->oo A(k) using the n-term Shanks transfor-
mation S(A)(n). With m > 1, calculate the m-fold recursive Shanks transformation
S(S(…S(A)…))(n).
The Shanks transformation is useful for summing Taylor series that converge slowly near
a pole or singularity, e.g. for log(2):

>>> from sympy.abc import k, n

>>> from sympy import Sum, Integer
>>> from sympy.series.acceleration import shanks
>>> A = Sum(Integer(-1)**(k+1) / k, (k, 1, n))
>>> print(round(A.subs(n, 100).doit().evalf(), 10))
0.6881721793
>>> print(round(shanks(A, n, 25).evalf(), 10))
0.6931396564
(continues on next page)

5.25. Series Module 1143

SymPy Documentation, Release 1.3

(continued from previous page)

>>> print(round(shanks(A, n, 25, 5).evalf(), 10))
0.6931471806

The correct value is 0.6931471805599453094172321215.

Residues

TODO

Reference

sympy.series.residues.residue(expr, x, x0)
Finds the residue of expr at the point x=x0.
The residue is defined as the coefficient of 1/(x-x0) in the power series expansion about
x=x0.

References

1. http://en.wikipedia.org/wiki/Residue_theorem

Examples

>>> from sympy import Symbol, residue, sin

>>> x = Symbol(”x”)
>>> residue(1/x, x, 0)
1
>>> residue(1/x**2, x, 0)
0
>>> residue(2/sin(x), x, 0)
2

This function is essential for the Residue Theorem [1].

Sequences

A sequence is a finite or infinite lazily evaluated list.

sympy.series.sequences.sequence(seq, limits=None)
Returns appropriate sequence object.
If seq is a sympy sequence, returns SeqPer (page 1147) object otherwise returns Seq-
Formula (page 1146) object.
See also:
sympy.series.sequences.SeqPer (page 1147), sympy.series.sequences.SeqFormula
(page 1146)

1144 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import sequence, SeqPer, SeqFormula

>>> from sympy.abc import n
>>> sequence(n**2, (n, 0, 5))
SeqFormula(n**2, (n, 0, 5))
>>> sequence((1, 2, 3), (n, 0, 5))
SeqPer((1, 2, 3), (n, 0, 5))

Sequences Base

class sympy.series.sequences.SeqBase
Base class for sequences
coeff(pt)
Returns the coefficient at point pt
coeff_mul(other)
Should be used when other is not a sequence. Should be defined to define custom
behaviour.

Notes

‘*’ defines multiplication of sequences with sequences only.

Examples

>>> from sympy import S, oo, SeqFormula

>>> from sympy.abc import n
>>> SeqFormula(n**2).coeff_mul(2)
SeqFormula(2*n**2, (n, 0, oo))

find_linear_recurrence(n, d=None, gfvar=None)

Finds the shortest linear recurrence that satisfies the first n terms of sequence of
order ≤ n/2 if possible. If d is specified, find shortest linear recurrence of order ≤
min(d, n/2) if possible. Returns list of coefficients [b(1), b(2), ...] correspond-
ing to the recurrence relation x(n) = b(1)*x(n-1) + b(2)*x(n-2) + ... Returns
[] if no recurrence is found. If gfvar is specified, also returns ordinary generating
function as a function of gfvar.

Examples

>>> from sympy import sequence, sqrt, oo, lucas

>>> from sympy.abc import n, x, y
>>> sequence(n**2).find_linear_recurrence(10, 2)
[]
>>> sequence(n**2).find_linear_recurrence(10)
[3, -3, 1]
>>> sequence(2**n).find_linear_recurrence(10)
[2]
(continues on next page)

5.25. Series Module 1145

SymPy Documentation, Release 1.3

(continued from previous page)

>>> sequence(23*n**4+91*n**2).find_linear_recurrence(10)
[5, -10, 10, -5, 1]
>>> sequence(sqrt(5)*(((1 + sqrt(5))/2)**n - (-(1 + sqrt(5))/2)**(-n))/5).
,→find_linear_recurrence(10)

[1, 1]
>>> sequence(x+y*(-2)**(-n), (n, 0, oo)).find_linear_recurrence(30)
[1/2, 1/2]
>>> sequence(3*5**n + 12).find_linear_recurrence(20,gfvar=x)
([6, -5], 3*(-21*x + 5)/((x - 1)*(5*x - 1)))
>>> sequence(lucas(n)).find_linear_recurrence(15,gfvar=x)
([1, 1], (x - 2)/(x**2 + x - 1))

free_symbols
This method returns the symbols in the object, excluding those that take on a specific
value (i.e. the dummy symbols).

Examples

>>> from sympy import SeqFormula

>>> from sympy.abc import n, m
>>> SeqFormula(m*n**2, (n, 0, 5)).free_symbols
{m}

gen
Returns the generator for the sequence
interval
The interval on which the sequence is defined
length
Length of the sequence
start
The starting point of the sequence. This point is included
stop
The ending point of the sequence. This point is included
variables
Returns a tuple of variables that are bounded

Elementary Sequences

class sympy.series.sequences.SeqFormula
Represents sequence based on a formula.
Elements are generated using a formula.
See also:
sympy.series.sequences.SeqPer (page 1147)

1146 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import SeqFormula, oo, Symbol

>>> n = Symbol('n')
>>> s = SeqFormula(n**2, (n, 0, 5))
>>> s.formula
n**2

For value at a particular point

>>> s.coeff(3)
9

supports slicing

>>> s[:]
[0, 1, 4, 9, 16, 25]

iterable

>>> list(s)
[0, 1, 4, 9, 16, 25]

sequence starts from negative infinity

>>> SeqFormula(n**2, (-oo, 0))[0:6]

[0, 1, 4, 9, 16, 25]

coeff_mul(coeff)
See docstring of SeqBase.coeff_mul
class sympy.series.sequences.SeqPer
Represents a periodic sequence.
The elements are repeated after a given period.
See also:
sympy.series.sequences.SeqFormula (page 1146)

Examples

>>> from sympy import SeqPer, oo

>>> from sympy.abc import k

>>> s = SeqPer((1, 2, 3), (0, 5))

>>> s.periodical
(1, 2, 3)
>>> s.period
3

For value at a particular point

>>> s.coeff(3)
1

supports slicing

5.25. Series Module 1147

SymPy Documentation, Release 1.3

>>> s[:]
[1, 2, 3, 1, 2, 3]

iterable

>>> list(s)
[1, 2, 3, 1, 2, 3]

sequence starts from negative infinity

>>> SeqPer((1, 2, 3), (-oo, 0))[0:6]

[1, 2, 3, 1, 2, 3]

Periodic formulas

>>> SeqPer((k, k**2, k**3), (k, 0, oo))[0:6]

[0, 1, 8, 3, 16, 125]

coeff_mul(coeff)
See docstring of SeqBase.coeff_mul

Singleton Sequences

class sympy.series.sequences.EmptySequence
Represents an empty sequence.
The empty sequence is available as a singleton as S.EmptySequence.

Examples

>>> from sympy import S, SeqPer, oo

>>> from sympy.abc import x
>>> S.EmptySequence
EmptySequence()
>>> SeqPer((1, 2), (x, 0, 10)) + S.EmptySequence
SeqPer((1, 2), (x, 0, 10))
>>> SeqPer((1, 2)) * S.EmptySequence
EmptySequence()
>>> S.EmptySequence.coeff_mul(-1)
EmptySequence()

coeff_mul(coeff)
See docstring of SeqBase.coeff_mul

Compound Sequences

class sympy.series.sequences.SeqAdd
Represents term-wise addition of sequences.
Rules:
• The interval on which sequence is defined is the intersection of respective inter-
vals of sequences.

1148 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• Anything + EmptySequence (page 1148) remains unchanged.

• Other rules are defined in _add methods of sequence classes.
See also:
sympy.series.sequences.SeqMul (page 1149)

Examples

>>> from sympy import S, oo, SeqAdd, SeqPer, SeqFormula

>>> from sympy.abc import n
>>> SeqAdd(SeqPer((1, 2), (n, 0, oo)), S.EmptySequence)
SeqPer((1, 2), (n, 0, oo))
>>> SeqAdd(SeqPer((1, 2), (n, 0, 5)), SeqPer((1, 2), (n, 6, 10)))
EmptySequence()
>>> SeqAdd(SeqPer((1, 2), (n, 0, oo)), SeqFormula(n**2, (n, 0, oo)))
SeqAdd(SeqFormula(n**2, (n, 0, oo)), SeqPer((1, 2), (n, 0, oo)))
>>> SeqAdd(SeqFormula(n**3), SeqFormula(n**2))
SeqFormula(n**3 + n**2, (n, 0, oo))

static reduce(args)
Simplify SeqAdd (page 1148) using known rules.
Iterates through all pairs and ask the constituent sequences if they can simplify
themselves with any other constituent.

Notes

adapted from Union.reduce

class sympy.series.sequences.SeqMul
Represents term-wise multiplication of sequences.
Handles multiplication of sequences only. For multiplication with other objects see
SeqBase.coeff_mul() (page 1145).
Rules:
• The interval on which sequence is defined is the intersection of respective inter-
vals of sequences.
• Anything * EmptySequence (page 1148) returns EmptySequence (page 1148).
• Other rules are defined in _mul methods of sequence classes.
See also:
sympy.series.sequences.SeqAdd (page 1148)

Examples

>>> from sympy import S, oo, SeqMul, SeqPer, SeqFormula

>>> from sympy.abc import n
>>> SeqMul(SeqPer((1, 2), (n, 0, oo)), S.EmptySequence)
EmptySequence()
>>> SeqMul(SeqPer((1, 2), (n, 0, 5)), SeqPer((1, 2), (n, 6, 10)))
(continues on next page)

5.25. Series Module 1149

SymPy Documentation, Release 1.3

(continued from previous page)

EmptySequence()
>>> SeqMul(SeqPer((1, 2), (n, 0, oo)), SeqFormula(n**2))
SeqMul(SeqFormula(n**2, (n, 0, oo)), SeqPer((1, 2), (n, 0, oo)))
>>> SeqMul(SeqFormula(n**3), SeqFormula(n**2))
SeqFormula(n**5, (n, 0, oo))

static reduce(args)
Simplify a SeqMul (page 1149) using known rules.
Iterates through all pairs and ask the constituent sequences if they can simplify
themselves with any other constituent.

Notes

adapted from Union.reduce

Fourier Series

Provides methods to compute Fourier series.

class sympy.series.fourier.FourierSeries
Represents Fourier sine/cosine series.
This class only represents a fourier series. No computation is performed.
For how to compute Fourier series, see the fourier_series() (page 1152) docstring.
See also:
sympy.series.fourier.fourier_series (page 1152)
scale(s)
Scale the function by a term independent of x.
f(x) -> s * f(x)
This is fast, if Fourier series of f(x) is already computed.

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x**2, (x, -pi, pi))
>>> s.scale(2).truncate()
-8*cos(x) + 2*cos(2*x) + 2*pi**2/3

scalex(s)
Scale x by a term independent of x.
f(x) -> f(s*x)
This is fast, if Fourier series of f(x) is already computed.

1150 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x**2, (x, -pi, pi))
>>> s.scalex(2).truncate()
-4*cos(2*x) + cos(4*x) + pi**2/3

shift(s)
Shift the function by a term independent of x.
f(x) -> f(x) + s
This is fast, if Fourier series of f(x) is already computed.

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x**2, (x, -pi, pi))
>>> s.shift(1).truncate()
-4*cos(x) + cos(2*x) + 1 + pi**2/3

shiftx(s)
Shift x by a term independent of x.
f(x) -> f(x + s)
This is fast, if Fourier series of f(x) is already computed.

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x**2, (x, -pi, pi))
>>> s.shiftx(1).truncate()
-4*cos(x + 1) + cos(2*x + 2) + pi**2/3

sigma_approximation(n=3)
Return σ-approximation of Fourier series with respect to order n.
Sigma approximation adjusts a Fourier summation to eliminate the Gibbs phe-
nomenon which would otherwise occur at discontinuities. A sigma-approximated
summation for a Fourier series of a T-periodical function can be written as

1 ∑
m−1 (k) [ ( 2πk ) ( 2πk )]
s(θ) = a0 + sinc · ak cos θ + bk sin θ ,
2 m T T
k=1
( )
where a0 , ak , bk , k = 1, . . . , m − 1 are standard Fourier series coefficients and sinc k
m
is a Lanczos σ factor (expressed in terms of normalized sinc function).
Parameters n : int
Highest order of the terms taken into account in approximation.

5.25. Series Module 1151

SymPy Documentation, Release 1.3

Returns Expr
Sigma approximation of function expanded into Fourier series.
See also:
sympy.series.fourier.FourierSeries.truncate (page 1152)

Notes

The behaviour of sigma_approximation() (page 1151) is different from truncate()

(page 1152) - it takes all nonzero terms of degree smaller than n, rather than first n
nonzero ones.

References

[R492], [R493]

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x, (x, -pi, pi))
>>> s.sigma_approximation(4)
2*sin(x)*sinc(pi/4) - 2*sin(2*x)/pi + 2*sin(3*x)*sinc(3*pi/4)/3

truncate(n=3)
Return the first n nonzero terms of the series.
If n is None return an iterator.
Parameters n : int or None
Amount of non-zero terms in approximation or None.
Returns Expr or iterator
Approximation of function expanded into Fourier series.
See also:
sympy.series.fourier.FourierSeries.sigma_approximation (page 1151)

Examples

>>> from sympy import fourier_series, pi

>>> from sympy.abc import x
>>> s = fourier_series(x, (x, -pi, pi))
>>> s.truncate(4)
2*sin(x) - sin(2*x) + 2*sin(3*x)/3 - sin(4*x)/2

sympy.series.fourier.fourier_series(f, limits=None)
Computes Fourier sine/cosine series expansion.
Returns a FourierSeries (page 1150) object.

1152 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

See also:
sympy.series.fourier.FourierSeries (page 1150)

Notes

Computing Fourier series can be slow due to the integration required in computing an,
bn.
It is faster to compute Fourier series of a function by using shifting and scaling on an
already computed Fourier series rather than computing again.
e.g. If the Fourier series of x**2 is known the Fourier series of x**2 - 1 can be found
by shifting by -1.

References

[R494]

Examples

>>> from sympy import fourier_series, pi, cos

>>> from sympy.abc import x

>>> s = fourier_series(x**2, (x, -pi, pi))

>>> s.truncate(n=3)
-4*cos(x) + cos(2*x) + pi**2/3

Shifting

>>> s.shift(1).truncate()
-4*cos(x) + cos(2*x) + 1 + pi**2/3
>>> s.shiftx(1).truncate()
-4*cos(x + 1) + cos(2*x + 2) + pi**2/3

Scaling

>>> s.scale(2).truncate()
-8*cos(x) + 2*cos(2*x) + 2*pi**2/3
>>> s.scalex(2).truncate()
-4*cos(2*x) + cos(4*x) + pi**2/3

Formal Power Series

Methods for computing and manipulating Formal Power Series.

class sympy.series.formal.FormalPowerSeries
Represents Formal Power Series of a function.
No computation is performed. This class should only to be used to represent a series.
No checks are performed.
For computing a series use fps() (page 1154).

5.25. Series Module 1153

SymPy Documentation, Release 1.3

See also:
sympy.series.formal.fps (page 1154)
infinite
Returns an infinite representation of the series
integrate(x=None, **kwargs)
Integrate Formal Power Series.

Examples

>>> from sympy import fps, sin, integrate

>>> from sympy.abc import x
>>> f = fps(sin(x))
>>> f.integrate(x).truncate()
-1 + x**2/2 - x**4/24 + O(x**6)
>>> integrate(f, (x, 0, 1))
-cos(1) + 1

polynomial(n=6)
Truncated series as polynomial.
Returns series sexpansion of f upto order O(x**n) as a polynomial(without O term).
truncate(n=6)
Truncated series.
Returns truncated series expansion of f upto order O(x**n).
If n is None, returns an infinite iterator.
sympy.series.formal.fps(f, x=None, x0=0, dir=1, hyper=True, order=4, ratio-
nal=True, full=False)
Generates Formal Power Series of f.
Returns the formal series expansion of f around x = x0 with respect to x in the form of
a FormalPowerSeries object.
Formal Power Series is represented using an explicit formula computed using different
algorithms.
See compute_fps() (page 1155) for the more details regarding the computation of for-
mula.
Parameters x : Symbol, optional
If x is None and f is univariate, the univariate symbols will be sup-
plied, otherwise an error will be raised.
x0 : number, optional
Point to perform series expansion about. Default is 0.
dir : {1, -1, ‘+’, ‘-‘}, optional
If dir is 1 or ‘+’ the series is calculated from the right and for -1 or ‘-‘
the series is calculated from the left. For smooth functions this flag
will not alter the results. Default is 1.
hyper : {True, False}, optional

1154 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Set hyper to False to skip the hypergeometric algorithm. By default

it is set to False.
order : int, optional
Order of the derivative of f, Default is 4.
rational : {True, False}, optional
Set rational to False to skip rational algorithm. By default it is set to
True.
full : {True, False}, optional
Set full to True to increase the range of rational algorithm. See ra-
tional_algorithm() (page 1156) for details. By default it is set to
False.
See also:
sympy.series.formal.FormalPowerSeries (page 1153), sympy.series.formal.
compute_fps (page 1155)

Examples

>>> from sympy import fps, O, ln, atan

>>> from sympy.abc import x

Rational Functions

>>> fps(ln(1 + x)).truncate()

x - x**2/2 + x**3/3 - x**4/4 + x**5/5 + O(x**6)

>>> fps(atan(x), full=True).truncate()

x - x**3/3 + x**5/5 + O(x**6)

sympy.series.formal.compute_fps(f, x, x0=0, dir=1, hyper=True, order=4, ratio-

nal=True, full=False)
Computes the formula for Formal Power Series of a function.
Tries to compute the formula by applying the following techniques (in order):
• rational_algorithm
• Hypergeomitric algorithm

Parameters x : Symbol
x0 : number, optional
Point to perform series expansion about. Default is 0.
dir : {1, -1, ‘+’, ‘-‘}, optional
If dir is 1 or ‘+’ the series is calculated from the right and for -1 or ‘-‘
the series is calculated from the left. For smooth functions this flag
will not alter the results. Default is 1.
hyper : {True, False}, optional
Set hyper to False to skip the hypergeometric algorithm. By default
it is set to False.

5.25. Series Module 1155

SymPy Documentation, Release 1.3

order : int, optional

Order of the derivative of f, Default is 4.
rational : {True, False}, optional
Set rational to False to skip rational algorithm. By default it is set to
True.
full : {True, False}, optional
Set full to True to increase the range of rational algorithm. See ra-
tional_algorithm() (page 1156) for details. By default it is set to
False.
Returns ak : sequence
Sequence of coefficients.
xk : sequence
Sequence of powers of x.
ind : Expr
Independent terms.
mul : Pow
Common terms.

See also:
sympy.series.formal.rational_algorithm (page 1156), sympy.series.formal.
hyper_algorithm (page 1160)

Rational Algorithm

sympy.series.formal.rational_independent(terms, x)
Returns a list of all the rationally independent terms.

Examples

>>> from sympy import sin, cos

>>> from sympy.series.formal import rational_independent
>>> from sympy.abc import x

>>> rational_independent([cos(x), sin(x)], x)

[cos(x), sin(x)]
>>> rational_independent([x**2, sin(x), x*sin(x), x**3], x)
[x**3 + x**2, x*sin(x) + sin(x)]

sympy.series.formal.rational_algorithm(f, x, k, order=4, full=False)

Rational algorithm for computing formula of coefficients of Formal Power Series of a
function.
Applicable when f(x) or some derivative of f(x) is a rational function in x.

1156 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

rational_algorithm() (page 1156) uses apart() function for partial fraction decom-
position. apart() by default uses ‘undetermined coefficients method’. By setting
full=True, ‘Bronstein’s algorithm’ can be used instead.
Looks for derivative of a function up to 4’th order (by default). This can be overridden
using order option.
Returns formula : Expr
ind : Expr
Independent terms.
order : int
See also:
sympy.polys.partfrac.apart (page 902)

Notes

By setting full=True, range of admissible functions to be solved using ratio-

nal_algorithm can be increased. This option should be used carefully as it can signifi-
cantly slow down the computation as doit is performed on the RootSum object returned
by the apart function. Use full=False whenever possible.

References

[R488], [R489]

Examples

>>> from sympy import log, atan, I

>>> from sympy.series.formal import rational_algorithm as ra
>>> from sympy.abc import x, k

>>> ra(1 / (1 - x), x, k)

(1, 0, 0)
>>> ra(log(1 + x), x, k)
(-(-1)**(-k)/k, 0, 1)

>>> ra(atan(x), x, k, full=True)

((-I*(-I)**(-k)/2 + I*I**(-k)/2)/k, 0, 1)

Hypergeometric Algorithm

sympy.series.formal.simpleDE(f, x, g, order=4)
Generates simple DE.
DE is of the form

∑
k−1
f k (x) + Aj f j (x) = 0
j=0

5.25. Series Module 1157

SymPy Documentation, Release 1.3

where Aj should be rational function in x.

Generates DE’s upto order 4 (default). DE’s can also have free parameters.
By increasing order, higher order DE’s can be found.
Yields a tuple of (DE, order).
sympy.series.formal.exp_re(DE, r, k)
Converts a DE with constant coefficients (explike) into a RE.
Performs the substitution:

f j (x) → r(k + j)

Normalises the terms so that lowest order of a term is always r(k).

See also:
sympy.series.formal.hyper_re (page 1158)

Examples

>>> from sympy import Function, Derivative

>>> from sympy.series.formal import exp_re
>>> from sympy.abc import x, k
>>> f, r = Function('f'), Function('r')

>>> exp_re(-f(x) + Derivative(f(x)), r, k)

-r(k) + r(k + 1)
>>> exp_re(Derivative(f(x), x) + Derivative(f(x), (x, 2)), r, k)
r(k) + r(k + 1)

sympy.series.formal.hyper_re(DE, r, k)
Converts a DE into a RE.
Performs the substitution:

xl f j (x) → (k + 1 − l)j .ak+j−l

Normalises the terms so that lowest order of a term is always r(k).

See also:
sympy.series.formal.exp_re (page 1158)

Examples

>>> from sympy import Function, Derivative

>>> from sympy.series.formal import hyper_re
>>> from sympy.abc import x, k
>>> f, r = Function('f'), Function('r')

>>> hyper_re(-f(x) + Derivative(f(x)), r, k)

(k + 1)*r(k + 1) - r(k)
>>> hyper_re(-x*f(x) + Derivative(f(x), (x, 2)), r, k)
(k + 2)*(k + 3)*r(k + 3) - r(k)

1158 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.series.formal.rsolve_hypergeometric(f, x, P, Q, k, m)
Solves RE of hypergeometric type.
Attempts to solve RE of the form
Q(k)*a(k + m) - P(k)*a(k)
Transformations that preserve Hypergeometric type:
a. x**n*f(x): b(k + m) = R(k - n)*b(k)
b. f(A*x): b(k + m) = A**m*R(k)*b(k)
c. f(x**n): b(k + n*m) = R(k/n)*b(k)
d. f(x**(1/m)): b(k + 1) = R(k*m)*b(k)
e. f’(x): b(k + m) = ((k + m + 1)/(k + 1))*R(k + 1)*b(k)
Some of these transformations have been used to solve the RE.
Returns formula : Expr
ind : Expr
Independent terms.
order : int

References

[R490], [R491]

Examples

>>> from sympy import exp, ln, S

>>> from sympy.series.formal import rsolve_hypergeometric as rh
>>> from sympy.abc import x, k

>>> rh(exp(x), x, -S.One, (k + 1), k, 1)

(Piecewise((1/factorial(k), Eq(Mod(k, 1), 0)), (0, True)), 1, 1)

>>> rh(ln(1 + x), x, k**2, k*(k + 1), k, 1)

(Piecewise(((-1)**(k - 1)*factorial(k - 1)/RisingFactorial(2, k - 1),
Eq(Mod(k, 1), 0)), (0, True)), x, 2)

sympy.series.formal.solve_de(f, x, DE, order, g, k)

Solves the DE.
Tries to solve DE by either converting into a RE containing two terms or converting into
a DE having constant coefficients.
Returns formula : Expr
ind : Expr
Independent terms.
order : int

5.25. Series Module 1159

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Derivative as D, Function

>>> from sympy import exp, ln
>>> from sympy.series.formal import solve_de
>>> from sympy.abc import x, k
>>> f = Function('f')

>>> solve_de(exp(x), x, D(f(x), x) - f(x), 1, f, k)

(Piecewise((1/factorial(k), Eq(Mod(k, 1), 0)), (0, True)), 1, 1)

>>> solve_de(ln(1 + x), x, (x + 1)*D(f(x), x, 2) + D(f(x)), 2, f, k)

(Piecewise(((-1)**(k - 1)*factorial(k - 1)/RisingFactorial(2, k - 1),
Eq(Mod(k, 1), 0)), (0, True)), x, 2)

sympy.series.formal.hyper_algorithm(f, x, k, order=4)
Hypergeometric algorithm for computing Formal Power Series.
Steps:
• Generates DE
• Convert the DE into RE
• Solves the RE
See also:
sympy.series.formal.simpleDE (page 1157), sympy.series.formal.solve_de
(page 1159)

Examples

>>> from sympy import exp, ln

>>> from sympy.series.formal import hyper_algorithm

>>> from sympy.abc import x, k

>>> hyper_algorithm(exp(x), x, k)
(Piecewise((1/factorial(k), Eq(Mod(k, 1), 0)), (0, True)), 1, 1)

>>> hyper_algorithm(ln(1 + x), x, k)

(Piecewise(((-1)**(k - 1)*factorial(k - 1)/RisingFactorial(2, k - 1),
Eq(Mod(k, 1), 0)), (0, True)), x, 2)

Limits of Sequences

Provides methods to compute limit of terms having sequences at infinity.

sympy.series.limitseq.difference_delta(expr, n=None, step=1)
Difference Operator.
Discrete analog of differential operator. Given a sequence x[n], returns the sequence x[n
+ step] - x[n].

1160 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R495]

Examples

>>> from sympy import difference_delta as dd

>>> from sympy.abc import n
>>> dd(n*(n + 1), n)
2*n + 2
>>> dd(n*(n + 1), n, 2)
4*n + 6

sympy.series.limitseq.dominant(expr, n)
Finds the dominant term in a sum, that is a term that dominates every other term.
If limit(a/b, n, oo) is oo then a dominates b. If limit(a/b, n, oo) is 0 then b dominates a.
Otherwise, a and b are comparable.
If there is no unique dominant term, then returns None.
See also:
sympy.series.limitseq.dominant (page 1161)

Examples

>>> from sympy import Sum

>>> from sympy.series.limitseq import dominant
>>> from sympy.abc import n, k
>>> dominant(5*n**3 + 4*n**2 + n + 1, n)
5*n**3
>>> dominant(2**n + Sum(k, (k, 0, n)), n)
2**n

sympy.series.limitseq.limit_seq(expr, n=None, trials=5)

Finds limits of terms having sequences at infinity.
Parameters expr : Expr
SymPy expression for the n-th term of the sequence
n : Symbol
The index of the sequence, an integer that tends to positive infinity.
trials: int, optional
The algorithm is highly recursive. trials is a safeguard from infinite
recursion in case the limit is not easily computed by the algorithm.
Try increasing trials if the algorithm returns None.
See also:
sympy.series.limitseq.dominant (page 1161)

5.25. Series Module 1161

SymPy Documentation, Release 1.3

References

[R496]

Examples

>>> from sympy import limit_seq, Sum, binomial

>>> from sympy.abc import n, k, m
>>> limit_seq((5*n**3 + 3*n**2 + 4) / (3*n**3 + 4*n - 5), n)
5/3
>>> limit_seq(binomial(2*n, n) / Sum(binomial(2*k, k), (k, 1, n)), n)
3/4
>>> limit_seq(Sum(k**2 * Sum(2**m/m, (m, 1, k)), (k, 1, n)) / (2**n*n), n)
4

Admissible Terms

The algorithm is designed for sequences built from rational functions, indefinite sums,
and indefinite products over an indeterminate n. Terms of alternating sign are also
allowed, but more complex oscillatory behavior is not supported.

5.26 Sets

5.26.1 Set

class sympy.sets.sets.Set
The base class for any kind of set.
This is not meant to be used directly as a container of items. It does not behave like the
builtin set; see FiniteSet (page 1171) for that.
Real intervals are represented by the Interval (page 1169) class and unions of sets by
the Union (page 1172) class. The empty set is represented by the EmptySet (page 1175)
class and available as a singleton as S.EmptySet.

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

boundary
The boundary or frontier of a set
A point x is on the boundary of a set S if
1. x is in the closure of S. I.e. Every neighborhood of x contains a point in S.

1162 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

2. x is not in the interior of S. I.e. There does not exist an open set centered on x
contained entirely within S.
There are the points on the outer rim of S. If S is open then these points need not
actually be contained within S.
For example, the boundary of an interval is its start and end points. This is true
regardless of whether or not the interval is open.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).boundary
{0, 1}
>>> Interval(0, 1, True, False).boundary
{0, 1}

closure
Property method which returns the closure of a set. The closure is defined as the
union of the set itself and its boundary.

Examples

>>> from sympy import S, Interval

>>> S.Reals.closure
Reals
>>> Interval(0, 1).closure
Interval(0, 1)

complement(universe)
The complement of ‘self’ w.r.t the given universe.

Examples

>>> from sympy import Interval, S

>>> Interval(0, 1).complement(S.Reals)
Union(Interval.open(-oo, 0), Interval.open(1, oo))

>>> Interval(0, 1).complement(S.UniversalSet)

UniversalSet() \ Interval(0, 1)

contains(other)
Returns True if ‘other’ is contained in ‘self’ as an element.
As a shortcut it is possible to use the ‘in’ operator:

Examples

5.26. Sets 1163

SymPy Documentation, Release 1.3

>>> from sympy import Interval

>>> Interval(0, 1).contains(0.5)
True
>>> 0.5 in Interval(0, 1)
True

inf
The infimum of ‘self’

Examples

>>> from sympy import Interval, Union

>>> Interval(0, 1).inf
0
>>> Union(Interval(0, 1), Interval(2, 3)).inf
0

interior
Property method which returns the interior of a set. The interior of a set S consists
all points of S that do not belong to the boundary of S.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).interior
Interval.open(0, 1)
>>> Interval(0, 1).boundary.interior
EmptySet()

intersect(other)
Returns the intersection of ‘self’ and ‘other’.

>>> from sympy import Interval

>>> Interval(1, 3).intersect(Interval(1, 2))

Interval(1, 2)

>>> from sympy import imageset, Lambda, symbols, S

>>> n, m = symbols('n m')
>>> a = imageset(Lambda(n, 2*n), S.Integers)
>>> a.intersect(imageset(Lambda(m, 2*m + 1), S.Integers))
EmptySet()

intersection(other)
Alias for intersect() (page 1164)
is_closed
A property method to check whether a set is closed. A set is closed if it’s complement
is an open set.

1164 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Interval

>>> Interval(0, 1).is_closed
True

is_disjoint(other)
Returns True if ‘self’ and ‘other’ are disjoint

References

[R498]

Examples

>>> from sympy import Interval

>>> Interval(0, 2).is_disjoint(Interval(1, 2))
False
>>> Interval(0, 2).is_disjoint(Interval(3, 4))
True

is_open
Property method to check whether a set is open. A set is open if and only if it has
an empty intersection with its boundary.

Examples

>>> from sympy import S

>>> S.Reals.is_open
True

is_proper_subset(other)
Returns True if ‘self’ is a proper subset of ‘other’.

Examples

>>> from sympy import Interval

>>> Interval(0, 0.5).is_proper_subset(Interval(0, 1))
True
>>> Interval(0, 1).is_proper_subset(Interval(0, 1))
False

is_proper_superset(other)
Returns True if ‘self’ is a proper superset of ‘other’.

Examples

5.26. Sets 1165

SymPy Documentation, Release 1.3

>>> from sympy import Interval

>>> Interval(0, 1).is_proper_superset(Interval(0, 0.5))
True
>>> Interval(0, 1).is_proper_superset(Interval(0, 1))
False

is_subset(other)
Returns True if ‘self’ is a subset of ‘other’.

Examples

>>> from sympy import Interval

>>> Interval(0, 0.5).is_subset(Interval(0, 1))
True
>>> Interval(0, 1).is_subset(Interval(0, 1, left_open=True))
False

is_superset(other)
Returns True if ‘self’ is a superset of ‘other’.

Examples

>>> from sympy import Interval

>>> Interval(0, 0.5).is_superset(Interval(0, 1))
False
>>> Interval(0, 1).is_superset(Interval(0, 1, left_open=True))
True

isdisjoint(other)
Alias for is_disjoint() (page 1165)
issubset(other)
Alias for is_subset() (page 1166)
issuperset(other)
Alias for is_superset() (page 1166)
measure
The (Lebesgue) measure of ‘self’

Examples

>>> from sympy import Interval, Union

>>> Interval(0, 1).measure
1
>>> Union(Interval(0, 1), Interval(2, 3)).measure
2

powerset()
Find the Power set of ‘self’.

1166 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R499]

Examples

>>> from sympy import FiniteSet, EmptySet

>>> A = EmptySet()
>>> A.powerset()
{EmptySet()}
>>> A = FiniteSet(1, 2)
>>> a, b, c = FiniteSet(1), FiniteSet(2), FiniteSet(1, 2)
>>> A.powerset() == FiniteSet(a, b, c, EmptySet())
True

sup
The supremum of ‘self’

Examples

>>> from sympy import Interval, Union

>>> Interval(0, 1).sup
1
>>> Union(Interval(0, 1), Interval(2, 3)).sup
3

symmetric_difference(other)
Returns symmetric difference of self and other.

References

[R500]

Examples

>>> from sympy import Interval, S

>>> Interval(1, 3).symmetric_difference(S.Reals)
Union(Interval.open(-oo, 1), Interval.open(3, oo))
>>> Interval(1, 10).symmetric_difference(S.Reals)
Union(Interval.open(-oo, 1), Interval.open(10, oo))

>>> from sympy import S, EmptySet

>>> S.Reals.symmetric_difference(EmptySet())
Reals

union(other)
Returns the union of ‘self’ and ‘other’.

5.26. Sets 1167

SymPy Documentation, Release 1.3

Examples

As a shortcut it is possible to use the ‘+’ operator:

>>> from sympy import Interval, FiniteSet

>>> Interval(0, 1).union(Interval(2, 3))
Union(Interval(0, 1), Interval(2, 3))
>>> Interval(0, 1) + Interval(2, 3)
Union(Interval(0, 1), Interval(2, 3))
>>> Interval(1, 2, True, True) + FiniteSet(2, 3)
Union(Interval.Lopen(1, 2), {3})

Similarly it is possible to use the ‘-‘ operator for set differences:

>>> Interval(0, 2) - Interval(0, 1)

Interval.Lopen(1, 2)
>>> Interval(1, 3) - FiniteSet(2)
Union(Interval.Ropen(1, 2), Interval.Lopen(2, 3))

sympy.sets.sets.imageset(*args)
Return an image of the set under transformation f.
If this function can’t compute the image, it returns an unevaluated ImageSet object.

f (x)|x ∈ self

See also:
sympy.sets.fancysets.ImageSet (page 1179)

Examples

>>> from sympy import S, Interval, Symbol, imageset, sin, Lambda

>>> from sympy.abc import x, y

>>> imageset(x, 2*x, Interval(0, 2))

Interval(0, 4)

>>> imageset(lambda x: 2*x, Interval(0, 2))

Interval(0, 4)

>>> imageset(Lambda(x, sin(x)), Interval(-2, 1))

ImageSet(Lambda(x, sin(x)), Interval(-2, 1))

>>> imageset(sin, Interval(-2, 1))

ImageSet(Lambda(x, sin(x)), Interval(-2, 1))
>>> imageset(lambda y: x + y, Interval(-2, 1))
ImageSet(Lambda(_x, _x + x), Interval(-2, 1))

Expressions applied to the set of Integers are simplified to show as few negatives as
possible and linear expressions are converted to a canonical form. If this is not desirable
then the unevaluated ImageSet should be used.

1168 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> imageset(x, -2*x + 5, S.Integers)

ImageSet(Lambda(x, 2*x + 1), Integers)

Elementary Sets

5.26.2 Interval

class sympy.sets.sets.Interval
Represents a real interval as a Set.
Usage: Returns an interval with end points “start” and “end”.
For left_open=True (default left_open is False) the interval will be open on the left.
Similarly, for right_open=True the interval will be open on the right.

Notes

• Only real end points are supported

• Interval(a, b) with a > b will return the empty set
• Use the evalf() method to turn an Interval into an mpmath ‘mpi’ interval instance

References

[R501]

Examples

>>> from sympy import Symbol, Interval

>>> Interval(0, 1)
Interval(0, 1)
>>> Interval.Ropen(0, 1)
Interval.Ropen(0, 1)
>>> Interval.Ropen(0, 1)
Interval.Ropen(0, 1)
>>> Interval.Lopen(0, 1)
Interval.Lopen(0, 1)
>>> Interval.open(0, 1)
Interval.open(0, 1)

>>> a = Symbol('a', real=True)

>>> Interval(0, a)
Interval(0, a)

5.26. Sets 1169

SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

classmethod Lopen(a, b)
Return an interval not including the left boundary.
classmethod Ropen(a, b)
Return an interval not including the right boundary.
as_relational(x)
Rewrite an interval in terms of inequalities and logic operators.
end
The right end point of ‘self’.
This property takes the same value as the ‘sup’ property.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).end
1

is_left_unbounded
Return True if the left endpoint is negative infinity.
is_right_unbounded
Return True if the right endpoint is positive infinity.
left
The left end point of ‘self’.
This property takes the same value as the ‘inf’ property.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).start
0

left_open
True if ‘self’ is left-open.

Examples

1170 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Interval

>>> Interval(0, 1, left_open=True).left_open
True
>>> Interval(0, 1, left_open=False).left_open
False

classmethod open(a, b)
Return an interval including neither boundary.
right
The right end point of ‘self’.
This property takes the same value as the ‘sup’ property.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).end
1

right_open
True if ‘self’ is right-open.

Examples

>>> from sympy import Interval

>>> Interval(0, 1, right_open=True).right_open
True
>>> Interval(0, 1, right_open=False).right_open
False

start
The left end point of ‘self’.
This property takes the same value as the ‘inf’ property.

Examples

>>> from sympy import Interval

>>> Interval(0, 1).start
0

5.26.3 FiniteSet

class sympy.sets.sets.FiniteSet
Represents a finite set of discrete numbers

References

[R502]

5.26. Sets 1171

SymPy Documentation, Release 1.3

Examples

>>> from sympy import FiniteSet

>>> FiniteSet(1, 2, 3, 4)
{1, 2, 3, 4}
>>> 3 in FiniteSet(1, 2, 3, 4)
True

>>> members = [1, 2, 3, 4]

>>> f = FiniteSet(*members)
>>> f
{1, 2, 3, 4}
>>> f - FiniteSet(2)
{1, 3, 4}
>>> f + FiniteSet(2, 5)
{1, 2, 3, 4, 5}

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

as_relational(symbol)
Rewrite a FiniteSet in terms of equalities and logic operators.

Compound Sets

5.26.4 Union

class sympy.sets.sets.Union
Represents a union of sets as a Set (page 1162).
See also:
Intersection (page 1173)

References

[R503]

Examples

>>> from sympy import Union, Interval

>>> Union(Interval(1, 2), Interval(3, 4))
Union(Interval(1, 2), Interval(3, 4))

1172 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The Union constructor will always try to merge overlapping intervals, if possible. For
example:
>>> Union(Interval(1, 2), Interval(2, 3))
Interval(1, 3)

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

as_relational(symbol)
Rewrite a Union in terms of equalities and logic operators.

5.26.5 Intersection

class sympy.sets.sets.Intersection
Represents an intersection of sets as a Set (page 1162).
See also:
Union (page 1172)

References

[R504]

Examples

>>> from sympy import Intersection, Interval

>>> Intersection(Interval(1, 3), Interval(2, 4))
Interval(2, 3)

We often use the .intersect method

>>> Interval(1,3).intersect(Interval(2,4))
Interval(2, 3)

Attributes

is_Complement
is_EmptySet
is_UniversalSet

as_relational(symbol)
Rewrite an Intersection in terms of equalities and logic operators

5.26. Sets 1173

SymPy Documentation, Release 1.3

5.26.6 ProductSet

class sympy.sets.sets.ProductSet
Represents a Cartesian Product of Sets.
Returns a Cartesian product given several sets as either an iterable or individual argu-
ments.
Can use ‘*’ operator on any sets for convenient shorthand.

Notes

• Passes most operations down to the argument sets

• Flattens Products of ProductSets

References

[R505]

Examples

>>> from sympy import Interval, FiniteSet, ProductSet

>>> I = Interval(0, 5); S = FiniteSet(1, 2, 3)
>>> ProductSet(I, S)
Interval(0, 5) x {1, 2, 3}

>>> (2, 2) in ProductSet(I, S)

True

>>> Interval(0, 1) * Interval(0, 1) # The unit square

Interval(0, 1) x Interval(0, 1)

>>> coin = FiniteSet('H', 'T')

>>> set(coin**2)
{(H, H), (H, T), (T, H), (T, T)}

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

is_iterable
A property method which tests whether a set is iterable or not. Returns True if set
is iterable, otherwise returns False.

1174 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import FiniteSet, Interval, ProductSet

>>> I = Interval(0, 1)
>>> A = FiniteSet(1, 2, 3, 4, 5)
>>> I.is_iterable
False
>>> A.is_iterable
True

5.26.7 Complement

class sympy.sets.sets.Complement
Represents the set difference or relative complement of a set with another set.
A − B = {x ∈ A|x
notinB}
See also:
Intersection (page 1173), Union (page 1172)

References

[R506]

Examples

>>> from sympy import Complement, FiniteSet

>>> Complement(FiniteSet(0, 1, 2), FiniteSet(1))
{0, 2}

Attributes

is_EmptySet
is_Intersection
is_UniversalSet

static reduce(A, B)
Simplify a Complement (page 1175).

Singleton Sets

5.26.8 EmptySet

class sympy.sets.sets.EmptySet
Represents the empty set. The empty set is available as a singleton as S.EmptySet.

5.26. Sets 1175

SymPy Documentation, Release 1.3

See also:
UniversalSet (page 1176)

References

[R507]

Examples

>>> from sympy import S, Interval

>>> S.EmptySet
EmptySet()

>>> Interval(1, 2).intersect(S.EmptySet)

EmptySet()

Attributes

is_Complement
is_Intersection
is_UniversalSet

5.26.9 UniversalSet

class sympy.sets.sets.UniversalSet
Represents the set of all things. The universal set is available as a singleton as
S.UniversalSet
See also:
EmptySet (page 1175)

References

[R508]

Examples

>>> from sympy import S, Interval

>>> S.UniversalSet
UniversalSet()

>>> Interval(1, 2).intersect(S.UniversalSet)

Interval(1, 2)

1176 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection

Special Sets

5.26.10 Naturals

class sympy.sets.fancysets.Naturals
Represents the natural numbers (or counting numbers) which are all positive integers
starting from 1. This set is also available as the Singleton, S.Naturals.
See also:

Naturals0 (page 1177) non-negative integers (i.e. includes 0, too)

Integers (page 1178) also includes negative integers

Examples

>>> from sympy import S, Interval, pprint

>>> 5 in S.Naturals
True
>>> iterable = iter(S.Naturals)
>>> next(iterable)
1
>>> next(iterable)
2
>>> next(iterable)
3
>>> pprint(S.Naturals.intersect(Interval(0, 10)))
{1, 2, ..., 10}

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

5.26.11 Naturals0

class sympy.sets.fancysets.Naturals0
Represents the whole numbers which are all the non-negative integers, inclusive of zero.
See also:

5.26. Sets 1177

SymPy Documentation, Release 1.3

Naturals (page 1177) positive integers; does not include 0

Integers (page 1178) also includes the negative integers

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

5.26.12 Integers

class sympy.sets.fancysets.Integers
Represents all integers: positive, negative and zero. This set is also available as the
Singleton, S.Integers.
See also:

Naturals0 (page 1177) non-negative integers

Integers (page 1178) positive and negative integers and zero

Examples

>>> from sympy import S, Interval, pprint

>>> 5 in S.Naturals
True
>>> iterable = iter(S.Integers)
>>> next(iterable)
0
>>> next(iterable)
1
>>> next(iterable)
-1
>>> next(iterable)
2

>>> pprint(S.Integers.intersect(Interval(-4, 4)))

{-4, -3, ..., 4}

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

1178 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.26.13 ImageSet

class sympy.sets.fancysets.ImageSet
Image of a set under a mathematical function. The transformation must be given as a
Lambda function which has as many arguments as the elements of the set upon which
it operates, e.g. 1 argument when acting on the set of integers or 2 arguments when
acting on a complex region.
This function is not normally called directly, but is called from imageset.
See also:
sympy.sets.sets.imageset (page 1168)

Examples

>>> from sympy import Symbol, S, pi, Dummy, Lambda

>>> from sympy.sets.sets import FiniteSet, Interval
>>> from sympy.sets.fancysets import ImageSet

>>> x = Symbol('x')
>>> N = S.Naturals
>>> squares = ImageSet(Lambda(x, x**2), N) # {x**2 for x in N}
>>> 4 in squares
True
>>> 5 in squares
False

>>> FiniteSet(0, 1, 2, 3, 4, 5, 6, 7, 9, 10).intersect(squares)

{1, 4, 9}

>>> square_iterable = iter(squares)

>>> for i in range(4):
... next(square_iterable)
1
4
9
16

If you want to get value for x = 2, 1/2 etc. (Please check whether the x value is in bases et
or not before passing it as args)

>>> squares.lamda(2)
4
>>> squares.lamda(S(1)/2)
1/4

>>> n = Dummy('n')
>>> solutions = ImageSet(Lambda(n, n*pi), S.Integers) # solutions of sin(x) = 0
>>> dom = Interval(-1, 1)
>>> dom.intersect(solutions)
{0}

5.26. Sets 1179

SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

5.26.14 Range

class sympy.sets.fancysets.Range
Represents a range of integers. Can be called as Range(stop), Range(start, stop), or
Range(start, stop, step); when stop is not given it defaults to 1.
Range(stop) is the same as Range(0, stop, 1) and the stop value (juse as for Python ranges)
is not included in the Range values.

>>> from sympy import Range

>>> list(Range(3))
[0, 1, 2]

The step can also be negative:

>>> list(Range(10, 0, -2))

[10, 8, 6, 4, 2]

The stop value is made canonical so equivalent ranges always have the same args:

>>> Range(0, 10, 3)

Range(0, 12, 3)

Infinite ranges are allowed. If the starting point is infinite, then the final value is stop
- step. To iterate such a range, it needs to be reversed:

>>> from sympy import oo

>>> r = Range(-oo, 1)
>>> r[-1]
0
>>> next(iter(r))
Traceback (most recent call last):
...
ValueError: Cannot iterate over Range with infinite start
>>> next(iter(r.reversed))
0

Although Range is a set (and supports the normal set operations) it maintains the order
of the elements and can be used in contexts where range would be used.

>>> from sympy import Interval

>>> Range(0, 10, 2).intersect(Interval(3, 7))
Range(4, 8, 2)
>>> list(_)
[4, 6]

Athough slicing of a Range will always return a Range – possibly empty – an empty set
will be returned from any intersection that is empty:

1180 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> Range(3)[:0]
Range(0, 0, 1)
>>> Range(3).intersect(Interval(4, oo))
EmptySet()
>>> Range(3).intersect(Range(4, oo))
EmptySet()

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

reversed
Return an equivalent Range in the opposite order.

Examples

>>> from sympy import Range

>>> Range(10).reversed
Range(9, -1, -1)

5.26.15 ComplexRegion

class sympy.sets.fancysets.ComplexRegion
Represents the Set of all Complex Numbers. It can represent a region of Complex Plane
in both the standard forms Polar and Rectangular coordinates.
• Polar Form Input is in the form of the ProductSet or Union of ProductSets of the
intervals of r and theta, & use the flag polar=True.
Z = {z in C | z = r*[cos(theta) + I*sin(theta)], r in [r], theta in [theta]}
• Rectangular Form Input is in the form of the ProductSet or Union of ProductSets of
interval of x and y the of the Complex numbers in a Plane. Default input type is in
rectangular form.
Z = {z in C | z = x + I*y, x in [Re(z)], y in [Im(z)]}
See also:
Reals

Examples

>>> from sympy.sets.fancysets import ComplexRegion

>>> from sympy.sets import Interval
>>> from sympy import S, I, Union
(continues on next page)

5.26. Sets 1181

SymPy Documentation, Release 1.3

(continued from previous page)

>>> a = Interval(2, 3)
>>> b = Interval(4, 6)
>>> c = Interval(1, 8)
>>> c1 = ComplexRegion(a*b) # Rectangular Form
>>> c1
ComplexRegion(Interval(2, 3) x Interval(4, 6), False)

• c1 represents the rectangular region in complex plane surrounded by the coordi-

nates (2, 4), (3, 4), (3, 6) and (2, 6), of the four vertices.

>>> c2 = ComplexRegion(Union(a*b, b*c))

>>> c2
ComplexRegion(Union(Interval(2, 3) x Interval(4, 6), Interval(4, 6) x Interval(1,␣
,→8)), False)

• c2 represents the Union of two rectangular regions in complex plane. One of them
surrounded by the coordinates of c1 and other surrounded by the coordinates (4, 1),
(6, 1), (6, 8) and (4, 8).

>>> 2.5 + 4.5*I in c1

True
>>> 2.5 + 6.5*I in c1
False

>>> r = Interval(0, 1)
>>> theta = Interval(0, 2*S.Pi)
>>> c2 = ComplexRegion(r*theta, polar=True) # Polar Form
>>> c2 # unit Disk
ComplexRegion(Interval(0, 1) x Interval.Ropen(0, 2*pi), True)

• c2 represents the region in complex plane inside the Unit Disk centered at the origin.

>>> 0.5 + 0.5*I in c2

True
>>> 1 + 2*I in c2
False

>>> unit_disk = ComplexRegion(Interval(0, 1)*Interval(0, 2*S.Pi), polar=True)

>>> upper_half_unit_disk = ComplexRegion(Interval(0, 1)*Interval(0, S.Pi),␣
,→polar=True)

>>> intersection = unit_disk.intersect(upper_half_unit_disk)

>>> intersection
ComplexRegion(Interval(0, 1) x Interval(0, pi), True)
>>> intersection == upper_half_unit_disk
True

1182 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

is_Complement
is_EmptySet
is_Intersection
is_UniversalSet

a_interval
Return the union of intervals of x when, self is in rectangular form, or the union of
intervals of r when self is in polar form.

Examples

>>> from sympy import Interval, ComplexRegion, Union

>>> a = Interval(2, 3)
>>> b = Interval(4, 5)
>>> c = Interval(1, 7)
>>> C1 = ComplexRegion(a*b)
>>> C1.a_interval
Interval(2, 3)
>>> C2 = ComplexRegion(Union(a*b, b*c))
>>> C2.a_interval
Union(Interval(2, 3), Interval(4, 5))

b_interval
Return the union of intervals of y when, self is in rectangular form, or the union of
intervals of theta when self is in polar form.

Examples

>>> from sympy import Interval, ComplexRegion, Union

>>> a = Interval(2, 3)
>>> b = Interval(4, 5)
>>> c = Interval(1, 7)
>>> C1 = ComplexRegion(a*b)
>>> C1.b_interval
Interval(4, 5)
>>> C2 = ComplexRegion(Union(a*b, b*c))
>>> C2.b_interval
Interval(1, 7)

classmethod from_real(sets)
Converts given subset of real numbers to a complex region.

Examples

>>> from sympy import Interval, ComplexRegion

>>> unit = Interval(0,1)
>>> ComplexRegion.from_real(unit)
ComplexRegion(Interval(0, 1) x {0}, False)

5.26. Sets 1183

SymPy Documentation, Release 1.3

polar
Returns True if self is in polar form.

Examples

>>> from sympy import Interval, ComplexRegion, Union, S

>>> a = Interval(2, 3)
>>> b = Interval(4, 5)
>>> theta = Interval(0, 2*S.Pi)
>>> C1 = ComplexRegion(a*b)
>>> C1.polar
False
>>> C2 = ComplexRegion(a*theta, polar=True)
>>> C2.polar
True

psets
Return a tuple of sets (ProductSets) input of the self.

Examples

>>> from sympy import Interval, ComplexRegion, Union

>>> a = Interval(2, 3)
>>> b = Interval(4, 5)
>>> c = Interval(1, 7)
>>> C1 = ComplexRegion(a*b)
>>> C1.psets
(Interval(2, 3) x Interval(4, 5),)
>>> C2 = ComplexRegion(Union(a*b, b*c))
>>> C2.psets
(Interval(2, 3) x Interval(4, 5), Interval(4, 5) x Interval(1, 7))

sets
Return raw input sets to the self.

Examples

>>> from sympy import Interval, ComplexRegion, Union

>>> a = Interval(2, 3)
>>> b = Interval(4, 5)
>>> c = Interval(1, 7)
>>> C1 = ComplexRegion(a*b)
>>> C1.sets
Interval(2, 3) x Interval(4, 5)
>>> C2 = ComplexRegion(Union(a*b, b*c))
>>> C2.sets
Union(Interval(2, 3) x Interval(4, 5), Interval(4, 5) x Interval(1, 7))

sympy.sets.fancysets.normalize_theta_set(theta)
Normalize a Real Set theta in the Interval [0, 2*pi). It returns a normalized value of theta
in the Set. For Interval, a maximum of one cycle [0, 2*pi], is returned i.e. for theta equal
to [0, 10*pi], returned normalized value would be [0, 2*pi). As of now intervals with end
points as non-multiples of pi is not supported.

1184 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Raises NotImplementedError
The algorithms for Normalizing theta Set are not yet implemented.
ValueError
The input is not valid, i.e. the input is not a real set.
RuntimeError
It is a bug, please report to the github issue tracker.

Examples

>>> from sympy.sets.fancysets import normalize_theta_set

>>> from sympy import Interval, FiniteSet, pi
>>> normalize_theta_set(Interval(9*pi/2, 5*pi))
Interval(pi/2, pi)
>>> normalize_theta_set(Interval(-3*pi/2, pi/2))
Interval.Ropen(0, 2*pi)
>>> normalize_theta_set(Interval(-pi/2, pi/2))
Union(Interval(0, pi/2), Interval.Ropen(3*pi/2, 2*pi))
>>> normalize_theta_set(Interval(-4*pi, 3*pi))
Interval.Ropen(0, 2*pi)
>>> normalize_theta_set(Interval(-3*pi/2, -pi/2))
Interval(pi/2, 3*pi/2)
>>> normalize_theta_set(FiniteSet(0, pi, 3*pi))
{0, pi}

5.27 Simplify

5.27.1 simplify

sympy.simplify.simplify.simplify(expr, ratio=1.7, measure=<function

count_ops>, rational=False, inverse=False)
Simplifies the given expression.
Simplification is not a well defined term and the exact strategies this function tries can
change in the future versions of SymPy. If your algorithm relies on “simplification”
(whatever it is), try to determine what you need exactly - is it powsimp()?, radsimp()?,
together()?, logcombine()?, or something else? And use this particular function directly,
because those are well defined and thus your algorithm will be robust.
Nonetheless, especially for interactive use, or when you don’t know anything about the
structure of the expression, simplify() tries to apply intelligent heuristics to make the
input expression “simpler”. For example:

>>> from sympy import simplify, cos, sin

>>> from sympy.abc import x, y
>>> a = (x + x**2)/(x*sin(y)**2 + x*cos(y)**2)
>>> a
(x**2 + x)/(x*sin(y)**2 + x*cos(y)**2)
>>> simplify(a)
x + 1

5.27. Simplify 1185

SymPy Documentation, Release 1.3

Note that we could have obtained the same result by using specific simplification func-
tions:

>>> from sympy import trigsimp, cancel

>>> trigsimp(a)
(x**2 + x)/x
>>> cancel(_)
x + 1

In some cases, applying simplify() (page 1185) may actually result in some more com-
plicated expression. The default ratio=1.7 prevents more extreme cases: if (result
length)/(input length) > ratio, then input is returned unmodified. The measure parame-
ter lets you specify the function used to determine how complex an expression is. The
function should take a single argument as an expression and return a number such that
if expression a is more complex than expression b, then measure(a) > measure(b). The
default measure function is count_ops(), which returns the total number of operations
in the expression.
For example, if ratio=1, simplify output can’t be longer than input.

>>> from sympy import sqrt, simplify, count_ops, oo

>>> root = 1/(sqrt(2)+3)

Since simplify(root) would result in a slightly longer expression, root is returned un-
changed instead:

>>> simplify(root, ratio=1) == root

True

If ratio=oo, simplify will be applied anyway:

>>> count_ops(simplify(root, ratio=oo)) > count_ops(root)

True

Note that the shortest expression is not necessary the simplest, so setting ratio to 1 may
not be a good idea. Heuristically, the default value ratio=1.7 seems like a reasonable
choice.
You can easily define your own measure function based on what you feel should represent
the “size” or “complexity” of the input expression. Note that some choices, such as
lambda expr: len(str(expr)) may appear to be good metrics, but have other problems
(in this case, the measure function may slow down simplify too much for very large
expressions). If you don’t know what a good metric would be, the default, count_ops, is
a good one.
For example:

>>> from sympy import symbols, log

>>> a, b = symbols('a b', positive=True)
>>> g = log(a) + log(b) + log(a)*log(1/b)
>>> h = simplify(g)
>>> h
log(a*b**(-log(a) + 1))
>>> count_ops(g)
8
>>> count_ops(h)
5

1186 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

So you can see that h is simpler than g using the count_ops metric. However, we may not
like how simplify (in this case, using logcombine) has created the b**(log(1/a) + 1)
term. A simple way to reduce this would be to give more weight to powers as operations
in count_ops. We can do this by using the visual=True option:

>>> print(count_ops(g, visual=True))

2*ADD + DIV + 4*LOG + MUL
>>> print(count_ops(h, visual=True))
2*LOG + MUL + POW + SUB

>>> from sympy import Symbol, S

>>> def my_measure(expr):
... POW = Symbol('POW')
... # Discourage powers by giving POW a weight of 10
... count = count_ops(expr, visual=True).subs(POW, 10)
... # Every other operation gets a weight of 1 (the default)
... count = count.replace(Symbol, type(S.One))
... return count
>>> my_measure(g)
8
>>> my_measure(h)
14
>>> 15./8 > 1.7 # 1.7 is the default ratio
True
>>> simplify(g, measure=my_measure)
-log(a)*log(b) + log(a) + log(b)

Note that because simplify() internally tries many different simplification strategies
and then compares them using the measure function, we get a completely different result
that is still different from the input expression by doing this.
If rational=True, Floats will be recast as Rationals before simplification. If ratio-
nal=None, Floats will be recast as Rationals but the result will be recast as Floats. If
rational=False(default) then nothing will be done to the Floats.
If inverse=True, it will be assumed that a composition of inverse functions, such as sin
and asin, can be cancelled in any order. For example, asin(sin(x)) will yield x without
checking whether x belongs to the set where this relation is true. The default is False.

5.27.2 separatevars

sympy.simplify.simplify.separatevars(expr, symbols=[], dict=False, force=False)

Separates variables in an expression, if possible. By default, it separates with respect to
all symbols in an expression and collects constant coefficients that are independent of
symbols.
If dict=True then the separated terms will be returned in a dictionary keyed to their
corresponding symbols. By default, all symbols in the expression will appear as keys; if
symbols are provided, then all those symbols will be used as keys, and any terms in the
expression containing other symbols or non-symbols will be returned keyed to the string
‘coeff’. (Passing None for symbols will return the expression in a dictionary keyed to
‘coeff’.)
If force=True, then bases of powers will be separated regardless of assumptions on the
symbols involved.

5.27. Simplify 1187

SymPy Documentation, Release 1.3

Notes

The order of the factors is determined by Mul, so that the separated expressions may
not necessarily be grouped together.
Although factoring is necessary to separate variables in some expressions, it is not nec-
essary in all cases, so one should not count on the returned factors being factored.

Examples

>>> from sympy.abc import x, y, z, alpha

>>> from sympy import separatevars, sin
>>> separatevars((x*y)**y)
(x*y)**y
>>> separatevars((x*y)**y, force=True)
x**y*y**y

>>> e = 2*x**2*z*sin(y)+2*z*x**2
>>> separatevars(e)
2*x**2*z*(sin(y) + 1)
>>> separatevars(e, symbols=(x, y), dict=True)
{'coeff': 2*z, x: x**2, y: sin(y) + 1}
>>> separatevars(e, [x, y, alpha], dict=True)
{'coeff': 2*z, alpha: 1, x: x**2, y: sin(y) + 1}

If the expression is not really separable, or is only partially separable, separatevars will
do the best it can to separate it by using factoring.

>>> separatevars(x + x*y - 3*x**2)

-x*(3*x - y - 1)

If the expression is not separable then expr is returned unchanged or (if dict=True) then
None is returned.

>>> eq = 2*x + y*sin(x)

>>> separatevars(eq) == eq
True
>>> separatevars(2*x + y*sin(x), symbols=(x, y), dict=True) == None
True

5.27.3 nthroot

sympy.simplify.simplify.nthroot(expr, n, max_len=4, prec=15)

compute a real nth-root of a sum of surds
Parameters expr : sum of surds
n : integer
max_len : maximum number of surds passed as constants to nsimplify

1188 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.simplify.simplify import nthroot

>>> from sympy import Rational, sqrt
>>> nthroot(90 + 34*sqrt(7), 3)
sqrt(7) + 3

Algorithm

First nsimplify is used to get a candidate root; if it is not a root the minimal polynomial
is computed; the answer is one of its roots.

5.27.4 besselsimp

sympy.simplify.simplify.besselsimp(expr)
Simplify bessel-type functions.
This routine tries to simplify bessel-type functions. Currently it only works on the Bessel J
and I functions, however. It works by looking at all such functions in turn, and eliminating
factors of “I” and “-1” (actually their polar equivalents) in front of the argument. Then,
functions of half-integer order are rewritten using strigonometric functions and functions
of integer order (> 1) are rewritten using functions of low order. Finally, if the expression
was changed, compute factorization of the result with factor().

>>> from sympy import besselj, besseli, besselsimp, polar_lift, I, S

>>> from sympy.abc import z, nu
>>> besselsimp(besselj(nu, z*polar_lift(-1)))
exp(I*pi*nu)*besselj(nu, z)
>>> besselsimp(besseli(nu, z*polar_lift(-I)))
exp(-I*pi*nu/2)*besselj(nu, z)
>>> besselsimp(besseli(S(-1)/2, z))
sqrt(2)*cosh(z)/(sqrt(pi)*sqrt(z))
>>> besselsimp(z*besseli(0, z) + z*(besseli(2, z))/2 + besseli(1, z))
3*z*besseli(0, z)/2

5.27.5 hypersimp

sympy.simplify.simplify.hypersimp(f, k)
Given combinatorial term f(k) simplify its consecutive term ratio i.e. f(k+1)/f(k). The
input term can be composed of functions and integer sequences which have equivalent
representation in terms of gamma special function.
The algorithm performs three basic steps:
1. Rewrite all functions in terms of gamma, if possible.
2. Rewrite all occurrences of gamma in terms of products of gamma and rising factorial
with integer, absolute constant exponent.
3. Perform simplification of nested fractions, powers and if the resulting expression is
a quotient of polynomials, reduce their total degree.

5.27. Simplify 1189

SymPy Documentation, Release 1.3

If f(k) is hypergeometric then as result we arrive with a quotient of polynomials of mini-

mal degree. Otherwise None is returned.
For more information on the implemented algorithm refer to:
1. W. Koepf, Algorithms for m-fold Hypergeometric Summation, Journal of Symbolic
Computation (1995) 20, 399-417

5.27.6 hypersimilar

sympy.simplify.simplify.hypersimilar(f, g, k)
Returns True if ‘f’ and ‘g’ are hyper-similar.
Similarity in hypergeometric sense means that a quotient of f(k) and g(k) is a rational
function in k. This procedure is useful in solving recurrence relations.
For more information see hypersimp().

5.27.7 nsimplify

sympy.simplify.simplify.nsimplify(expr, constants=(), tolerance=None,

full=False, rational=None, ratio-
nal_conversion=’base10’)
Find a simple representation for a number or, if there are free symbols or if ratio-
nal=True, then replace Floats with their Rational equivalents. If no change is made
and rational is not False then Floats will at least be converted to Rationals.
For numerical expressions, a simple formula that numerically matches the given numer-
ical expression is sought (and the input should be possible to evalf to a precision of at
least 30 digits).
Optionally, a list of (rationally independent) constants to include in the formula may be
given.
A lower tolerance may be set to find less exact matches. If no tolerance is given then the
least precise value will set the tolerance (e.g. Floats default to 15 digits of precision, so
would be tolerance=10**-15).
With full=True, a more extensive search is performed (this is useful to find simpler num-
bers when the tolerance is set low).
When converting to rational, if rational_conversion=’base10’ (the default), then con-
vert floats to rationals using their base-10 (string) representation. When ratio-
nal_conversion=’exact’ it uses the exact, base-2 representation.
See also:
sympy.core.function.nfloat (page 202)

Examples

>>> from sympy import nsimplify, sqrt, GoldenRatio, exp, I, exp, pi

>>> nsimplify(4/(1+sqrt(5)), [GoldenRatio])
-2 + 2*GoldenRatio
>>> nsimplify((1/(exp(3*pi*I/5)+1)))
(continues on next page)

1190 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

1/2 - I*sqrt(sqrt(5)/10 + 1/4)
>>> nsimplify(I**I, [pi])
exp(-pi/2)
>>> nsimplify(pi, tolerance=0.01)
22/7

>>> nsimplify(0.333333333333333, rational=True, rational_conversion='exact')

6004799503160655/18014398509481984
>>> nsimplify(0.333333333333333, rational=True)
1/3

5.27.8 posify

sympy.simplify.simplify.posify(eq)
Return eq (with generic symbols made positive) and a dictionary containing the mapping
between the old and new symbols.
Any symbol that has positive=None will be replaced with a positive dummy symbol hav-
ing the same name. This replacement will allow more symbolic processing of expres-
sions, especially those involving powers and logarithms.
A dictionary that can be sent to subs to restore eq to its original symbols is also returned.

>>> from sympy import posify, Symbol, log, solve

>>> from sympy.abc import x
>>> posify(x + Symbol('p', positive=True) + Symbol('n', negative=True))
(_x + n + p, {_x: x})

>>> eq = 1/x
>>> log(eq).expand()
log(1/x)
>>> log(posify(eq)[0]).expand()
-log(_x)
>>> p, rep = posify(eq)
>>> log(p).expand().subs(rep)
-log(x)

It is possible to apply the same transformations to an iterable of expressions:

>>> eq = x**2 - 4
>>> solve(eq, x)
[-2, 2]
>>> eq_x, reps = posify([eq, x]); eq_x
[_x**2 - 4, _x]
>>> solve(*eq_x)
[2]

5.27.9 logcombine

sympy.simplify.simplify.logcombine(expr, force=False)
Takes logarithms and combines them using the following rules:
• log(x) + log(y) == log(x*y) if both are not negative

5.27. Simplify 1191

SymPy Documentation, Release 1.3

• a*log(x) == log(x**a) if x is positive and a is real

If force is True then the assumptions above will be assumed to hold if there is no as-
sumption already in place on a quantity. For example, if a is imaginary or the argument
negative, force will not perform a combination but if a is a symbol with no assumptions
the change will take place.
See also:

posify (page 1191) replace all symbols with symbols having positive assumptions
sympy.core.function.expand_log (page 199) expand the logarithms of products and
powers; the opposite of logcombine

Examples

>>> from sympy import Symbol, symbols, log, logcombine, I

>>> from sympy.abc import a, x, y, z
>>> logcombine(a*log(x) + log(y) - log(z))
a*log(x) + log(y) - log(z)
>>> logcombine(a*log(x) + log(y) - log(z), force=True)
log(x**a*y/z)
>>> x,y,z = symbols('x,y,z', positive=True)
>>> a = Symbol('a', real=True)
>>> logcombine(a*log(x) + log(y) - log(z))
log(x**a*y/z)

The transformation is limited to factors and/or terms that contain logs, so the result
depends on the initial state of expansion:

>>> eq = (2 + 3*I)*log(x)
>>> logcombine(eq, force=True) == eq
True
>>> logcombine(eq.expand(), force=True)
log(x**2) + I*log(x**3)

5.27.10 Radsimp

radsimp

sympy.simplify.radsimp.radsimp(expr, symbolic=True, max_terms=4)

Rationalize the denominator by removing square roots.
Note: the expression returned from radsimp must be used with caution since if the de-
nominator contains symbols, it will be possible to make substitutions that violate the as-
sumptions of the simplification process: that for a denominator matching a + b*sqrt(c),
a != +/-b*sqrt(c). (If there are no symbols, this assumptions is made valid by collecting
terms of sqrt(c) so the match variable a does not contain sqrt(c).) If you do not want
the simplification to occur for symbolic denominators, set symbolic to False.
If there are more than max_terms radical terms then the expression is returned un-
changed.

1192 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import radsimp, sqrt, Symbol, denom, pprint, I

>>> from sympy import factor_terms, fraction, signsimp
>>> from sympy.simplify.radsimp import collect_sqrt
>>> from sympy.abc import a, b, c

>>> radsimp(1/(2 + sqrt(2)))

(-sqrt(2) + 2)/2
>>> x,y = map(Symbol, 'xy')
>>> e = ((2 + 2*sqrt(2))*x + (2 + sqrt(8))*y)/(2 + sqrt(2))
>>> radsimp(e)
sqrt(2)*(x + y)

No simplification beyond removal of the gcd is done. One might want to polish the result
a little, however, by collecting square root terms:

>>> r2 = sqrt(2)
>>> r5 = sqrt(5)
>>> ans = radsimp(1/(y*r2 + x*r2 + a*r5 + b*r5)); pprint(ans)
___ ___ ___ ___
\/ 5 *a + \/ 5 *b - \/ 2 *x - \/ 2 *y
------------------------------------------
2 2 2 2
5*a + 10*a*b + 5*b - 2*x - 4*x*y - 2*y

>>> n, d = fraction(ans)
>>> pprint(factor_terms(signsimp(collect_sqrt(n))/d, radical=True))
___ ___
\/ 5 *(a + b) - \/ 2 *(x + y)
------------------------------------------
2 2 2 2
5*a + 10*a*b + 5*b - 2*x - 4*x*y - 2*y

If radicals in the denominator cannot be removed or there is no denominator, the original

expression will be returned.

>>> radsimp(sqrt(2)*x + sqrt(2))

sqrt(2)*x + sqrt(2)

Results with symbols will not always be valid for all substitutions:

>>> eq = 1/(a + b*sqrt(c))

>>> eq.subs(a, b*sqrt(c))
1/(2*b*sqrt(c))
>>> radsimp(eq).subs(a, b*sqrt(c))
nan

If symbolic=False, symbolic denominators will not be transformed (but numeric denom-

inators will still be processed):

>>> radsimp(eq, symbolic=False)

1/(a + b*sqrt(c))

5.27. Simplify 1193

SymPy Documentation, Release 1.3

rad_rationalize

sympy.simplify.radsimp.rad_rationalize(num, den)
Rationalize num/den by removing square roots in the denominator; num and den are
sum of terms whose squares are rationals

Examples

>>> from sympy import sqrt

>>> from sympy.simplify.radsimp import rad_rationalize
>>> rad_rationalize(sqrt(3), 1 + sqrt(2)/3)
(-sqrt(3) + sqrt(6)/3, -7/9)

collect

sympy.simplify.radsimp.collect(expr, syms, func=None, evaluate=None, ex-

act=False, distribute_order_term=True)
Collect additive terms of an expression.
This function collects additive terms of an expression with respect to a list of expression
up to powers with rational exponents. By the term symbol here are meant arbitrary
expressions, which can contain powers, products, sums etc. In other words symbol is a
pattern which will be searched for in the expression’s terms.
The input expression is not expanded by collect() (page 1194), so user is expected
to provide an expression is an appropriate form. This makes collect() (page 1194)
more predictable as there is no magic happening behind the scenes. However, it is
important to note, that powers of products are converted to products of powers using
the expand_power_base() function.
There are two possible types of output. First, if evaluate flag is set, this function will
return an expression with collected terms or else it will return a dictionary with expres-
sions up to rational powers as keys and collected coefficients as values.
See also:
collect_const (page 1197), collect_sqrt (page 1197), rcollect (page 1196)

Examples

>>> from sympy import S, collect, expand, factor, Wild

>>> from sympy.abc import a, b, c, x, y, z

This function can collect symbolic coefficients in polynomials or rational expressions. It

will manage to find all integer or rational powers of collection variable:

>>> collect(a*x**2 + b*x**2 + a*x - b*x + c, x)

c + x**2*(a + b) + x*(a - b)

The same result can be achieved in dictionary form:

1194 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> d = collect(a*x**2 + b*x**2 + a*x - b*x + c, x, evaluate=False)

>>> d[x**2]
a + b
>>> d[x]
a - b
>>> d[S.One]
c

You can also work with multivariate polynomials. However, remember that this function
is greedy so it will care only about a single symbol at time, in specification order:

>>> collect(x**2 + y*x**2 + x*y + y + a*y, [x, y])

x**2*(y + 1) + x*y + y*(a + 1)

Also more complicated expressions can be used as patterns:

>>> from sympy import sin, log

>>> collect(a*sin(2*x) + b*sin(2*x), sin(2*x))
(a + b)*sin(2*x)

>>> collect(a*x*log(x) + b*(x*log(x)), x*log(x))

x*(a + b)*log(x)

You can use wildcards in the pattern:

>>> w = Wild('w1')
>>> collect(a*x**y - b*x**y, w**y)
x**y*(a - b)

It is also possible to work with symbolic powers, although it has more complicated be-
havior, because in this case power’s base and symbolic part of the exponent are treated
as a single symbol:

>>> collect(a*x**c + b*x**c, x)

a*x**c + b*x**c
>>> collect(a*x**c + b*x**c, x**c)
x**c*(a + b)

However if you incorporate rationals to the exponents, then you will get well known
behavior:

>>> collect(a*x**(2*c) + b*x**(2*c), x**c)

x**(2*c)*(a + b)

Note also that all previously stated facts about collect() (page 1194) function apply to
the exponential function, so you can get:

>>> from sympy import exp

>>> collect(a*exp(2*x) + b*exp(2*x), exp(x))
(a + b)*exp(2*x)

If you are interested only in collecting specific powers of some symbols then set exact
flag in arguments:

>>> collect(a*x**7 + b*x**7, x, exact=True)

a*x**7 + b*x**7
(continues on next page)

5.27. Simplify 1195

SymPy Documentation, Release 1.3

(continued from previous page)

>>> collect(a*x**7 + b*x**7, x**7, exact=True)
x**7*(a + b)

You can also apply this function to differential equations, where derivatives of arbitrary
order can be collected. Note that if you collect with respect to a function or a derivative
of a function, all derivatives of that function will also be collected. Use exact=True to
prevent this from happening:

>>> from sympy import Derivative as D, collect, Function

>>> f = Function('f') (x)

>>> collect(a*D(f,x) + b*D(f,x), D(f,x))

(a + b)*Derivative(f(x), x)

>>> collect(a*D(D(f,x),x) + b*D(D(f,x),x), f)

(a + b)*Derivative(f(x), (x, 2))

>>> collect(a*D(D(f,x),x) + b*D(D(f,x),x), D(f,x), exact=True)

a*Derivative(f(x), (x, 2)) + b*Derivative(f(x), (x, 2))

>>> collect(a*D(f,x) + b*D(f,x) + a*f + b*f, f)

(a + b)*f(x) + (a + b)*Derivative(f(x), x)

Or you can even match both derivative order and exponent at the same time:

>>> collect(a*D(D(f,x),x)**2 + b*D(D(f,x),x)**2, D(f,x))

(a + b)*Derivative(f(x), (x, 2))**2

Finally, you can apply a function to each of the collected coefficients. For example you
can factorize symbolic coefficients of polynomial:

>>> f = expand((x + a + 1)**3)

>>> collect(f, x, factor)

x**3 + 3*x**2*(a + 1) + 3*x*(a + 1)**2 + (a + 1)**3

Note: Arguments are expected to be in expanded form, so you might have to call
expand() prior to calling this function.

sympy.simplify.radsimp.rcollect(expr, *vars)
Recursively collect sums in an expression.
See also:
collect (page 1194), collect_const (page 1197), collect_sqrt (page 1197)

Examples

>>> from sympy.simplify import rcollect

>>> from sympy.abc import x, y

>>> expr = (x**2*y + x*y + x + y)/(x + y)

1196 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> rcollect(expr, y)
(x + y*(x**2 + x + 1))/(x + y)

collect_sqrt

sympy.simplify.radsimp.collect_sqrt(expr, evaluate=None)
Return expr with terms having common square roots collected together. If evaluate
is False a count indicating the number of sqrt-containing terms will be returned and, if
non-zero, the terms of the Add will be returned, else the expression itself will be returned
as a single term. If evaluate is True, the expression with any collected terms will be
returned.
Note: since I = sqrt(-1), it is collected, too.
See also:
collect (page 1194), collect_const (page 1197), rcollect (page 1196)

Examples

>>> from sympy import sqrt

>>> from sympy.simplify.radsimp import collect_sqrt
>>> from sympy.abc import a, b

>>> r2, r3, r5 = [sqrt(i) for i in [2, 3, 5]]

>>> collect_sqrt(a*r2 + b*r2)
sqrt(2)*(a + b)
>>> collect_sqrt(a*r2 + b*r2 + a*r3 + b*r3)
sqrt(2)*(a + b) + sqrt(3)*(a + b)
>>> collect_sqrt(a*r2 + b*r2 + a*r3 + b*r5)
sqrt(3)*a + sqrt(5)*b + sqrt(2)*(a + b)

If evaluate is False then the arguments will be sorted and returned as a list and a count
of the number of sqrt-containing terms will be returned:

>>> collect_sqrt(a*r2 + b*r2 + a*r3 + b*r5, evaluate=False)

((sqrt(3)*a, sqrt(5)*b, sqrt(2)*(a + b)), 3)
>>> collect_sqrt(a*sqrt(2) + b, evaluate=False)
((b, sqrt(2)*a), 1)
>>> collect_sqrt(a + b, evaluate=False)
((a + b,), 0)

collect_const

sympy.simplify.radsimp.collect_const(expr, *vars, **kwargs)

A non-greedy collection of terms with similar number coefficients in an Add expr. If
vars is given then only those constants will be targeted. Although any Number can also
be targeted, if this is not desired set Numbers=False and no Float or Rational will be
collected.
Parameters expr : sympy expression

5.27. Simplify 1197

SymPy Documentation, Release 1.3

This parameter defines the expression the expression from which

terms with similar coefficients are to be collected. A non-Add ex-
pression is returned as it is.
vars : variable length collection of Numbers, optional
Specifies the constants to target for collection. Can be multiple in
number.
kwargs : Numbers is the only possible argument to pass.
Numbers (default=True) specifies to target all instance of sympy.
core.numbers.Number (page 142) class. If Numbers=False, then no
Float or Rational will be collected.
Returns expr : Expr
Returns an expression with similar coefficient terms collected.
See also:
collect (page 1194), collect_sqrt (page 1197), rcollect (page 1196)

Examples

>>> from sympy import sqrt

>>> from sympy.abc import a, s, x, y, z
>>> from sympy.simplify.radsimp import collect_const
>>> collect_const(sqrt(3) + sqrt(3)*(1 + sqrt(2)))
sqrt(3)*(sqrt(2) + 2)
>>> collect_const(sqrt(3)*s + sqrt(7)*s + sqrt(3) + sqrt(7))
(sqrt(3) + sqrt(7))*(s + 1)
>>> s = sqrt(2) + 2
>>> collect_const(sqrt(3)*s + sqrt(3) + sqrt(7)*s + sqrt(7))
(sqrt(2) + 3)*(sqrt(3) + sqrt(7))
>>> collect_const(sqrt(3)*s + sqrt(3) + sqrt(7)*s + sqrt(7), sqrt(3))
sqrt(7) + sqrt(3)*(sqrt(2) + 3) + sqrt(7)*(sqrt(2) + 2)

The collection is sign-sensitive, giving higher precedence to the unsigned values:

>>> collect_const(x - y - z)
x - (y + z)
>>> collect_const(-y - z)
-(y + z)
>>> collect_const(2*x - 2*y - 2*z, 2)
2*(x - y - z)
>>> collect_const(2*x - 2*y - 2*z, -2)
2*x - 2*(y + z)

fraction

sympy.simplify.radsimp.fraction(expr, exact=False)
Returns a pair with expression’s numerator and denominator. If the given expression is
not a fraction then this function will return the tuple (expr, 1).
This function will not make any attempt to simplify nested fractions or to do any term
rewriting at all.

1198 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If only one of the numerator/denominator pair is needed then use numer(expr) or de-
nom(expr) functions respectively.

>>> from sympy import fraction, Rational, Symbol

>>> from sympy.abc import x, y

>>> fraction(x/y)
(x, y)
>>> fraction(x)
(x, 1)

>>> fraction(1/y**2)
(1, y**2)

>>> fraction(x*y/2)
(x*y, 2)
>>> fraction(Rational(1, 2))
(1, 2)

This function will also work fine with assumptions:

>>> k = Symbol('k', negative=True)

>>> fraction(x * y**k)
(x, y**(-k))

If we know nothing about sign of some exponent and ‘exact’ flag is unset, then structure
this exponent’s structure will be analyzed and pretty fraction will be returned:

>>> from sympy import exp, Mul

>>> fraction(2*x**(-y))
(2, x**y)

>>> fraction(exp(-x))
(1, exp(x))

>>> fraction(exp(-x), exact=True)

(exp(-x), 1)

The exact flag will also keep any unevaluated Muls from being evaluated:

>>> u = Mul(2, x + 1, evaluate=False)

>>> fraction(u)
(2*x + 2, 1)
>>> fraction(u, exact=True)
(2*(x + 1), 1)

5.27.11 Ratsimp

ratsimp

sympy.simplify.ratsimp.ratsimp(expr)
Put an expression over a common denominator, cancel and reduce.

5.27. Simplify 1199

SymPy Documentation, Release 1.3

Examples

>>> from sympy import ratsimp

>>> from sympy.abc import x, y
>>> ratsimp(1/x + 1/y)
(x + y)/(x*y)

5.27.12 Trigonometric simplification

trigsimp

sympy.simplify.trigsimp.trigsimp(expr, **opts)
reduces expression by using known trig identities

Notes

method: - Determine the method to use. Valid choices are ‘matching’ (default), ‘groeb-
ner’, ‘combined’, and ‘fu’. If ‘matching’, simplify the expression recursively by targeting
common patterns. If ‘groebner’, apply an experimental groebner basis algorithm. In this
case further options are forwarded to trigsimp_groebner, please refer to its docstring.
If ‘combined’, first run the groebner basis algorithm with small default parameters, then
run the ‘matching’ algorithm. ‘fu’ runs the collection of trigonometric transformations
described by Fu, et al. (see the f u docstring).

Examples

>>> from sympy import trigsimp, sin, cos, log

>>> from sympy.abc import x, y
>>> e = 2*sin(x)**2 + 2*cos(x)**2
>>> trigsimp(e)
2

Simplification occurs wherever trigonometric functions are located.

>>> trigsimp(log(e))
log(2)

Using method = ”groebner” (or ”combined”) might lead to greater simplification.

The old trigsimp routine can be accessed as with method ‘old’.

>>> from sympy import coth, tanh

>>> t = 3*tanh(x)**7 - 2/coth(x)**7
>>> trigsimp(t, method='old') == t
True
>>> trigsimp(t)
tanh(x)**7

1200 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.27.13 Power simplification

powsimp

sympy.simplify.powsimp.powsimp(expr, deep=False, combine=’all’, force=False,

measure=<function count_ops>)
reduces expression by combining powers with similar bases and exponents.

Notes

If deep is True then powsimp() will also simplify arguments of functions. By default deep
is set to False.
If force is True then bases will be combined without checking for assumptions, e.g.
sqrt(x)*sqrt(y) -> sqrt(x*y) which is not true if x and y are both negative.
You can make powsimp() only combine bases or only combine exponents by changing
combine=’base’ or combine=’exp’. By default, combine=’all’, which does both. com-
bine=’base’ will only combine:

a a a 2x x
x * y => (x*y) as well as things like 2 => 4

and combine=’exp’ will only combine

a b (a + b)
x * x => x

combine=’exp’ will strictly only combine exponents in the way that used to be automatic.
Also use deep=True if you need the old behavior.
When combine=’all’, ‘exp’ is evaluated first. Consider the first example below for when
there could be an ambiguity relating to this. This is done so things like the second
example can be completely combined. If you want ‘base’ combined first, do something
like powsimp(powsimp(expr, combine=’base’), combine=’exp’).

Examples

>>> from sympy import powsimp, exp, log, symbols

>>> from sympy.abc import x, y, z, n
>>> powsimp(x**y*x**z*y**z, combine='all')
x**(y + z)*y**z
>>> powsimp(x**y*x**z*y**z, combine='exp')
x**(y + z)*y**z
>>> powsimp(x**y*x**z*y**z, combine='base', force=True)
x**y*(x*y)**z

>>> powsimp(x**z*x**y*n**z*n**y, combine='all', force=True)

(n*x)**(y + z)
>>> powsimp(x**z*x**y*n**z*n**y, combine='exp')
n**(y + z)*x**(y + z)
>>> powsimp(x**z*x**y*n**z*n**y, combine='base', force=True)
(n*x)**y*(n*x)**z

5.27. Simplify 1201

SymPy Documentation, Release 1.3

>>> x, y = symbols('x y', positive=True)

>>> powsimp(log(exp(x)*exp(y)))
log(exp(x)*exp(y))
>>> powsimp(log(exp(x)*exp(y)), deep=True)
x + y

Radicals with Mul bases will be combined if combine=’exp’

>>> from sympy import sqrt, Mul

>>> x, y = symbols('x y')

Two radicals are automatically joined through Mul:

>>> a=sqrt(x*sqrt(y))
>>> a*a**3 == a**4
True

But if an integer power of that radical has been autoexpanded then Mul does not join
the resulting factors:

>>> a**4 # auto expands to a Mul, no longer a Pow

x**2*y
>>> _*a # so Mul doesn't combine them
x**2*y*sqrt(x*sqrt(y))
>>> powsimp(_) # but powsimp will
(x*sqrt(y))**(5/2)
>>> powsimp(x*y*a) # but won't when doing so would violate assumptions
x*y*sqrt(x*sqrt(y))

powdenest

sympy.simplify.powsimp.powdenest(eq, force=False, polar=False)

Collect exponents on powers as assumptions allow.
Given (bb**be)**e, this can be simplified as follows:
• if bb is positive, or
• e is an integer, or
• |be| < 1 then this simplifies to bb**(be*e)
Given a product of powers raised to a power, (bb1**be1 * bb2**be2...)**e, simplifi-
cation can be done as follows:
• if e is positive, the gcd of all bei can be joined with e;
• all non-negative bb can be separated from those that are negative and their gcd can
be joined with e; autosimplification already handles this separation.
• integer factors from powers that have integers in the denominator of the exponent
can be removed from any term and the gcd of such integers can be joined with e
Setting force to True will make symbols that are not explicitly negative behave as though
they are positive, resulting in more denesting.
Setting polar to True will do simplifications on the Riemann surface of the logarithm,
also resulting in more denestings.

1202 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

When there are sums of logs in exp() then a product of powers may be obtained e.g.
exp(3*(log(a) + 2*log(b))) - > a**3*b**6.

Examples

>>> from sympy.abc import a, b, x, y, z

>>> from sympy import Symbol, exp, log, sqrt, symbols, powdenest

>>> powdenest((x**(2*a/3))**(3*x))
(x**(2*a/3))**(3*x)
>>> powdenest(exp(3*x*log(2)))
2**(3*x)

Assumptions may prevent expansion:

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

>>> p = symbols('p', positive=True)

>>> powdenest(sqrt(p**2))
p

No other expansion is done.

>>> i, j = symbols('i,j', integer=True)

>>> powdenest((x**x)**(i + j)) # -X-> (x**x)**i*(x**x)**j
x**(x*(i + j))

But exp() will be denested by moving all non-log terms outside of the function; this may
result in the collapsing of the exp to a power with a different base:

>>> powdenest(exp(3*y*log(x)))
x**(3*y)
>>> powdenest(exp(y*(log(a) + log(b))))
(a*b)**y
>>> powdenest(exp(3*(log(a) + log(b))))
a**3*b**3

If assumptions allow, symbols can also be moved to the outermost exponent:

>>> i = Symbol('i', integer=True)

>>> powdenest(((x**(2*i))**(3*y))**x)
((x**(2*i))**(3*y))**x
>>> powdenest(((x**(2*i))**(3*y))**x, force=True)
x**(6*i*x*y)

>>> powdenest(((x**(2*a/3))**(3*y/i))**x)
((x**(2*a/3))**(3*y/i))**x
>>> powdenest((x**(2*i)*y**(4*i))**z, force=True)
(x*y**2)**(2*i*z)

>>> n = Symbol('n', negative=True)

5.27. Simplify 1203

SymPy Documentation, Release 1.3

>>> powdenest((x**i)**y, force=True)

x**(i*y)
>>> powdenest((n**i)**x, force=True)
(n**i)**x

5.27.14 Combinatorial simplification

combsimp

sympy.simplify.combsimp.combsimp(expr)
Simplify combinatorial expressions.
This function takes as input an expression containing factorials, binomials, Pochhammer
symbol and other “combinatorial” functions, and tries to minimize the number of those
functions and reduce the size of their arguments.
The algorithm works by rewriting all combinatorial functions as gamma functions and
applying gammasimp() except simplification steps that may make an integer argument
non-integer. See docstring of gammasimp for more information.
Then it rewrites expression in terms of factorials and binomials by rewriting gammas as
factorials and converting (a+b)!/a!b! into binomials.
If expression has gamma functions or combinatorial functions with non-integer argu-
ment, it is automatically passed to gammasimp.

Examples

>>> from sympy.simplify import combsimp

>>> from sympy import factorial, binomial, symbols
>>> n, k = symbols('n k', integer = True)

>>> combsimp(factorial(n)/factorial(n - 3))

n*(n - 2)*(n - 1)
>>> combsimp(binomial(n+1, k+1)/binomial(n, k))
(n + 1)/(k + 1)

5.27.15 Square Root Denesting

sqrtdenest

sympy.simplify.sqrtdenest.sqrtdenest(expr, max_iter=3)
Denests sqrts in an expression that contain other square roots if possible, otherwise
returns the expr unchanged. This is based on the algorithms of [1].
See also:
sympy.solvers.solvers.unrad

1204 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[1] http://researcher.watson.ibm.com/researcher/files/us-fagin/symb85.pdf
[2] D. J. Jeffrey and A. D. Rich, ‘Symplifying Square Roots of Square Roots by Denesting’
(available at http://www.cybertester.com/data/denest.pdf)

Examples

>>> from sympy.simplify.sqrtdenest import sqrtdenest

>>> from sympy import sqrt
>>> sqrtdenest(sqrt(5 + 2 * sqrt(6)))
sqrt(2) + sqrt(3)

5.27.16 Common Subexpression Elimination

cse

sympy.simplify.cse_main.cse(exprs, symbols=None, optimizations=None, postpro-

cess=None, order=’canonical’, ignore=())
Perform common subexpression elimination on an expression.
Parameters exprs : list of sympy expressions, or a single sympy expression
The expressions to reduce.
symbols : infinite iterator yielding unique Symbols
The symbols used to label the common subexpressions which are
pulled out. The numbered_symbols generator is useful. The default
is a stream of symbols of the form “x0”, “x1”, etc. This must be an
infinite iterator.
optimizations : list of (callable, callable) pairs
The (preprocessor, postprocessor) pairs of external optimization
functions. Optionally ‘basic’ can be passed for a set of predefined
basic optimizations. Such ‘basic’ optimizations were used by default
in old implementation, however they can be really slow on larger ex-
pressions. Now, no pre or post optimizations are made by default.
postprocess : a function which accepts the two return values of cse and
returns the desired form of output from cse, e.g. if you want the
replacements reversed the function might be the following lambda:
lambda r, e: return reversed(r), e
order : string, ‘none’ or ‘canonical’
The order by which Mul and Add arguments are processed. If set to
‘canonical’, arguments will be canonically ordered. If set to ‘none’,
ordering will be faster but dependent on expressions hashes, thus
machine dependent and variable. For large expressions where speed
is a concern, use the setting order=’none’.
ignore : iterable of Symbols

5.27. Simplify 1205

SymPy Documentation, Release 1.3

Substitutions containing any Symbol from ignore will be ignored.

Returns replacements : list of (Symbol, expression) pairs
All of the common subexpressions that were replaced. Subexpres-
sions earlier in this list might show up in subexpressions later in this
list.
reduced_exprs : list of sympy expressions
The reduced expressions with all of the replacements above.

Examples

>>> from sympy import cse, SparseMatrix

>>> from sympy.abc import x, y, z, w
>>> cse(((w + x + y + z)*(w + y + z))/(w + x)**3)
([(x0, y + z), (x1, w + x)], [(w + x0)*(x0 + x1)/x1**3])

Note that currently, y + z will not get substituted if -y - z is used.

>>> cse(((w + x + y + z)*(w - y - z))/(w + x)**3)

([(x0, w + x)], [(w - y - z)*(x0 + y + z)/x0**3])

List of expressions with recursive substitutions:

>>> m = SparseMatrix([x + y, x + y + z])

>>> cse([(x+y)**2, x + y + z, y + z, x + z + y, m])
([(x0, x + y), (x1, x0 + z)], [x0**2, x1, y + z, x1, Matrix([
[x0],
[x1]])])

Note: the type and mutability of input matrices is retained.

>>> isinstance(_[1][-1], SparseMatrix)

True

The user may disallow substitutions containing certain symbols:

>>> cse([y**2*(x + 1), 3*y**2*(x + 1)], ignore=(y,))

([(x0, x + 1)], [x0*y**2, 3*x0*y**2])

opt_cse

sympy.simplify.cse_main.opt_cse(exprs, order=’canonical’)
Find optimization opportunities in Adds, Muls, Pows and negative coefficient Muls
Parameters exprs : list of sympy expressions
The expressions to optimize.
order : string, ‘none’ or ‘canonical’
The order by which Mul and Add arguments are processed. For large
expressions where speed is a concern, use the setting order=’none’.
Returns opt_subs : dictionary of expression substitutions

1206 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The expression substitutions which can be useful to optimize CSE.

Examples

>>> from sympy.simplify.cse_main import opt_cse

>>> from sympy.abc import x
>>> opt_subs = opt_cse([x**-2])
>>> k, v = list(opt_subs.keys())[0], list(opt_subs.values())[0]
>>> print((k, v.as_unevaluated_basic()))
(x**(-2), 1/(x**2))

tree_cse

sympy.simplify.cse_main.tree_cse(exprs, symbols, opt_subs=None, or-

der=’canonical’, ignore=())
Perform raw CSE on expression tree, taking opt_subs into account.
Parameters exprs : list of sympy expressions
The expressions to reduce.
symbols : infinite iterator yielding unique Symbols
The symbols used to label the common subexpressions which are
pulled out.
opt_subs : dictionary of expression substitutions
The expressions to be substituted before any CSE action is per-
formed.
order : string, ‘none’ or ‘canonical’
The order by which Mul and Add arguments are processed. For large
expressions where speed is a concern, use the setting order=’none’.
ignore : iterable of Symbols
Substitutions containing any Symbol from ignore will be ignored.

5.27.17 Hypergeometric Function Expansion

hyperexpand

sympy.simplify.hyperexpand.hyperexpand(f, allow_hyper=False, rewrite=’default’,

place=None)
Expand hypergeometric functions. If allow_hyper is True, allow partial simplification
(that is a result different from input, but still containing hypergeometric functions).
If a G-function has expansions both at zero and at infinity, place can be set to 0 or zoo
to indicate the preferred choice.

5.27. Simplify 1207

SymPy Documentation, Release 1.3

Examples

>>> from sympy.simplify.hyperexpand import hyperexpand

>>> from sympy.functions import hyper
>>> from sympy.abc import z
>>> hyperexpand(hyper([], [], z))
exp(z)

Non-hyperegeometric parts of the expression and hypergeometric expressions that are

not recognised are left unchanged:

>>> hyperexpand(1 + hyper([1, 1, 1], [], z))

hyper((1, 1, 1), (), z) + 1

5.27.18 Traversal Tools

use

sympy.simplify.traversaltools.use(expr, func, level=0, args=(), kwargs={})

Use func to transform expr at the given level.

Examples

>>> from sympy import use, expand

>>> from sympy.abc import x, y

>>> f = (x + y)**2*x + 1

>>> use(f, expand, level=2)

x*(x**2 + 2*x*y + y**2) + 1
>>> expand(f)
x**3 + 2*x**2*y + x*y**2 + 1

5.27.19 EPath Tools

EPath class

class sympy.simplify.epathtools.EPath
Manipulate expressions using paths.
EPath grammar in EBNF notation:

literal ::= /[A-Za-z_][A-Za-z_0-9]*/

number ::= /-?\d+/
type ::= literal
attribute ::= literal ”?”
all ::= ”*”
slice ::= ”[” number? (”:” number? (”:” number?)?)? ”]”
range ::= all | slice
(continues on next page)

1208 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

query ::= (type | attribute) (”|” (type | attribute))*
selector ::= range | query range?
path ::= ”/” selector (”/” selector)*

See the docstring of the epath() function.

apply(expr, func, args=None, kwargs=None)
Modify parts of an expression selected by a path.

Examples

>>> from sympy.simplify.epathtools import EPath

>>> from sympy import sin, cos, E
>>> from sympy.abc import x, y, z, t

>>> path = EPath(”/*/[0]/Symbol”)

>>> expr = [((x, 1), 2), ((3, y), z)]

>>> path.apply(expr, lambda expr: expr**2)

[((x**2, 1), 2), ((3, y**2), z)]

>>> path = EPath(”/*/*/Symbol”)

>>> expr = t + sin(x + 1) + cos(x + y + E)

>>> path.apply(expr, lambda expr: 2*expr)

t + sin(2*x + 1) + cos(2*x + 2*y + E)

select(expr)
Retrieve parts of an expression selected by a path.

Examples

>>> from sympy.simplify.epathtools import EPath

>>> from sympy import sin, cos, E
>>> from sympy.abc import x, y, z, t

>>> path = EPath(”/*/[0]/Symbol”)

>>> expr = [((x, 1), 2), ((3, y), z)]

>>> path.select(expr)
[x, y]

>>> path = EPath(”/*/*/Symbol”)

>>> expr = t + sin(x + 1) + cos(x + y + E)

>>> path.select(expr)
[x, x, y]

5.27. Simplify 1209

SymPy Documentation, Release 1.3

epath

sympy.simplify.epathtools.epath(path, expr=None, func=None, args=None,

kwargs=None)
Manipulate parts of an expression selected by a path.
This function allows to manipulate large nested expressions in single line of code, utiliz-
ing techniques to those applied in XML processing standards (e.g. XPath).
If func is None, epath() (page 1210) retrieves elements selected by the path. Otherwise
it applies func to each matching element.
Note that it is more efficient to create an EPath object and use the select and apply
methods of that object, since this will compile the path string only once. This function
should only be used as a convenient shortcut for interactive use.
This is the supported syntax:
• select all: /* Equivalent of for arg in args:.
• select slice: /[0] or /[1:5] or /[1:5:2] Supports standard Python’s slice syn-
tax.
• select by type: /list or /list|tuple Emulates isinstance().
• select by attribute: /__iter__? Emulates hasattr().

Parameters path : str | EPath

A path as a string or a compiled EPath.
expr : Basic | iterable
An expression or a container of expressions.
func : callable (optional)
A callable that will be applied to matching parts.
args : tuple (optional)
Additional positional arguments to func.
kwargs : dict (optional)
Additional keyword arguments to func.

Examples

>>> from sympy.simplify.epathtools import epath

>>> from sympy import sin, cos, E
>>> from sympy.abc import x, y, z, t

>>> path = ”/*/[0]/Symbol”

>>> expr = [((x, 1), 2), ((3, y), z)]

>>> epath(path, expr)

[x, y]
>>> epath(path, expr, lambda expr: expr**2)
[((x**2, 1), 2), ((3, y**2), z)]

1210 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> path = ”/*/*/Symbol”

>>> expr = t + sin(x + 1) + cos(x + y + E)

>>> epath(path, expr)

[x, x, y]
>>> epath(path, expr, lambda expr: 2*expr)
t + sin(2*x + 1) + cos(2*x + 2*y + E)

5.28 Details on the Hypergeometric Function Expansion

Module

This page describes how the function hyperexpand() and related code work. For usage, see
the documentation of the symplify module.

5.28.1 Hypergeometric Function Expansion Algorithm

This section describes the algorithm used to expand hypergeometric functions. Most of it is
based on the papers [Roach1996] and [Roach1997].
Recall that the hypergeometric function is (initially) defined as
( ) ∑∞
a1 , · · · , ap (a1 )n · · · (ap )n z n
p Fq z = .
b1 , · · · , b q (b1 )n · · · (bq )n n!
n=0

It turns out that there are certain differential operators that can change the ap and pq param-
eters by integers. If a sequence of such operators is known that converts the set of indices
a0r and b0s into ap and bq , then we shall say the pair ap , bq is reachable from a0r , b0s . Our general
strategy is thus as follows: given a set ap , bq of parameters, try to look up an origin a0r , b0s for
which we know an expression, and then apply the sequence of differential operators to the
known expression to find an expression for the Hypergeometric function we are interested
in.

Notation

In the following, the symbol a will always denote a numerator parameter and the symbol b
will always denote a denominator parameter. The subscripts p, q, r, s denote vectors of that
length, so e.g. ap denotes a vector of p numerator parameters. The subscripts i and j denote
“running indices”, so they should usually be used in conjunction with a “for all i”. E.g. ai < 4
for all i. Uppercase subscripts I and J denote a chosen, fixed index. So for example aI > 0 is
true if the inequality holds for the one index I we are currently interested in.

Incrementing and decrementing indices

( ) ( )
Suppose ai ̸= 0. Set A(ai ) = z d
ai dz + 1. It is then easy to show that A(ai )p Fq ap
bq
z = p Fq apb+e
q
i
z ,
where ei is the i-th unit vector. Similarly for bj ̸= 1 we set B(bj ) = bjz−1 dz
d
+ 1 and find
( ) ( )
B(bj )p Fq abqp z = p Fq bqa−e
p
i
z . Thus we can increment upper and decrement lower indices
at will, as long as we don’t go through zero. The A(ai ) and B(bj ) are called shift operators.

5.28. Details on the Hypergeometric Function Expansion Module 1211

SymPy Documentation, Release 1.3

( ) ( )
d ap a1 ···ap ap +1
It is also easy to show that dz p Fq bq
z = b1 ···bq p Fq bq +1
z , where ap +1 is the vector a1 +1, a2 +
1, . . . and similarly for bq + 1. Combining this[ with the shift operators, we arrive at] one(form) of
∏q a1 ···ap ∏p
j=1 B(bj ) − (b1 −1)···(bq −1)
d ap
the Hypergeometric differential equation: dz i=1 A(ai ) p Fq bq z =
0. This holds if all shift operators are defined, i.e. if no ai = 0 and no bj = 1.
Clearing
[ denominators ) and multiplying)]through by
) z we arrive at the following equation:
∏q ( d ∏p ( d (
d
z dz j=1 z dz + b j − 1 − z i=1 z dz + ai F ap
p q bq z = 0. Even though our derivation does not
show it, it can be checked that this equation holds whenever the p Fq is defined.
d
Notice that, under suitable conditions on aI , bJ , each of the operators A(ai ), B(bj ) and z dz
can be expressed in terms of A(aI ) or B(bJ ). Our ( next
) aim is to write the Hypergeometric
differential equation as follows: [XA(aI ) − r]p Fq ap
= 0, for some operator X and some
z
bq
( ) ( )
̸ 0, then we can write this as −1
constant r to be determined. If r = r X p Fq
ap +eI
bq
z = p Fq abqp z ,
−1
and so r X undoes the shifting of A(aI ), whence it will be called an inverse-shift operator.
Now A(aI ) exists if aI ̸= 0, and then z dz
d
= aI A(aI ) − a)I . Observe also that ))
all the operators
d
∏p ( d (∏
p
(
d
A(ai ), B(bj ) and z dz commute. We have i=1 z dz + ai = i=1,i̸=I z dz + ai aI A(aI ), so this
gives us (the first half
) of X. The other half does not have such a nice expression. We find
∏q ∏q
z dz j=1 z dz + bj − 1 = (aI A(aI ) − aI ) j=1 (aI A(aI ) − aI + bj − 1). Since the first half had no
d d
∏q
constant term, we infer r = −aI j=1 (bj − 1 − aI ).
This tells us under which conditions we can “un-shift” A(aI ), namely when aI ̸= 0 and r ̸= 0.
Substituting aI − 1 for aI then tells us under what conditions we can decrement the index aI .
Doing a similar analysis for B(aJ ), we arrive at the following rules:
• An index aI can be decremented if aI ̸= 1 and aI ̸= bj for all bj .
• An index bJ can be incremented if bJ ̸= −1 and bJ ̸= ai for all ai .
Combined with the conditions (stated above) for the existence of shift operators, we have thus
established the rules of the game!

Reduction of Order
( ) ( )
a∗
Notice that, quite trivially, if aI = bJ , we have p Fq ap
bq
z = p−1 Fq−1
p
b∗
z , where a∗p means ap
q
with aI omitted, and similarly for b∗q . We call this reduction of order.
(aI )n
In fact, we can do even better. If aI − bJ ∈ Z>0 , then it is easy to see that (bJ )n is actually a
d k n
polynomial in n. It is also easy to see that (z dz ) z = nk z n . Combining these two remarks we
find:
If aI − bJ ∈ Z>0 , then there exists a polynomial p(n) = p0 + p1 n + · · · )
(of degree aI − bJ )
( ) ( ( )2 ( ∗ )
(aI )n a
such that (bJ )n = p(n) and p Fq bq z = p0 + p1 z dz + p2 z dz + · · · p−1 Fq−1 b∗p z .
ap d d
q

Thus any set of parameters ap , bq is reachable from a set of parameters cr , ds where ci − dj ∈ Z

implies ci < dj . Such a set of parameters cr , ds is called suitable. Our database of known
formulae should only contain suitable origins. The reasons are twofold: firstly, working from
suitable origins is easier, and secondly, a formula for a non-suitable origin can be deduced
from a lower order formula, and we should put this one into the database instead.

1212 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Moving Around in the Parameter Space

It remains to investigate the following question: suppose ap , bq and a0p , b0q are both suitable,
and also ai − a0i ∈ Z, bj − b0j ∈ Z. When is ap , bq reachable from a0p , b0q ? It is clear that we can
treat all parameters independently that are incongruent mod 1. So assume that ai and bj are
congruent to r mod 1, for all i and j. The same then follows for a0i and b0j .
If r ̸= 0, then any such ap , bq is reachable from any a0p , b0q . To see this notice that there exist
constants c, c0 , congruent mod 1, such that ai < c < bj for all i and j, and similarly a0i < c0 < b0j .
If n = c − c0 > 0 then we first inverse-shift all the b0j n times up, and then similarly shift up
all the a0i n times. If n < 0 then we first inverse-shift down the a0i and then shift down the b0j .
This reduces to the case c = c0 . But evidently we can now shift or inverse-shift around the ai0
arbitrarily so long as we keep them less than c, and similarly for the b0j so long as we keep
them bigger than c. Thus ap , bq is reachable from a0p , b0q .
If r = 0 then the problem is slightly more involved. WLOG no parameter is zero. We now
have one additional complication: no parameter can ever move through zero. Hence ap , bq
is reachable from a0p , b0q if and only if the number of ai < 0 equals the number of a0i < 0, and
similarly for the bi and b0i . But in a suitable set of parameters, all bj > 0! This is because the
Hypergeometric function is undefined if one of the bj is a non-positive integer and all ai are
smaller than the bj . Hence the number of bj ≤ 0 is always zero.
We can thus associate to every suitable set of parameters ap , bq , where no ai = 0, the following
invariants:
• For every r ∈ [0, 1) the number αr of parameters ai ≡ r (mod 1), and similarly the number
βr of parameters bi ≡ r (mod 1).
• The number γ of integers ai with ai < 0.
The above reasoning shows that ap , bq is reachable from a0p , b0q if and only if the invariants
αr , βr , γ all agree. Thus in particular “being reachable from” is a symmetric relation on suitable
parameters without zeros.

Applying the Operators

If all goes well then for a given set of parameters we find an origin in our database for which
we have a nice formula. We now have to apply (potentially) many differential operators to it. If
we do this blindly then the result will be very messy. This is because with Hypergeometric type
functions, the derivative is usually expressed as a sum of two contiguous functions. Hence
if we compute N derivatives, then the answer will involve 2N contiguous functions! This is
clearly undesirable. In fact we know from the Hypergeometric differential equation that we
need at most max(p, q + 1) contiguous functions to express all derivatives.
Hence instead of differentiating blindly, we will work with a C(z)-module basis: for an origin
a0r , b0s we either store (for particularly pretty answers) or compute a set of N functions (typ-
ically N = max(r, s + 1)) with the property that the derivative of any of them is a C(z)-linear
combination of them. In formulae, we store a vector B of N functions, a matrix M and a vector
C (the latter two with entries in C(z)), with the following properties:
( 0 )
• r Fs ab0r z = CB
s

d
• z dz B = M B.
Then we can compute as many derivatives as we want and we will always end up with C(z)-
linear combination of at most N special functions.

5.28. Details on the Hypergeometric Function Expansion Module 1213

SymPy Documentation, Release 1.3

As hinted above, B, M and C can either all be stored (for particularly pretty answers) or
computed from a single p Fq formula.

Loose Ends

This describes the bulk of the hypergeometric function algorithm. There a few further tricks,
described in the hyperexpand.py source file. The extension to Meijer G-functions is also de-
scribed there.

5.28.2 Meijer G-Functions of Finite Confluence

Slater’s theorem essentially evaluates a G-function as a sum of residues. If all poles are
simple, the resulting series can be recognised as hypergeometric series. Thus a G-function
can be evaluated as a sum of Hypergeometric functions.
If the poles are not simple, the resulting series are not hypergeometric. This is known as
the “confluent” or “logarithmic” case (the latter because the resulting series tend to contain
logarithms). The answer depends in a complicated way on the multiplicities of various poles,
and there is no accepted notation for representing it (as far as I know). However if there are
only finitely many multiple poles, we can evaluate the G function as a sum of hypergeometric
functions, plus finitely many extra terms. I could not find any good reference for this, which
is why I work it out here.
Recall the general setup. We define
∫ ∏m ∏n
1 j=1 Γ(bj − s) Γ(1 − aj + s)
j=1
G(z) = ∏q ∏p z s ds,
2πi L j=m+1 Γ(1 − bj + s) j=n+1 Γ(aj − s)

where L is a contour starting and ending at +∞, enclosing all of the poles of Γ(bj − s) for
j = 1, . . . , n once in the negative direction, and no other poles. Also the integral is assumed
absolutely convergent.
In what follows, for any complex numbers a, b, we write a ≡ b (mod 1) if and only if there
exists an integer k such that a − b = k. Thus there are double poles iff ai ≡ aj (mod 1) for some
i ̸= j ≤ n.
We now assume that whenever bj ≡ ai (mod 1) for i ≤ m, j > n then bj < ai . This means that
no quotient of the relevant gamma functions is a polynomial, and can always be achieved by
“reduction of order”. Fix a complex number c such that {bi |bi ≡ c (mod 1), i ≤ m} is not empty.
Enumerate this set as b, b + k1 , . . . , b + ku , with ki non-negative integers. Enumerate similarly
{aj |aj ≡ c (mod 1), j > n} as b + l1 , . . . , b + lv . Then li > kj for all i, j. For finite confluence, we
need to assume v ≥ u for all such c.
Let c1 , . . . , cw be distinct (mod 1) and exhaust the congruence classes of the bi . I claim

∑
w
G(z) = − (Fj (z) + Rj (z)),
j=1

where Fj (z) is a hypergeometric function and Rj (z) is a finite sum, both to be specified later.
Indeed corresponding to every cj there is a sequence of poles, at mostly finitely many of them
multiple poles. This is where the j-th term comes from.
Hence fix again c, enumerate the relevant bi as b, b + k1 , . . . , b + ku . We will look at the aj
corresponding to a + l1 , . . . , a + lu . The other ai are not treated specially. The corresponding

1214 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

gamma functions have poles at (potentially) s = b + r for r = 0, 1, . . .. For r ≥ lu , pole of the

integrand is simple. We thus set
u −1
l∑
R(z) = ress=r+b .
r=0

We finally need to investigate the other poles. Set r = lu + t, t ≥ 0. A computation shows

Γ(ki − lu − t) 1 (−1)δi (lu − li + 1)t

= = ,
Γ(li − lu − t) (ki − lu − t)li −ki (lu − li + 1)δi (lu − ki + 1)t
where δi = li − ki .
Also
Γ(bj − lu − b)
Γ(bj − lu − b − t) = ,
(−1)t (lu + b + 1 − bj )t

Γ(1 − aj + lu + b + t) = Γ(1 − aj + lu + b)(1 − aj + lu + b)t

and
(−1)lu +t (−1)lu (−1)t
ress=b+lu +t Γ(b − s) = − =− .
(lu + t)! lu ! (lu + 1)t
Hence
∏n ∏m
(−1)lu ∏
∗
j=1 Γ(1 − aj + lu + b) j=1 Γ(bj − lu − b)
u
(−1)δi
ress=b+lu +t =−z b+lu
∏p ∏ q
lu ! i=1 (lu − ki + 1)δi j=n+1 Γ(aj − lu − b)∗ j=m+1 Γ(1 − bj + lu + b)
∏n ∏p
t ∏ ∗
(lu − li + 1)t j=1 (1 − aj + lu + b)t j=n+1 (−1) (lu + b + 1 − aj )t
u t
t (−1)
×z ∏m ∏ ,
(lu + 1)t i=1 (lu − ki + 1)t j=1 (−1)t (lu + b + 1 − bj )∗t qj=m+1 (1 − bj + lu + b)t

where the ∗ means to omit the terms we treated specially.

We thus arrive at
( )
1, (1 + lu − li ), (1 + lu + b − ai )∗
F (z) = C × p+1 Fq (−1)p−m−n
z ,
1 + lu , (1 + lu − ki ), (1 + lu + b − bi )∗

where C designates the factor in the residue independent of t. (This result can also be written
in slightly simpler form by converting all the lu etc back to a∗ − b∗ , but doing so is going to
require more notation still and is not helpful for computation.)

5.28.3 Extending The Hypergeometric Tables

Adding new formulae to the tables is straightforward. At the top of the file sympy/simplify/
hyperexpand.py, there is a function called add_formulae(). Nested in it are defined two
helpers, add(ap, bq, res) and addb(ap, bq, B, C, M), as well as dummys a, b, c, and z.
The first step in adding a new formula is by using add(ap, bq, res). This declares hyper(ap,
bq, z) == res. Here ap and bq may use the dummys a, b, and c as free symbols. For example
∑∞ n
the well-known formula 0 (−a) nz
n! = (1 − z)a is declared by the following line: add((-a, ),
(), (1-z)**a).
From the information provided, the matrices B, C and M will be computed, and the formula is
now available when expanding hypergeometric functions. Next the test file sympy/simplify/
tests/test_hyperexpand.py should be run, in particular the test test_formulae(). This will

5.28. Details on the Hypergeometric Function Expansion Module 1215

SymPy Documentation, Release 1.3

test the newly added formula numerically. If it fails, there is (presumably) a typo in what was
entered.
Since all newly-added formulae are probably relatively complicated, chances are that the
automatically computed basis is rather suboptimal (there is no good way of testing this, other
than observing very messy output). In this case the matrices B, C and M should be computed
by hand. Then the helper addb can be used to declare a hypergeometric formula with hand-
computed basis.

An example

Because this explanation so far might be very theoretical and difficult to understand, we walk
through an explicit example now. We take the Fresnel function C(z) which obeys the following
hypergeometric representation:
( 1 )
π2 z4
C(z) = z · 1 F2 1 5 −
4 .
2, 4 16
First we try to add this formula to the lookup table by using the (simpler) function add(ap,
bq, res). The first two arguments are simply the lists containing the parameter sets of 1 F2 .
The res argument is a little bit more complicated. We only know C(z) in terms of 1 F2 (. . . |f (z))
with f a function of z, in our case
π2 z4
f (z) = − .
16
What we need is a formula where the hypergeometric function has only z as argument
1 F2 (. . . |z). We introduce the new complex symbol w and search for a function g(w) such that

f (g(w)) = w

holds. Then we can replace every z in C(z) by g(w). In the case of our example the function g
could look like
( )
2 iπ 1
g(w) = √ exp w4 .
π 4
We get these functions mainly by guessing and testing the result. Hence we proceed by
computing f (g(w)) (and simplifying naively)
π 2 g(w)4
f (g(w)) = −
16
( ( ) 1 )4
π 2 g √2π exp iπ
4 w
4

=−
16
4 ( )4 1 4
π 2 √2π4 exp iπ4 w4
=−
16
= − exp (iπ) w
=w
and indeed get back w. (In case of branched functions we have to be aware of branch cuts. In
that case we take w to be a positive real number and check the formula. If what we have found
works for positive w, then just replace exp() inside any branched function by exp_polar()
and what we get is right for all w.) Hence we can write the formula as
( 1 )
C(g(w)) = g(w) · 1 F2 1 4 5 w .
2, 4

1216 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

and trivially
( ( ) 1)
( ) C √2 exp iπ 4 w
1 4
C(g(w)) π
1 F2
4
1 5 w = = ( iπ ) 1
2, 4 g(w) √2
π
exp 4 w 4

which is exactly what is needed for the third parameter, res, in add. Finally, the whole function
call to add this rule to the table looks like:

add([S(1)/4],
[S(1)/2, S(5)/4],
fresnelc(exp(pi*I/4)*root(z,4)*2/sqrt(pi)) / (exp(pi*I/4)*root(z,4)*2/sqrt(pi))
)

Using this rule we will find that it works but the results are not really nice in terms of simplicity
and number of special function instances included. We can obtain much better results by
adding the formula to the lookup table in another way. For this we use the (more complicated)
function addb(ap, bq, B, C, M). The first two arguments are again the lists containing the
parameter sets of 1 F2 . The remaining three are the matrices mentioned earlier on this page.
We know that the n = max (p, q + 1)-th derivative can be expressed as a linear combination of
lower order derivatives. The matrix B contains the basis {B0 , B1 , . . .} and is of shape n × 1. The
best way to get Bi is to take the first n = max(p, q + 1) derivatives of the expression for p Fq
and take out useful pieces. In our case we find that n = max (1, 2 + 1) = 3. For computing the
d
derivatives, we have to use the operator z dz . The first basis element B0 is set to the expression
for 1 F2 from above:
√ ( ) ( 2 ( ) 1)
π exp − ıπ 4 C
√ exp ıπ z 4
π 4
B0 = 1
2z 4
d
Next we compute z dz B0 . For this we can directly use SymPy!

>>> from sympy import Symbol, sqrt, exp, I, pi, fresnelc, root, diff, expand
>>> z = Symbol(”z”)
>>> B0 = sqrt(pi)*exp(-I*pi/4)*fresnelc(2*root(z,4)*exp(I*pi/4)/sqrt(pi))/\
... (2*root(z,4))
>>> z * diff(B0, z)
z*(cosh(2*sqrt(z))/(4*z) - sqrt(pi)*exp(-I*pi/4)*fresnelc(2*z**(1/4)*exp(I*pi/4)/
,→sqrt(pi))/(8*z**(5/4)))

>>> expand(_)
cosh(2*sqrt(z))/4 - sqrt(pi)*exp(-I*pi/4)*fresnelc(2*z**(1/4)*exp(I*pi/4)/sqrt(pi))/
,→(8*z**(1/4))

Formatting this result nicely we obtain

√ ( ) ( 2 ( ) 1)
1 π exp − ıπ
4 C √ exp ıπ z 4
π 4 1 ( √ )
B1′ = − 1 + cosh 2 z
4 2z 4 4
Computing the second derivative we find

>>> from sympy import (Symbol, cosh, sqrt, pi, exp, I, fresnelc, root,
... diff, expand)
>>> z = Symbol(”z”)
>>> B1prime = cosh(2*sqrt(z))/4 - sqrt(pi)*exp(-I*pi/4)*\
... fresnelc(2*root(z,4)*exp(I*pi/4)/sqrt(pi))/(8*root(z,4))
>>> z * diff(B1prime, z)
(continues on next page)

5.28. Details on the Hypergeometric Function Expansion Module 1217

SymPy Documentation, Release 1.3

(continued from previous page)

z*(-cosh(2*sqrt(z))/(16*z) + sinh(2*sqrt(z))/(4*sqrt(z)) + sqrt(pi)*exp(-I*pi/
,→4)*fresnelc(2*z**(1/4)*exp(I*pi/4)/sqrt(pi))/(32*z**(5/4)))

>>> expand(_)
sqrt(z)*sinh(2*sqrt(z))/4 - cosh(2*sqrt(z))/16 + sqrt(pi)*exp(-I*pi/
,→4)*fresnelc(2*z**(1/4)*exp(I*pi/4)/sqrt(pi))/(32*z**(1/4))

which can be printed as

√ ( ) ( 2 ( ) 1)
1 π exp − ıπ
4 C √ exp ıπ z 4
π 4 1 ( √ ) 1 ( √ )√
B2′ = 1 − cosh 2 z + sinh 2 z z
16 2z 4 16 4

We see the common pattern and can collect the pieces. Hence it makes sense to choose B1
and B2 as follows
√ ( 1)

  π exp(− ıπ
4 )C
√2 exp( ıπ )z 4
B0 
π 4

B = B1  =  
1
2z 4 √
 cosh (2 z) 
B2 √ √
sinh (2 z) z

(This is in contrast to the basis B = (B0 , B1′ , B2′ ) that would have been computed automatically
if we used just add(ap, bq, res).)
Because it must hold that p Fq (· · ·|z) = CB the entries of C are obviously
 
1
C = 0
0

Finally we have to compute the entries of the 3 × 3 matrix M such that z dz

d
B = M B holds. This
d
is easy. We already computed the first part z dz B0 above. This gives us the first row of M . For
the second row we have:

>>> from sympy import Symbol, cosh, sqrt, diff

>>> z = Symbol(”z”)
>>> B1 = cosh(2*sqrt(z))
>>> z * diff(B1, z)
sqrt(z)*sinh(2*sqrt(z))

and for the third one

>>> from sympy import Symbol, sinh, sqrt, expand, diff

>>> z = Symbol(”z”)
>>> B2 = sinh(2*sqrt(z))*sqrt(z)
>>> expand(z * diff(B2, z))
sqrt(z)*sinh(2*sqrt(z))/2 + z*cosh(2*sqrt(z))

Now we have computed the entries of this matrix to be

 1 1 
−4 4 0
M = 0 0 1
0 z 21

Note that the entries of C and M should typically be rational functions in z, with rational
coefficients. This is all we need to do in order to add a new formula to the lookup table for
hyperexpand.

1218 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.28.4 Implemented Hypergeometric Formulae

A vital part of the algorithm is a relatively large table of hypergeometric function represen-
tations. The following automatically generated list contains all the representations imple-
mented in SymPy (of course many more are derived from them). These formulae are mostly
taken from [Luke1969] and [Prudnikov1990]. They are all tested numerically.

( )
0 F0 z = ez
( )
1 F0 a z = (−z + 1)−a
( )
a, a − 1 (√ )−2a+1
2 F1
2 z = 22a−1 −z + 1 + 1
2a
( )
1, 1 log (−z + 1)
2 F1 z =−
2 z
(1 ) √
2, 1 z
atanh ( z)
F
2 1 3 = √
2 z
(1 1 ) √
,2 asin ( z)
2 F1
2
3 z = √
2 z
( ) √ −2a √ −2a
a, a + 12 ( z + 1) (− z + 1)
2 F1 1 z = +
2 2 2
( )
a, −a ( (√ ))
2 F1 1 z = cos 2a asin z
2
( √)
asin ( z)
1, 1
2 F1
3 = √ √z
2 z −z + 1
(1 1 )
2, 2 z
2K (z)
2 F1 =
1 π
( 1 1 )
−2, 2 2E (z)
2 F1 z =
1 π
( 1 ) √ √
− 2 , 1, 1 2 z atanh ( z) 2 log (−z + 1)
3 F2 1 z =− + −
2 , 2 3 3 3z
(√ )
( 1 ) ( ) 4 log −z+1
+ 21
− 2 , 1, 1 4 16 √ 2 16
3 F2 z = − −z + 1 + +
2, 2 9 9z 3z 9z
( )
1
1 F1 z = z −b+1 (b − 1) ez γ (b − 1, z)
b
( ) (z ) ( )
a a− 21 −a+ 12 z2 1
F
1 1 z = 4 z e I 1
a− 2 Γ a +
2a 2 2
( )
a ( )−a ( )
1 F1 z = a zeiπ γ a, zeiπ
a+1
( 1 )
−2 √ √ (√ )
F
1 1 1 z = zi π erf zi + ez
2
( ( ) ( ))
√ √ √ iπ
2 4√ √ √ iπ
2 4√
( ) e−
ze 4 ze 4 iπ
π i sinh (2 z)S π
+ cosh (2 z)C π
4
1
1 F2 3 5 z = √
4, 4 24z

5.28. Details on the Hypergeometric Function Expansion Module 1219

SymPy Documentation, Release 1.3

( ) √ √ √ ( )−a ( )
1 ai π z1 erf ( zi) a zeiπ γ a, zeiπ
2, a =− −
2 F2 3 z
2, a +1 2a − 1 2a − 1
( )
1, 1 − log (z) + Ei (z) γ
2 F2 z = −
2, 2 z z
( )
( √ )
0 F1 1 z = cosh 2 z
2
( )
( √ )
= z − 2 + 2 Ib−1 2 z Γ (b)
b 1
0 F1 z
b
( )
1 ( ( √ ) ( √ ))
= 2−2a z − 2 + 4 I2a−1 4 4 z + J2a−1 4 4 z Γ (2a)
a
0 F3 1 1 z
2 , a, a
+ 2
( ) (
√ iπ )−2a+1 ( √ √ iπ ) ( √ √ iπ )
0 F3 z = 2 ze 2 I2a−1 2 2 4 ze 4 J2a−1 2 2 4 ze 4 Γ2 (2a)
a, a + 12 , 2a
( ) ( ) ( ) ( )
a a−1 −a+1
(√ ) (√ ) 1 1 a− 21 −a+ 12 2
(√ ) 2 1
1 F2 z =2·4 z Ia− 32 z Ia− 12 z Γ a− Γ a+ −4 z Ia− 1 z Γ a+
a − 12 , 2a 2 2 2 2
( 1
) √ √
2
π (−b + 1) I−b+1 ( z) Ib−1 ( z)
1 F2 z =
b, −b + 2 sin (bπ)
( 1 ) √
Shi (2 z)
F
1 2
2 z
3 3 = √
2, 2 2 z
( √ iπ )
√ − 3iπ 4
( 3 ) 3 πe 4 S 2 √zeπ 4
4
1 F2 3 7 z = 3
2, 4 4z 4
( √ iπ )
√ − iπ 4
( 1 ) πe 4 C 2 √zeπ
4

1 F2
4
1 5 z = √
2, 4 24z
( ) ( √ )−2a+1
a, a + 12 z (√ ) (√ )
2 F3 z = I2a−b z Ib−1 z Γ (b) Γ (2a − b + 1)
2a, b, 2a − b + 1 2
( ) √ √
1, 1 − log (2 z) + Chi (2 z) γ
2 F3 z = −
2, 2, 23 z z
( ) −a
1, 1, a a (−z) (Γ (a) − Γ (a, −z)) a (−a + 1) (log (−z) + E1 (−z) + γ) aez a
3 F3 z = 2 + 2 − 2a + 1)
− 2 − 2a + 1)
+ 2 − 2a + 1)
2, 2, a + 1 (a − 1) z (a z (a z (a

5.28.5 References

5.29 Stats

SymPy statistics module

Introduces a random variable type into the SymPy language.
Random variables may be declared using prebuilt functions such as Normal, Exponential,
Coin, Die, etc… or built with functions like FiniteRV.
Queries on random expressions can be made using the functions

1220 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Expression Meaning
P(condition) Probability
E(expression) Expected value
variance(expression) Variance
density(expression) Probability Density Function
sample(expression) Produce a realization
where(condition) Where the condition is true

5.29.1 Examples

>>> from sympy.stats import P, E, variance, Die, Normal

>>> from sympy import Eq, simplify
>>> X, Y = Die('X', 6), Die('Y', 6) # Define two six sided dice
>>> Z = Normal('Z', 0, 1) # Declare a Normal random variable with mean 0, std 1
>>> P(X>3) # Probability X is greater than 3
1/2
>>> E(X+Y) # Expectation of the sum of two dice
7
>>> variance(X+Y) # Variance of the sum of two dice
35/6
>>> simplify(P(Z>1)) # Probability of Z being greater than 1
-erf(sqrt(2)/2)/2 + 1/2

5.29.2 Random Variable Types

Finite Types

sympy.stats.DiscreteUniform(name, items)
Create a Finite Random Variable representing a uniform distribution over the input set.
Returns a RandomSymbol.

Examples

>>> from sympy.stats import DiscreteUniform, density

>>> from sympy import symbols

>>> X = DiscreteUniform('X', symbols('a b c')) # equally likely over a, b, c

>>> density(X).dict
{a: 1/3, b: 1/3, c: 1/3}

>>> Y = DiscreteUniform('Y', list(range(5))) # distribution over a range

>>> density(Y).dict
{0: 1/5, 1: 1/5, 2: 1/5, 3: 1/5, 4: 1/5}

sympy.stats.Die(name, sides=6)
Create a Finite Random Variable representing a fair die.
Returns a RandomSymbol.

5.29. Stats 1221

SymPy Documentation, Release 1.3

>>> from sympy.stats import Die, density

>>> D6 = Die('D6', 6) # Six sided Die

>>> density(D6).dict
{1: 1/6, 2: 1/6, 3: 1/6, 4: 1/6, 5: 1/6, 6: 1/6}

>>> D4 = Die('D4', 4) # Four sided Die

>>> density(D4).dict
{1: 1/4, 2: 1/4, 3: 1/4, 4: 1/4}

sympy.stats.Bernoulli(name, p, succ=1, fail=0)

Create a Finite Random Variable representing a Bernoulli process.
Returns a RandomSymbol

>>> from sympy.stats import Bernoulli, density

>>> from sympy import S

>>> X = Bernoulli('X', S(3)/4) # 1-0 Bernoulli variable, probability = 3/4

>>> density(X).dict
{0: 1/4, 1: 3/4}

>>> X = Bernoulli('X', S.Half, 'Heads', 'Tails') # A fair coin toss

>>> density(X).dict
{Heads: 1/2, Tails: 1/2}

sympy.stats.Coin(name, p=1/2)
Create a Finite Random Variable representing a Coin toss.
Probability p is the chance of gettings “Heads.” Half by default
Returns a RandomSymbol.

>>> from sympy.stats import Coin, density

>>> from sympy import Rational

>>> C = Coin('C') # A fair coin toss

>>> density(C).dict
{H: 1/2, T: 1/2}

>>> C2 = Coin('C2', Rational(3, 5)) # An unfair coin

>>> density(C2).dict
{H: 3/5, T: 2/5}

sympy.stats.Binomial(name, n, p, succ=1, fail=0)

Create a Finite Random Variable representing a binomial distribution.
Returns a RandomSymbol.

Examples

>>> from sympy.stats import Binomial, density

>>> from sympy import S

1222 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> X = Binomial('X', 4, S.Half) # Four ”coin flips”

>>> density(X).dict
{0: 1/16, 1: 1/4, 2: 3/8, 3: 1/4, 4: 1/16}

sympy.stats.Hypergeometric(name, N, m, n)
Create a Finite Random Variable representing a hypergeometric distribution.
Returns a RandomSymbol.

Examples

>>> from sympy.stats import Hypergeometric, density

>>> from sympy import S

>>> X = Hypergeometric('X', 10, 5, 3) # 10 marbles, 5 white (success), 3 draws

>>> density(X).dict
{0: 1/12, 1: 5/12, 2: 5/12, 3: 1/12}

sympy.stats.FiniteRV(name, density)
Create a Finite Random Variable given a dict representing the density.
Returns a RandomSymbol.

>>> from sympy.stats import FiniteRV, P, E

>>> density = {0: .1, 1: .2, 2: .3, 3: .4}

>>> X = FiniteRV('X', density)

>>> E(X)
2.00000000000000
>>> P(X >= 2)
0.700000000000000

Discrete Types

sympy.stats.Geometric(name, p)
Create a discrete random variable with a Geometric distribution.
The density of the Geometric distribution is given by

f (k) := p(1 − p)k−1

Parameters p: A probability between 0 and 1

Returns A RandomSymbol.

References

[1] http://en.wikipedia.org/wiki/Geometric_distribution [2] http://mathworld.wolfram.

com/GeometricDistribution.html

5.29. Stats 1223

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Geometric, density, E, variance

>>> from sympy import Symbol, S

>>> p = S.One / 5
>>> z = Symbol(”z”)

>>> X = Geometric(”x”, p)

>>> density(X)(z)
(4/5)**(z - 1)/5

>>> E(X)
5

>>> variance(X)
20

sympy.stats.Poisson(name, lamda)
Create a discrete random variable with a Poisson distribution.
The density of the Poisson distribution is given by

λk e−λ
f (k) :=
k!
Parameters lamda: Positive number, a rate
Returns A RandomSymbol.

References

[1] http://en.wikipedia.org/wiki/Poisson_distribution [2] http://mathworld.wolfram.com/

PoissonDistribution.html

Examples

>>> from sympy.stats import Poisson, density, E, variance

>>> from sympy import Symbol, simplify

>>> rate = Symbol(”lambda”, positive=True)

>>> z = Symbol(”z”)

>>> X = Poisson(”x”, rate)

>>> density(X)(z)
lambda**z*exp(-lambda)/factorial(z)

>>> E(X)
lambda

1224 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> simplify(variance(X))
lambda

Continuous Types

sympy.stats.Arcsin(name, a=0, b=1)

Create a Continuous Random Variable with an arcsin distribution.
The density of the arcsin distribution is given by
1
f (x) := √
π (x − a)(b − x)

with x ∈ [a, b]. It must hold that −∞ < a < b < ∞.

Parameters a : Real number, the left interval boundary
b : Real number, the right interval boundary
Returns A RandomSymbol.

References

[R538]

Examples

>>> from sympy.stats import Arcsin, density, cdf

>>> from sympy import Symbol, simplify

>>> a = Symbol(”a”, real=True)

>>> b = Symbol(”b”, real=True)
>>> z = Symbol(”z”)

>>> X = Arcsin(”x”, a, b)

>>> density(X)(z)
1/(pi*sqrt((-a + z)*(b - z)))

>>> cdf(X)(z)
Piecewise((0, a > z),
(2*asin(sqrt((-a + z)/(-a + b)))/pi, b >= z),
(1, True))

sympy.stats.Benini(name, alpha, beta, sigma)

Create a Continuous Random Variable with a Benini distribution.
The density of the Benini distribution is given by
( )
−α log σ
x
2
−β log [ σ
x
] α 2β log σx
f (x) := e +
x x

This is a heavy-tailed distrubtion and is also known as the log-Rayleigh distribution.

5.29. Stats 1225

SymPy Documentation, Release 1.3

Parameters alpha : Real number, α > 0, a shape

beta : Real number, β > 0, a shape
sigma : Real number, σ > 0, a scale
Returns A RandomSymbol.

References

[R539], [R540]

Examples

>>> from sympy.stats import Benini, density

>>> from sympy import Symbol, simplify, pprint

>>> alpha = Symbol(”alpha”, positive=True)

>>> beta = Symbol(”beta”, positive=True)
>>> sigma = Symbol(”sigma”, positive=True)
>>> z = Symbol(”z”)

>>> X = Benini(”x”, alpha, beta, sigma)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
/ / z \\ / z \ 2/ z \
| 2*beta*log|-----|| - alpha*log|-----| - beta*log |-----|
|alpha \sigma/| \sigma/ \sigma/
|----- + -----------------|*e
\ z z /

sympy.stats.Beta(name, alpha, beta)

Create a Continuous Random Variable with a Beta distribution.
The density of the Beta distribution is given by

xα−1 (1 − x)β−1
f (x) :=
B(α, β)

with x ∈ [0, 1].

Parameters alpha : Real number, α > 0, a shape
beta : Real number, β > 0, a shape
Returns A RandomSymbol.

References

[R541], [R542]

1226 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Beta, density, E, variance

>>> from sympy import Symbol, simplify, pprint, expand_func

>>> alpha = Symbol(”alpha”, positive=True)

>>> beta = Symbol(”beta”, positive=True)
>>> z = Symbol(”z”)

>>> X = Beta(”x”, alpha, beta)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
alpha - 1 beta - 1
z *(-z + 1)
---------------------------
B(alpha, beta)

>>> expand_func(simplify(E(X, meijerg=True)))

alpha/(alpha + beta)

>>> simplify(variance(X, meijerg=True)) #doctest: +SKIP

alpha*beta/((alpha + beta)**2*(alpha + beta + 1))

sympy.stats.BetaPrime(name, alpha, beta)

Create a continuous random variable with a Beta prime distribution.
The density of the Beta prime distribution is given by

xα−1 (1 + x)−α−β
f (x) :=
B(α, β)

with x > 0.
Parameters alpha : Real number, α > 0, a shape
beta : Real number, β > 0, a shape
Returns A RandomSymbol.

References

[R543], [R544]

Examples

>>> from sympy.stats import BetaPrime, density

>>> from sympy import Symbol, pprint

>>> alpha = Symbol(”alpha”, positive=True)

>>> beta = Symbol(”beta”, positive=True)
>>> z = Symbol(”z”)

5.29. Stats 1227

SymPy Documentation, Release 1.3

>>> X = BetaPrime(”x”, alpha, beta)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
alpha - 1 -alpha - beta
z *(z + 1)
-------------------------------
B(alpha, beta)

sympy.stats.Cauchy(name, x0, gamma)

Create a continuous random variable with a Cauchy distribution.
The density of the Cauchy distribution is given by
( )
1 x − x0 1
f (x) := arctan +
π γ 2

Parameters x0 : Real number, the location

gamma : Real number, γ > 0, the scale
Returns A RandomSymbol.

References

[R545], [R546]

Examples

>>> from sympy.stats import Cauchy, density

>>> from sympy import Symbol

>>> x0 = Symbol(”x0”)
>>> gamma = Symbol(”gamma”, positive=True)
>>> z = Symbol(”z”)

>>> X = Cauchy(”x”, x0, gamma)

>>> density(X)(z)
1/(pi*gamma*(1 + (-x0 + z)**2/gamma**2))

sympy.stats.Chi(name, k)
Create a continuous random variable with a Chi distribution.
The density of the Chi distribution is given by

21−k/2 xk−1 e−x

2
/2
f (x) :=
Γ(k/2)

with x ≥ 0.
Parameters k : A positive Integer, k > 0, the number of degrees of freedom
Returns A RandomSymbol.

1228 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R547], [R548]

Examples

>>> from sympy.stats import Chi, density, E, std

>>> from sympy import Symbol, simplify

>>> k = Symbol(”k”, integer=True)

>>> z = Symbol(”z”)

>>> X = Chi(”x”, k)

>>> density(X)(z)
2**(-k/2 + 1)*z**(k - 1)*exp(-z**2/2)/gamma(k/2)

sympy.stats.ChiNoncentral(name, k, l)
Create a continuous random variable with a non-central Chi distribution.
The density of the non-central Chi distribution is given by

e−(x +λ )/2 xk λ
2 2

f (x) := Ik/2−1 (λx)

(λx)k/2

with x ≥ 0. Here, Iν (x) is the modified Bessel function of the first kind (page 536).
Parameters k : A positive Integer, k > 0, the number of degrees of freedom
l : Shift parameter
Returns A RandomSymbol.

References

[R549]

Examples

>>> from sympy.stats import ChiNoncentral, density, E, std

>>> from sympy import Symbol, simplify

>>> k = Symbol(”k”, integer=True)

>>> l = Symbol(”l”)
>>> z = Symbol(”z”)

>>> X = ChiNoncentral(”x”, k, l)

>>> density(X)(z)
l*z**k*(l*z)**(-k/2)*exp(-l**2/2 - z**2/2)*besseli(k/2 - 1, l*z)

5.29. Stats 1229

SymPy Documentation, Release 1.3

sympy.stats.ChiSquared(name, k)
Create a continuous random variable with a Chi-squared distribution.
The density of the Chi-squared distribution is given by
1
( k ) x 2 −1 e− 2
k x
f (x) := k
2 Γ 2
2

with x ≥ 0.
Parameters k : A positive Integer, k > 0, the number of degrees of freedom
Returns A RandomSymbol.

References

[R550], [R551]

Examples

>>> from sympy.stats import ChiSquared, density, E, variance

>>> from sympy import Symbol, simplify, gammasimp, expand_func

>>> k = Symbol(”k”, integer=True, positive=True)

>>> z = Symbol(”z”)

>>> X = ChiSquared(”x”, k)

>>> density(X)(z)
2**(-k/2)*z**(k/2 - 1)*exp(-z/2)/gamma(k/2)

>>> gammasimp(E(X))
k

>>> simplify(expand_func(variance(X)))
2*k

sympy.stats.Dagum(name, p, a, b)
Create a continuous random variable with a Dagum distribution.
The density of the Dagum distribution is given by
( ( x )ap )
ap b
x (( x )a + 1)p+1
f (x) :=
b

with x > 0.
Parameters p : Real number, p > 0, a shape
a : Real number, a > 0, a shape
b : Real number, b > 0, a scale
Returns A RandomSymbol.

1230 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R552]

Examples

>>> from sympy.stats import Dagum, density, cdf

>>> from sympy import Symbol, simplify

>>> p = Symbol(”p”, positive=True)

>>> b = Symbol(”b”, positive=True)
>>> a = Symbol(”a”, positive=True)
>>> z = Symbol(”z”)

>>> X = Dagum(”x”, p, a, b)

>>> density(X)(z)
a*p*(z/b)**(a*p)*((z/b)**a + 1)**(-p - 1)/z

>>> cdf(X)(z)
Piecewise(((1 + (z/b)**(-a))**(-p), z >= 0), (0, True))

sympy.stats.Erlang(name, k, l)
Create a continuous random variable with an Erlang distribution.
The density of the Erlang distribution is given by

λk xk−1 e−λx
f (x) :=
(k − 1)!

with x ∈ [0, ∞].

Parameters k : Integer
l : Real number, λ > 0, the rate
Returns A RandomSymbol.

References

[R553], [R554]

Examples

>>> from sympy.stats import Erlang, density, cdf, E, variance

>>> from sympy import Symbol, simplify, pprint

>>> k = Symbol(”k”, integer=True, positive=True)

>>> l = Symbol(”l”, positive=True)
>>> z = Symbol(”z”)

5.29. Stats 1231

SymPy Documentation, Release 1.3

>>> X = Erlang(”x”, k, l)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
k k - 1 -l*z
l *z *e
---------------
Gamma(k)

>>> C = cdf(X, meijerg=True)(z)

>>> pprint(C, use_unicode=False)
/ -2*I*pi*k
|k*e *lowergamma(k, l*z)
|------------------------------- for z >= 0
< Gamma(k + 1)
|
| 0 otherwise
\

>>> simplify(E(X))
k/l

>>> simplify(variance(X))
k/l**2

sympy.stats.Exponential(name, rate)
Create a continuous random variable with an Exponential distribution.
The density of the exponential distribution is given by

f (x) := λ exp(−λx)

with x > 0. Note that the expected value is 1/λ.

Parameters rate : A positive Real number, λ > 0, the rate (or inverse
scale/inverse mean)
Returns A RandomSymbol.

References

[R555], [R556]

Examples

>>> from sympy.stats import Exponential, density, cdf, E

>>> from sympy.stats import variance, std, skewness
>>> from sympy import Symbol

>>> l = Symbol(”lambda”, positive=True)

>>> z = Symbol(”z”)

1232 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> X = Exponential(”x”, l)

>>> density(X)(z)
lambda*exp(-lambda*z)

>>> cdf(X)(z)
Piecewise((1 - exp(-lambda*z), z >= 0), (0, True))

>>> E(X)
1/lambda

>>> variance(X)
lambda**(-2)

>>> skewness(X)
2

>>> X = Exponential('x', 10)

>>> density(X)(z)
10*exp(-10*z)

>>> E(X)
1/10

>>> std(X)
1/10

sympy.stats.FDistribution(name, d1, d2)

Create a continuous random variable with a F distribution.
The density of the F distribution is given by
√
d
(d1 x)d1 d2 2
(d1 x+d2 )d1 +d2
f (x) := ( d1 )
xB 2 , d22

with x > 0.
Parameters d1 : d1 > 0, where d_1 is the degrees of freedom (n_1 - 1)
d2 : d2 > 0, where d_2 is the degrees of freedom (n_2 - 1)
Returns A RandomSymbol.

References

[R557], [R558]

Examples

5.29. Stats 1233

SymPy Documentation, Release 1.3

>>> from sympy.stats import FDistribution, density

>>> from sympy import Symbol, simplify, pprint

>>> d1 = Symbol(”d1”, positive=True)

>>> d2 = Symbol(”d2”, positive=True)
>>> z = Symbol(”z”)

>>> X = FDistribution(”x”, d1, d2)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
d2
-- ______________________________
2 / d1 -d1 - d2
d2 *\/ (d1*z) *(d1*z + d2)
--------------------------------------
/d1 d2\
z*B|--, --|
\2 2 /

sympy.stats.FisherZ(name, d1, d2)

Create a Continuous Random Variable with an Fisher’s Z distribution.
The density of the Fisher’s Z distribution is given by
d /2 d /2
2d11 d22 ed 1 z
f (x) :=
B(d1 /2, d2 /2) (d1 e2z + d2 )(d1 +d2 )/2

Parameters d1 : d1 > 0, degree of freedom

d2 : d2 > 0, degree of freedom
Returns A RandomSymbol.

References

[R559], [R560]

Examples

>>> from sympy.stats import FisherZ, density

>>> from sympy import Symbol, simplify, pprint

>>> d1 = Symbol(”d1”, positive=True)

>>> d2 = Symbol(”d2”, positive=True)
>>> z = Symbol(”z”)

>>> X = FisherZ(”x”, d1, d2)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
d1 d2
(continues on next page)

1234 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

d1 d2 - -- - --
-- -- 2 2
2 2 / 2*z \ d1*z
2*d1 *d2 *\d1*e + d2/ *e
-----------------------------------------
/d1 d2\
B|--, --|
\2 2 /

sympy.stats.Frechet(name, a, s=1, m=0)

Create a continuous random variable with a Frechet distribution.
The density of the Frechet distribution is given by
( )−1−α
α x−m x−m −α
f (x) := e−( s )
s s

with x ≥ m.
Parameters a : Real number, a ∈ (0, ∞) the shape
s : Real number, s ∈ (0, ∞) the scale
m : Real number, m ∈ (−∞, ∞) the minimum
Returns A RandomSymbol.

References

[R561]

Examples

>>> from sympy.stats import Frechet, density, E, std, cdf

>>> from sympy import Symbol, simplify

>>> a = Symbol(”a”, positive=True)

>>> s = Symbol(”s”, positive=True)
>>> m = Symbol(”m”, real=True)
>>> z = Symbol(”z”)

>>> X = Frechet(”x”, a, s, m)

>>> density(X)(z)
a*((-m + z)/s)**(-a - 1)*exp(-((-m + z)/s)**(-a))/s

>>> cdf(X)(z)
Piecewise((exp(-((-m + z)/s)**(-a)), m <= z), (0, True))

sympy.stats.Gamma(name, k, theta)
Create a continuous random variable with a Gamma distribution.

5.29. Stats 1235

SymPy Documentation, Release 1.3

The density of the Gamma distribution is given by

1
xk−1 e− θ
x
f (x) :=
Γ(k)θk

with x ∈ [0, 1].

Parameters k : Real number, k > 0, a shape
theta : Real number, θ > 0, a scale
Returns A RandomSymbol.

References

[R562], [R563]

Examples

>>> from sympy.stats import Gamma, density, cdf, E, variance

>>> from sympy import Symbol, pprint, simplify

>>> k = Symbol(”k”, positive=True)

>>> theta = Symbol(”theta”, positive=True)
>>> z = Symbol(”z”)

>>> X = Gamma(”x”, k, theta)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
-z
-----
-k k - 1 theta
theta *z *e
---------------------
Gamma(k)

>>> C = cdf(X, meijerg=True)(z)

>>> pprint(C, use_unicode=False)
/ / z \
|k*lowergamma|k, -----|
| \ theta/
<---------------------- for z >= 0
| Gamma(k + 1)
|
\ 0 otherwise

>>> E(X)
k*theta

>>> V = simplify(variance(X))
>>> pprint(V, use_unicode=False)
2
k*theta

1236 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.stats.GammaInverse(name, a, b)
Create a continuous random variable with an inverse Gamma distribution.
The density of the inverse Gamma distribution is given by
( )
β α −α−1 −β
f (x) := x exp
Γ(α) x
with x > 0.
Parameters a : Real number, a > 0 a shape
b : Real number, b > 0 a scale
Returns A RandomSymbol.

References

[R564]

Examples

>>> from sympy.stats import GammaInverse, density, cdf, E, variance

>>> from sympy import Symbol, pprint

>>> a = Symbol(”a”, positive=True)

>>> b = Symbol(”b”, positive=True)
>>> z = Symbol(”z”)

>>> X = GammaInverse(”x”, a, b)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
-b
---
a -a - 1 z
b *z *e
---------------
Gamma(a)

>>> cdf(X)(z)
Piecewise((uppergamma(a, b/z)/gamma(a), z > 0), (0, True))

sympy.stats.Kumaraswamy(name, a, b)
Create a Continuous Random Variable with a Kumaraswamy distribution.
The density of the Kumaraswamy distribution is given by

f (x) := abxa−1 (1 − xa )b−1

with x ∈ [0, 1].

Parameters a : Real number, a > 0 a shape
b : Real number, b > 0 a shape
Returns A RandomSymbol.

5.29. Stats 1237

SymPy Documentation, Release 1.3

References

[R565]

Examples

>>> from sympy.stats import Kumaraswamy, density, E, variance, cdf

>>> from sympy import Symbol, simplify, pprint

>>> a = Symbol(”a”, positive=True)

>>> b = Symbol(”b”, positive=True)
>>> z = Symbol(”z”)

>>> X = Kumaraswamy(”x”, a, b)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
b - 1
a - 1 / a \
a*b*z *\- z + 1/

>>> cdf(X)(z)
Piecewise((0, z < 0),
(-(-z**a + 1)**b + 1, z <= 1),
(1, True))

sympy.stats.Laplace(name, mu, b)
Create a continuous random variable with a Laplace distribution.
The density of the Laplace distribution is given by
( )
1 |x − µ|
f (x) := exp −
2b b

Parameters mu : Real number or a list/matrix, the location (mean) or the

location vector
b : Real number or a positive definite matrix, representing a scale
or the covariance matrix.
Returns A RandomSymbol.

References

[R566], [R567]

Examples

>>> from sympy.stats import Laplace, density, cdf

>>> from sympy import Symbol, pprint

1238 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> mu = Symbol(”mu”)
>>> b = Symbol(”b”, positive=True)
>>> z = Symbol(”z”)

>>> X = Laplace(”x”, mu, b)

>>> density(X)(z)
exp(-Abs(mu - z)/b)/(2*b)

>>> cdf(X)(z)
Piecewise((exp((-mu + z)/b)/2, mu > z),
(-exp((mu - z)/b)/2 + 1, True))

>>> L = Laplace('L', [1, 2], [[1, 0], [0, 1]])

>>> pprint(density(L)(1, 2), use_unicode=False)
5 / ____\
e *besselk\0, \/ 35 /
---------------------
pi

sympy.stats.Logistic(name, mu, s)
Create a continuous random variable with a logistic distribution.
The density of the logistic distribution is given by

e−(x−µ)/s
f (x) := ( )2
s 1 + e−(x−µ)/s

Parameters mu : Real number, the location (mean)

s : Real number, s > 0 a scale
Returns A RandomSymbol.

References

[R568], [R569]

Examples

>>> from sympy.stats import Logistic, density, cdf

>>> from sympy import Symbol

>>> mu = Symbol(”mu”, real=True)

>>> s = Symbol(”s”, positive=True)
>>> z = Symbol(”z”)

>>> X = Logistic(”x”, mu, s)

>>> density(X)(z)
exp((mu - z)/s)/(s*(exp((mu - z)/s) + 1)**2)

5.29. Stats 1239

SymPy Documentation, Release 1.3

>>> cdf(X)(z)
1/(exp((mu - z)/s) + 1)

sympy.stats.LogNormal(name, mean, std)

Create a continuous random variable with a log-normal distribution.
The density of the log-normal distribution is given by
1 (ln x−µ)2
f (x) := √ e− 2σ2
x 2πσ 2
with x ≥ 0.
Parameters mu : Real number, the log-scale
sigma : Real number, σ 2 > 0 a shape
Returns A RandomSymbol.

References

[R570], [R571]

Examples

>>> from sympy.stats import LogNormal, density

>>> from sympy import Symbol, simplify, pprint

>>> mu = Symbol(”mu”, real=True)

>>> sigma = Symbol(”sigma”, positive=True)
>>> z = Symbol(”z”)

>>> X = LogNormal(”x”, mu, sigma)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
2
-(-mu + log(z))
-----------------
2
___ 2*sigma
\/ 2 *e
------------------------
____
2*\/ pi *sigma*z

>>> X = LogNormal('x', 0, 1) # Mean 0, standard deviation 1

>>> density(X)(z)
sqrt(2)*exp(-log(z)**2/2)/(2*sqrt(pi)*z)

sympy.stats.Maxwell(name, a)
Create a continuous random variable with a Maxwell distribution.

1240 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The density of the Maxwell distribution is given by

√
2 x2 e−x /(2a )
2 2

f (x) :=
π a3
with x ≥ 0.
Parameters a : Real number, a > 0
Returns A RandomSymbol.

References

[R572], [R573]

Examples

>>> from sympy.stats import Maxwell, density, E, variance

>>> from sympy import Symbol, simplify

>>> a = Symbol(”a”, positive=True)

>>> z = Symbol(”z”)

>>> X = Maxwell(”x”, a)

>>> density(X)(z)
sqrt(2)*z**2*exp(-z**2/(2*a**2))/(sqrt(pi)*a**3)

>>> E(X)
2*sqrt(2)*a/sqrt(pi)

>>> simplify(variance(X))
a**2*(-8 + 3*pi)/pi

sympy.stats.Nakagami(name, mu, omega)

Create a continuous random variable with a Nakagami distribution.
The density of the Nakagami distribution is given by
2µµ ( µ )
f (x) := x 2µ−1
exp − x2
Γ(µ)ω µ ω

with x > 0.
Parameters mu : Real number, µ ≥ 1
2 a shape
omega : Real number, ω > 0, the spread
Returns A RandomSymbol.

References

[R574]

5.29. Stats 1241

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Nakagami, density, E, variance, cdf

>>> from sympy import Symbol, simplify, pprint

>>> mu = Symbol(”mu”, positive=True)

>>> omega = Symbol(”omega”, positive=True)
>>> z = Symbol(”z”)

>>> X = Nakagami(”x”, mu, omega)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
2
-mu*z
-------
mu -mu 2*mu - 1 omega
2*mu *omega *z *e
----------------------------------
Gamma(mu)

>>> simplify(E(X))
sqrt(mu)*sqrt(omega)*gamma(mu + 1/2)/gamma(mu + 1)

>>> V = simplify(variance(X))
>>> pprint(V, use_unicode=False)
2
omega*Gamma (mu + 1/2)
omega - -----------------------
Gamma(mu)*Gamma(mu + 1)

>>> cdf(X)(z)
Piecewise((lowergamma(mu, mu*z**2/omega)/gamma(mu), z > 0),
(0, True))

sympy.stats.Normal(name, mean, std)

Create a continuous random variable with a Normal distribution.
The density of the Normal distribution is given by
1 (x−µ)2
f (x) := √ e− 2σ2
σ 2π
Parameters mu : Real number or a list representing the mean or the mean
vector
sigma : Real number or a positive definite sqaure matrix,
σ 2 > 0 the variance
Returns A RandomSymbol.

References

[R575], [R576]

1242 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Normal, density, E, std, cdf, skewness

>>> from sympy import Symbol, simplify, pprint, factor, together, factor_terms

>>> mu = Symbol(”mu”)
>>> sigma = Symbol(”sigma”, positive=True)
>>> z = Symbol(”z”)
>>> y = Symbol(”y”)
>>> X = Normal(”x”, mu, sigma)

>>> density(X)(z)
sqrt(2)*exp(-(-mu + z)**2/(2*sigma**2))/(2*sqrt(pi)*sigma)

>>> C = simplify(cdf(X))(z) # it needs a little more help...

>>> pprint(C, use_unicode=False)
/ ___ \
|\/ 2 *(-mu + z)|
erf|---------------|
\ 2*sigma / 1
-------------------- + -
2 2

>>> simplify(skewness(X))
0

>>> X = Normal(”x”, 0, 1) # Mean 0, standard deviation 1

>>> density(X)(z)
sqrt(2)*exp(-z**2/2)/(2*sqrt(pi))

>>> E(2*X + 1)
1

>>> simplify(std(2*X + 1))

2

>>> m = Normal('X', [1, 2], [[2, 1], [1, 2]])

>>> from sympy.stats.joint_rv import marginal_distribution
>>> pprint(density(m)(y, z))
/ y 1\ /2*y z\ / z \ / y 2*z \
|- - + -|*|--- - -| + |- - + 1|*|- - + --- - 1|
___ \ 2 2/ \ 3 3/ \ 2 / \ 3 3 /
\/ 3 *e
------------------------------------------------------
6*pi

>>> marginal_distribution(m, m[0])(1)

1/(2*sqrt(pi))

sympy.stats.Pareto(name, xm, alpha)

Create a continuous random variable with the Pareto distribution.
The density of the Pareto distribution is given by
α xα
m
f (x) :=
xα+1

5.29. Stats 1243

SymPy Documentation, Release 1.3

with x ∈ [xm , ∞].

Parameters xm : Real number, xm > 0, a scale
alpha : Real number, α > 0, a shape
Returns A RandomSymbol.

References

[R577], [R578]

Examples

>>> from sympy.stats import Pareto, density

>>> from sympy import Symbol

>>> xm = Symbol(”xm”, positive=True)

>>> beta = Symbol(”beta”, positive=True)
>>> z = Symbol(”z”)

>>> X = Pareto(”x”, xm, beta)

>>> density(X)(z)
beta*xm**beta*z**(-beta - 1)

sympy.stats.QuadraticU(name, a, b)
Create a Continuous Random Variable with a U-quadratic distribution.
The density of the U-quadratic distribution is given by

f (x) := α(x − β)2

with x ∈ [a, b].

Parameters a : Real number
b : Real number, a < b
Returns A RandomSymbol.

References

[R579]

Examples

>>> from sympy.stats import QuadraticU, density, E, variance

>>> from sympy import Symbol, simplify, factor, pprint

>>> a = Symbol(”a”, real=True)

>>> b = Symbol(”b”, real=True)
>>> z = Symbol(”z”)

1244 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> X = QuadraticU(”x”, a, b)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
/ 2
| / a b \
|12*|- - - - + z|
| \ 2 2 /
<----------------- for And(b >= z, a <= z)
| 3
| (-a + b)
|
\ 0 otherwise

sympy.stats.RaisedCosine(name, mu, s)
Create a Continuous Random Variable with a raised cosine distribution.
The density of the raised cosine distribution is given by
( ( ))
1 x−µ
f (x) := 1 + cos π
2s s

with x ∈ [µ − s, µ + s].
Parameters mu : Real number
s : Real number, s > 0
Returns A RandomSymbol.

References

[R580]

Examples

>>> from sympy.stats import RaisedCosine, density, E, variance

>>> from sympy import Symbol, simplify, pprint

>>> mu = Symbol(”mu”, real=True)

>>> s = Symbol(”s”, positive=True)
>>> z = Symbol(”z”)

>>> X = RaisedCosine(”x”, mu, s)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
/ /pi*(-mu + z)\
|cos|------------| + 1
| \ s /
<--------------------- for And(z >= mu - s, z <= mu + s)
| 2*s
|
\ 0 otherwise

5.29. Stats 1245

SymPy Documentation, Release 1.3

sympy.stats.Rayleigh(name, sigma)
Create a continuous random variable with a Rayleigh distribution.
The density of the Rayleigh distribution is given by
x −x2 /2σ2
f (x) := e
σ2
with x > 0.
Parameters sigma : Real number, σ > 0
Returns A RandomSymbol.

References

[R581], [R582]

Examples

>>> from sympy.stats import Rayleigh, density, E, variance

>>> from sympy import Symbol, simplify

>>> sigma = Symbol(”sigma”, positive=True)

>>> z = Symbol(”z”)

>>> X = Rayleigh(”x”, sigma)

>>> density(X)(z)
z*exp(-z**2/(2*sigma**2))/sigma**2

>>> E(X)
sqrt(2)*sqrt(pi)*sigma/2

>>> variance(X)
-pi*sigma**2/2 + 2*sigma**2

sympy.stats.StudentT(name, nu)
Create a continuous random variable with a student’s t distribution.
The density of the student’s t distribution is given by
( ) ( )− ν+1
Γ ν+1
2( ) x2 2

f (x) := √ ν 1+
νπΓ 2 ν

Parameters nu : Real number, ν > 0, the degrees of freedom

Returns A RandomSymbol.

References

[R583], [R584]

1246 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import StudentT, density, E, variance, cdf

>>> from sympy import Symbol, simplify, pprint

>>> nu = Symbol(”nu”, positive=True)

>>> z = Symbol(”z”)

>>> X = StudentT(”x”, nu)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
nu 1
- -- - -
2 2
/ 2\
| z |
|1 + --|
\ nu/
-----------------
____ / nu\
\/ nu *B|1/2, --|
\ 2 /

>>> cdf(X)(z)
1/2 + z*gamma(nu/2 + 1/2)*hyper((1/2, nu/2 + 1/2), (3/2,),
-z**2/nu)/(sqrt(pi)*sqrt(nu)*gamma(nu/2))

sympy.stats.Triangular(name, a, b, c)
Create a continuous random variable with a triangular distribution.
The density of the triangular distribution is given by


 0 for x < a,


 2(x−a)
 (b−a)(c−a) for a ≤ x < c,

2
f (x) := b−a for x = c,




2(b−x)
for c < x ≤ b,

 (b−a)(b−c)

0 for b < x.

Parameters a : Real number, a ∈ (−∞, ∞)

b : Real number, a < b
c : Real number, a ≤ c ≤ b
Returns A RandomSymbol.

References

[R585], [R586]

5.29. Stats 1247

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Triangular, density, E

>>> from sympy import Symbol, pprint

>>> a = Symbol(”a”)
>>> b = Symbol(”b”)
>>> c = Symbol(”c”)
>>> z = Symbol(”z”)

>>> X = Triangular(”x”, a,b,c)

>>> pprint(density(X)(z), use_unicode=False)

/ -2*a + 2*z
|----------------- for And(a <= z, c > z)
|(-a + b)*(-a + c)
|
| 2
| ------ for c = z
< -a + b
|
| 2*b - 2*z
|---------------- for And(b >= z, c < z)
|(-a + b)*(b - c)
|
\ 0 otherwise

sympy.stats.Uniform(name, left, right)

Create a continuous random variable with a uniform distribution.
The density of the uniform distribution is given by
{
1
for x ∈ [a, b]
f (x) := b−a
0 otherwise

with x ∈ [a, b].

Parameters a : Real number, −∞ < a the left boundary
b : Real number, a < b < ∞ the right boundary
Returns A RandomSymbol.

References

[R587], [R588]

Examples

>>> from sympy.stats import Uniform, density, cdf, E, variance, skewness

>>> from sympy import Symbol, simplify

1248 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> a = Symbol(”a”, negative=True)

>>> b = Symbol(”b”, positive=True)
>>> z = Symbol(”z”)

>>> X = Uniform(”x”, a, b)

>>> density(X)(z)
Piecewise((1/(-a + b), (b >= z) & (a <= z)), (0, True))

>>> cdf(X)(z) # doctest: +SKIP

-a/(-a + b) + z/(-a + b)

>>> simplify(E(X))
a/2 + b/2

>>> simplify(variance(X))
a**2/12 - a*b/6 + b**2/12

sympy.stats.UniformSum(name, n)
Create a continuous random variable with an Irwin-Hall distribution.
The probability distribution function depends on a single parameter n which is an integer.
The density of the Irwin-Hall distribution is given by
⌊x⌋
∑ ( )
1 k n
f (x) := (−1) (x − k)n−1
(n − 1)! k
k=0

Parameters n : A positive Integer, n > 0

Returns A RandomSymbol.

References

[R589], [R590]

Examples

>>> from sympy.stats import UniformSum, density, cdf

>>> from sympy import Symbol, pprint

>>> n = Symbol(”n”, integer=True)

>>> z = Symbol(”z”)

>>> X = UniformSum(”x”, n)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
floor(z)
___
\ `
(continues on next page)

5.29. Stats 1249

SymPy Documentation, Release 1.3

(continued from previous page)

\ k n - 1 /n\
) (-1) *(-k + z) *| |
/ \k/
/__,
k = 0
--------------------------------
(n - 1)!

>>> cdf(X)(z)
Piecewise((0, z < 0), (Sum((-1)**_k*(-_k + z)**n*binomial(n, _k),
(_k, 0, floor(z)))/factorial(n), n >= z), (1, True))

Compute cdf with specific ‘x’ and ‘n’ values as follows : >>> cdf(UniformSum(“x”, 5),
evaluate=False)(2).doit() 9/40
The argument evaluate=False prevents an attempt at evaluation of the sum for general
n, before the argument 2 is passed.
sympy.stats.VonMises(name, mu, k)
Create a Continuous Random Variable with a von Mises distribution.
The density of the von Mises distribution is given by
eκ cos(x−µ)
f (x) :=
2πI0 (κ)
with x ∈ [0, 2π].
Parameters mu : Real number, measure of location
k : Real number, measure of concentration
Returns A RandomSymbol.

References

[R591], [R592]

Examples

>>> from sympy.stats import VonMises, density, E, variance

>>> from sympy import Symbol, simplify, pprint

>>> mu = Symbol(”mu”)
>>> k = Symbol(”k”, positive=True)
>>> z = Symbol(”z”)

>>> X = VonMises(”x”, mu, k)

>>> D = density(X)(z)
>>> pprint(D, use_unicode=False)
k*cos(mu - z)
e
------------------
2*pi*besseli(0, k)

1250 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.stats.Weibull(name, alpha, beta)

Create a continuous random variable with a Weibull distribution.
The density of the Weibull distribution is given by
{ ( )k−1
e−(x/λ)
k
k x
λ λ x≥0
f (x) :=
0 x<0

Parameters lambda : Real number, λ > 0 a scale

k : Real number, k > 0 a shape
Returns A RandomSymbol.

References

[R593], [R594]

Examples

>>> from sympy.stats import Weibull, density, E, variance

>>> from sympy import Symbol, simplify

>>> l = Symbol(”lambda”, positive=True)

>>> k = Symbol(”k”, positive=True)
>>> z = Symbol(”z”)

>>> X = Weibull(”x”, l, k)

>>> density(X)(z)
k*(z/lambda)**(k - 1)*exp(-(z/lambda)**k)/lambda

>>> simplify(E(X))
lambda*gamma(1 + 1/k)

>>> simplify(variance(X))
lambda**2*(-gamma(1 + 1/k)**2 + gamma(1 + 2/k))

sympy.stats.WignerSemicircle(name, R)
Create a continuous random variable with a Wigner semicircle distribution.
The density of the Wigner semicircle distribution is given by
2 √ 2
f (x) := R − x2
πR2
with x ∈ [−R, R].
Parameters R : Real number, R > 0, the radius
Returns A RandomSymbol.

References

[R595], [R596]

5.29. Stats 1251

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import WignerSemicircle, density, E

>>> from sympy import Symbol, simplify

>>> R = Symbol(”R”, positive=True)

>>> z = Symbol(”z”)

>>> X = WignerSemicircle(”x”, R)

>>> density(X)(z)
2*sqrt(R**2 - z**2)/(pi*R**2)

>>> E(X)
0

sympy.stats.ContinuousRV(symbol, density, set=Interval(-oo, oo))

Create a Continuous Random Variable given the following:
– a symbol – a probability density function – set on which the pdf is valid (defaults to
entire real line)
Returns a RandomSymbol.
Many common continuous random variable types are already implemented. This function
should be necessary only very rarely.

Examples

>>> from sympy import Symbol, sqrt, exp, pi

>>> from sympy.stats import ContinuousRV, P, E

>>> x = Symbol(”x”)

>>> pdf = sqrt(2)*exp(-x**2/2)/(2*sqrt(pi)) # Normal distribution

>>> X = ContinuousRV(x, pdf)

>>> E(X)
0
>>> P(X>0)
1/2

5.29.3 Interface

sympy.stats.P(condition, given_condition=None, numsamples=None, evaluate=True,

**kwargs)
Probability that a condition is true, optionally given a second condition
Parameters condition : Combination of Relationals containing RandomSym-
bols
The condition of which you want to compute the probability

1252 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

given_condition : Combination of Relationals containing RandomSymbols

A conditional expression. P(X > 1, X > 0) is expectation of X > 1 given
X>0
numsamples : int
Enables sampling and approximates the probability with this many
samples
evaluate : Bool (defaults to True)
In case of continuous systems return unevaluated integral

Examples

>>> from sympy.stats import P, Die

>>> from sympy import Eq
>>> X, Y = Die('X', 6), Die('Y', 6)
>>> P(X > 3)
1/2
>>> P(Eq(X, 5), X > 2) # Probability that X == 5 given that X > 2
1/4
>>> P(X > Y)
5/12

class sympy.stats.Probability
Symbolic expression for the probability.

Examples

>>> from sympy.stats import Probability, Normal

>>> from sympy import Integral
>>> X = Normal(”X”, 0, 1)
>>> prob = Probability(X > 1)
>>> prob
Probability(X > 1)

Integral representation:

>>> prob.rewrite(Integral)
Integral(sqrt(2)*exp(-_z**2/2)/(2*sqrt(pi)), (_z, 1, oo))

Evaluation of the integral:

>>> prob.evaluate_integral()
sqrt(2)*(-sqrt(2)*sqrt(pi)*erf(sqrt(2)/2) + sqrt(2)*sqrt(pi))/(4*sqrt(pi))

sympy.stats.E(expr, condition=None, numsamples=None, evaluate=True, **kwargs)

Returns the expected value of a random expression
Parameters expr : Expr containing RandomSymbols
The expression of which you want to compute the expectation value
given : Expr containing RandomSymbols
A conditional expression. E(X, X>0) is expectation of X given X > 0

5.29. Stats 1253

SymPy Documentation, Release 1.3

numsamples : int
Enables sampling and approximates the expectation with this many
samples
evalf : Bool (defaults to True)
If sampling return a number rather than a complex expression
evaluate : Bool (defaults to True)
In case of continuous systems return unevaluated integral

Examples

>>> from sympy.stats import E, Die

>>> X = Die('X', 6)
>>> E(X)
7/2
>>> E(2*X + 1)
8

>>> E(X, X > 3) # Expectation of X given that it is above 3

5

class sympy.stats.Expectation
Symbolic expression for the expectation.

Examples

>>> from sympy.stats import Expectation, Normal, Probability

>>> from sympy import symbols, Integral
>>> mu = symbols(”mu”)
>>> sigma = symbols(”sigma”, positive=True)
>>> X = Normal(”X”, mu, sigma)
>>> Expectation(X)
Expectation(X)
>>> Expectation(X).evaluate_integral().simplify()
mu

To get the integral expression of the expectation:

>>> Expectation(X).rewrite(Integral)
Integral(sqrt(2)*X*exp(-(X - mu)**2/(2*sigma**2))/(2*sqrt(pi)*sigma), (X, -oo,␣
,→oo))

The same integral expression, in more abstract terms:

>>> Expectation(X).rewrite(Probability)
Integral(x*Probability(Eq(X, x)), (x, -oo, oo))

This class is aware of some properties of the expectation:

1254 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import a

>>> Expectation(a*X)
Expectation(a*X)
>>> Y = Normal(”Y”, 0, 1)
>>> Expectation(X + Y)
Expectation(X + Y)

To expand the Expectation into its expression, use doit():

>>> Expectation(X + Y).doit()

Expectation(X) + Expectation(Y)
>>> Expectation(a*X + Y).doit()
a*Expectation(X) + Expectation(Y)
>>> Expectation(a*X + Y)
Expectation(a*X + Y)

sympy.stats.density(expr, condition=None, evaluate=True, numsamples=None,

**kwargs)
Probability density of a random expression, optionally given a second condition.
This density will take on different forms for different types of probability spaces. Discrete
variables produce Dicts. Continuous variables produce Lambdas.
Parameters expr : Expr containing RandomSymbols
The expression of which you want to compute the density value
condition : Relational containing RandomSymbols
A conditional expression. density(X > 1, X > 0) is density of X > 1
given X > 0
numsamples : int
Enables sampling and approximates the density with this many sam-
ples

Examples

>>> from sympy.stats import density, Die, Normal

>>> from sympy import Symbol

>>> x = Symbol('x')
>>> D = Die('D', 6)
>>> X = Normal(x, 0, 1)

>>> density(D).dict
{1: 1/6, 2: 1/6, 3: 1/6, 4: 1/6, 5: 1/6, 6: 1/6}
>>> density(2*D).dict
{2: 1/6, 4: 1/6, 6: 1/6, 8: 1/6, 10: 1/6, 12: 1/6}
>>> density(X)(x)
sqrt(2)*exp(-x**2/2)/(2*sqrt(pi))

sympy.stats.given(expr, condition=None, **kwargs)

Conditional Random Expression From a random expression and a condition on that ex-
pression creates a new probability space from the condition and returns the same ex-
pression on that conditional probability space.

5.29. Stats 1255

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import given, density, Die

>>> X = Die('X', 6)
>>> Y = given(X, X > 3)
>>> density(Y).dict
{4: 1/3, 5: 1/3, 6: 1/3}

Following convention, if the condition is a random symbol then that symbol is considered
fixed.

>>> from sympy.stats import Normal

>>> from sympy import pprint
>>> from sympy.abc import z

>>> X = Normal('X', 0, 1)
>>> Y = Normal('Y', 0, 1)
>>> pprint(density(X + Y, Y)(z), use_unicode=False)
2
-(-Y + z)
-----------
___ 2
\/ 2 *e
------------------
____
2*\/ pi

sympy.stats.where(condition, given_condition=None, **kwargs)

Returns the domain where a condition is True.

Examples

>>> from sympy.stats import where, Die, Normal

>>> from sympy import symbols, And

>>> D1, D2 = Die('a', 6), Die('b', 6)

>>> a, b = D1.symbol, D2.symbol
>>> X = Normal('x', 0, 1)

>>> where(X**2<1)
Domain: (-1 < x) & (x < 1)

>>> where(X**2<1).set
Interval.open(-1, 1)

>>> where(And(D1<=D2 , D2<3))

Domain: (Eq(a, 1) & Eq(b, 1)) | (Eq(a, 1) & Eq(b, 2)) | (Eq(a, 2) & Eq(b, 2))

sympy.stats.variance(X, condition=None, **kwargs)

Variance of a random expression
Expectation of (X-E(X))**2

1256 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Die, E, Bernoulli, variance

>>> from sympy import simplify, Symbol

>>> X = Die('X', 6)
>>> p = Symbol('p')
>>> B = Bernoulli('B', p, 1, 0)

>>> variance(2*X)
35/3

>>> simplify(variance(B))
p*(-p + 1)

class sympy.stats.Variance
Symbolic expression for the variance.

Examples

>>> from sympy import symbols, Integral

>>> from sympy.stats import Normal, Expectation, Variance, Probability
>>> mu = symbols(”mu”, positive=True)
>>> sigma = symbols(”sigma”, positive=True)
>>> X = Normal(”X”, mu, sigma)
>>> Variance(X)
Variance(X)
>>> Variance(X).evaluate_integral()
sigma**2

Integral representation of the underlying calculations:

>>> Variance(X).rewrite(Integral)
Integral(sqrt(2)*(X - Integral(sqrt(2)*X*exp(-(X - mu)**2/(2*sigma**2))/
,→(2*sqrt(pi)*sigma), (X, -oo, oo)))**2*exp(-(X - mu)**2/(2*sigma**2))/

,→(2*sqrt(pi)*sigma), (X, -oo, oo))

Integral representation, without expanding the PDF:

>>> Variance(X).rewrite(Probability)
-Integral(x*Probability(Eq(X, x)), (x, -oo, oo))**2 +␣
,→Integral(x**2*Probability(Eq(X, x)), (x, -oo, oo))

Rewrite the variance in terms of the expectation

>>> Variance(X).rewrite(Expectation)
-Expectation(X)**2 + Expectation(X**2)

Some transformations based on the properties of the variance may happen:

>>> from sympy.abc import a

>>> Y = Normal(”Y”, 0, 1)
>>> Variance(a*X)
Variance(a*X)

5.29. Stats 1257

SymPy Documentation, Release 1.3

To expand the variance in its expression, use doit():

>>> Variance(a*X).doit()
a**2*Variance(X)
>>> Variance(X + Y)
Variance(X + Y)
>>> Variance(X + Y).doit()
2*Covariance(X, Y) + Variance(X) + Variance(Y)

sympy.stats.covariance(X, Y, condition=None, **kwargs)

Covariance of two random expressions
The expectation that the two variables will rise and fall together
Covariance(X,Y) = E( (X-E(X)) * (Y-E(Y)) )

Examples

>>> from sympy.stats import Exponential, covariance

>>> from sympy import Symbol

>>> rate = Symbol('lambda', positive=True, real=True, finite=True)

>>> X = Exponential('X', rate)
>>> Y = Exponential('Y', rate)

>>> covariance(X, X)
lambda**(-2)
>>> covariance(X, Y)
0
>>> covariance(X, Y + rate*X)
1/lambda

class sympy.stats.Covariance
Symbolic expression for the covariance.

Examples

>>> from sympy.stats import Covariance

>>> from sympy.stats import Normal
>>> X = Normal(”X”, 3, 2)
>>> Y = Normal(”Y”, 0, 1)
>>> Z = Normal(”Z”, 0, 1)
>>> W = Normal(”W”, 0, 1)
>>> cexpr = Covariance(X, Y)
>>> cexpr
Covariance(X, Y)

Evaluate the covariance, X and Y are independent, therefore zero is the result:

>>> cexpr.evaluate_integral()
0

Rewrite the covariance expression in terms of expectations:

1258 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.stats import Expectation

>>> cexpr.rewrite(Expectation)
Expectation(X*Y) - Expectation(X)*Expectation(Y)

In order to expand the argument, use doit():

>>> from sympy.abc import a, b, c, d
>>> Covariance(a*X + b*Y, c*Z + d*W)
Covariance(a*X + b*Y, c*Z + d*W)
>>> Covariance(a*X + b*Y, c*Z + d*W).doit()
a*c*Covariance(X, Z) + a*d*Covariance(W, X) + b*c*Covariance(Y, Z) +␣
,→b*d*Covariance(W, Y)

This class is aware of some properties of the covariance:

>>> Covariance(X, X).doit()
Variance(X)
>>> Covariance(a*X, b*Y).doit()
a*b*Covariance(X, Y)

sympy.stats.std(X, condition=None, **kwargs)

Standard Deviation of a random expression
Square root of the Expectation of (X-E(X))**2

Examples

>>> from sympy.stats import Bernoulli, std

>>> from sympy import Symbol, simplify

>>> p = Symbol('p')
>>> B = Bernoulli('B', p, 1, 0)

>>> simplify(std(B))
sqrt(p*(-p + 1))

sympy.stats.sample(expr, condition=None, **kwargs)

A realization of the random expression

Examples

>>> from sympy.stats import Die, sample

>>> X, Y, Z = Die('X', 6), Die('Y', 6), Die('Z', 6)

>>> die_roll = sample(X + Y + Z) # A random realization of three dice

sympy.stats.sample_iter(expr, condition=None, numsamples=oo, **kwargs)

Returns an iterator of realizations from the expression given a condition
expr: Random expression to be realized condition: A conditional expression (optional)
numsamples: Length of the iterator (defaults to infinity)
See also:
Sample, sampling_P, sampling_E, sample_iter_lambdify, sample_iter_subs

5.29. Stats 1259

SymPy Documentation, Release 1.3

Examples

>>> from sympy.stats import Normal, sample_iter

>>> X = Normal('X', 0, 1)
>>> expr = X*X + 3
>>> iterator = sample_iter(expr, numsamples=3)
>>> list(iterator) # doctest: +SKIP
[12, 4, 7]

5.29.4 Mechanics

SymPy Stats employs a relatively complex class hierarchy.

RandomDomains are a mapping of variables to possible values. For example we might say that
the symbol Symbol('x') can take on the values {1, 2, 3, 4, 5, 6}.
class sympy.stats.rv.RandomDomain
A PSpace, or Probability Space, combines a RandomDomain with a density to provide prob-
abilistic information. For example the above domain could be enhanced by a finite density
{1:1/6, 2:1/6, 3:1/6, 4:1/6, 5:1/6, 6:1/6} to fully define the roll of a fair die named
x.
class sympy.stats.rv.PSpace
A RandomSymbol represents the PSpace’s symbol ‘x’ inside of SymPy expressions.
class sympy.stats.rv.RandomSymbol
The RandomDomain and PSpace classes are almost never directly instantiated. Instead they
are subclassed for a variety of situations.
RandomDomains and PSpaces must be sufficiently general to represent domains and spaces
of several variables with arbitrarily complex densities. This generality is often unneces-
sary. Instead we often build SingleDomains and SinglePSpaces to represent single, univariate
events and processes such as a single die or a single normal variable.
class sympy.stats.rv.SinglePSpace
class sympy.stats.rv.SingleDomain
Another common case is to collect together a set of such univariate random variables. A
collection of independent SinglePSpaces or SingleDomains can be brought together to form
a ProductDomain or ProductPSpace. These objects would be useful in representing three
dice rolled together for example.
class sympy.stats.rv.ProductDomain
class sympy.stats.rv.ProductPSpace
The Conditional adjective is added whenever we add a global condition to a RandomDomain
or PSpace. A common example would be three independent dice where we know their sum
to be greater than 12.
class sympy.stats.rv.ConditionalDomain
We specialize further into Finite and Continuous versions of these classes to represent finite
(such as dice) and continuous (such as normals) random variables.
class sympy.stats.frv.FiniteDomain

1260 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.stats.frv.FinitePSpace
class sympy.stats.crv.ContinuousDomain
class sympy.stats.crv.ContinuousPSpace
Additionally there are a few specialized classes that implement certain common random vari-
able types. There is for example a DiePSpace that implements SingleFinitePSpace and a
NormalPSpace that implements SingleContinuousPSpace.
class sympy.stats.frv_types.DiePSpace
class sympy.stats.crv_types.NormalPSpace
RandomVariables can be extracted from these objects using the PSpace.values method.
As previously mentioned SymPy Stats employs a relatively complex class structure. Inher-
itance is widely used in the implementation of end-level classes. This tactic was chosen to
balance between the need to allow SymPy to represent arbitrarily defined random variables
and optimizing for common cases. This complicates the code but is structured to only be
important to those working on extending SymPy Stats to other random variable types.
Users will not use this class structure. Instead these mechanics are exposed through variable
creation functions Die, Coin, FiniteRV, Normal, Exponential, etc…. These build the appropri-
ate SinglePSpaces and return the corresponding RandomVariable. Conditional and Product
spaces are formed in the natural construction of SymPy expressions and the use of interface
functions E, Given, Density, etc….
sympy.stats.Die()
sympy.stats.Normal()
There are some additional functions that may be useful. They are largely used internally.
sympy.stats.rv.random_symbols(expr)
Returns all RandomSymbols within a SymPy Expression.
sympy.stats.rv.pspace(expr)
Returns the underlying Probability Space of a random expression.
For internal use.

Examples

>>> from sympy.stats import pspace, Normal

>>> from sympy.stats.rv import IndependentProductPSpace
>>> X = Normal('X', 0, 1)
>>> pspace(2*X + 1) == X.pspace
True

sympy.stats.rv.rs_swap(a, b)
Build a dictionary to swap RandomSymbols based on their underlying symbol.
i.e. if X = ('x', pspace1) and Y = ('x', pspace2) then X and Y match and the key,
value pair {X:Y} will appear in the result
Inputs: collections a and b of random variables which share common symbols Output:
dict mapping RVs in a to RVs in b

5.29. Stats 1261

SymPy Documentation, Release 1.3

5.30 ODE

5.30.1 User Functions

These are functions that are imported into the global namespace with from sympy import *.
These functions (unlike Hint Functions (page 1270), below) are intended for use by ordinary
users of SymPy.

dsolve()

sympy.solvers.ode.dsolve(eq, func=None, hint=’default’, simplify=True, ics=None,

xi=None, eta=None, x0=0, n=6, **kwargs)
Solves any (supported) kind of ordinary differential equation and system of or-
dinary differential equations.

Examples

>>> from sympy import Function, dsolve, Eq, Derivative, sin, cos, symbols
>>> from sympy.abc import x
>>> f = Function('f')
>>> dsolve(Derivative(f(x), x, x) + 9*f(x), f(x))
Eq(f(x), C1*sin(3*x) + C2*cos(3*x))

>>> eq = sin(x)*cos(f(x)) + cos(x)*sin(f(x))*f(x).diff(x)

>>> dsolve(eq, hint='1st_exact')
[Eq(f(x), -acos(C1/cos(x)) + 2*pi), Eq(f(x), acos(C1/cos(x)))]
>>> dsolve(eq, hint='almost_linear')
[Eq(f(x), -acos(C1/cos(x)) + 2*pi), Eq(f(x), acos(C1/cos(x)))]
>>> t = symbols('t')
>>> x, y = symbols('x, y', cls=Function)
>>> eq = (Eq(Derivative(x(t),t), 12*t*x(t) + 8*y(t)), Eq(Derivative(y(t),t),␣
,→21*x(t) + 7*t*y(t)))

>>> dsolve(eq)
[Eq(x(t), C1*x0(t) + C2*x0(t)*Integral(8*exp(Integral(7*t, t))*exp(Integral(12*t,␣
,→t))/x0(t)**2, t)),

Eq(y(t), C1*y0(t) + C2*(y0(t)*Integral(8*exp(Integral(7*t, t))*exp(Integral(12*t,␣

,→t))/x0(t)**2, t) +

exp(Integral(7*t, t))*exp(Integral(12*t, t))/x0(t)))]

>>> eq = (Eq(Derivative(x(t),t),x(t)*y(t)*sin(t)), Eq(Derivative(y(t),t),
,→y(t)**2*sin(t)))

>>> dsolve(eq)
{Eq(x(t), -exp(C1)/(C2*exp(C1) - cos(t))), Eq(y(t), -1/(C1 - cos(t)))}

For Single Ordinary Differential Equation

It is classified under this when number of equation in eq is one. Usage

dsolve(eq, f(x), hint) -> Solve ordinary differential equation eq for func-
tion f(x), using method hint.
Details

1262 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

eq can be any supported ordinary differential equation (see the ode

(page 1316) docstring for supported methods). This can either be an
Equality (page 167), or an expression, which is assumed to be equal to 0.
f(x) is a function of one variable whose derivatives in that variable
make up the ordinary differential equation eq. In many cases it is not
necessary to provide this; it will be autodetected (and an error raised if it
couldn’t be detected).
hint is the solving method that you want dsolve to use. Use
classify_ode(eq, f(x)) to get all of the possible hints for an ODE.
The default hint, default, will use whatever hint is returned first by
classify_ode() (page 1265). See Hints below for more options that you
can use for hint.
simplify enables simplification by odesimp() (page 1270). See its doc-
string for more information. Turn this off, for example, to disable solving
of solutions for func or simplification of arbitrary constants. It will still in-
tegrate with this hint. Note that the solution may contain more arbitrary
constants than the order of the ODE with this option enabled.
xi and eta are the infinitesimal functions of an ordinary differential
equation. They are the infinitesimals of the Lie group of point transfor-
mations for which the differential equation is invariant. The user can
specify values for the infinitesimals. If nothing is specified, xi and eta are
calculated using infinitesimals() (page 1268) with the help of various
heuristics.
ics is the set of initial/boundary conditions for the differential equation.
It should be given in the form of {f(x0): x1, f(x).diff(x).subs(x,
x2): x3} and so on. For power series solutions, if no initial conditions
are specified f(0) is assumed to be C0 and the power series solution is
calculated about 0.
x0 is the point about which the power series solution of a differential
equation is to be evaluated.
n gives the exponent of the dependent variable up to which the power series
solution of a differential equation is to be evaluated.
Hints
Aside from the various solving methods, there are also some meta-hints that you
can pass to dsolve() (page 1262):
default: This uses whatever hint is returned first by classify_ode()
(page 1265). This is the default argument to dsolve() (page 1262).
all: To make dsolve() (page 1262) apply all relevant classification hints,
use dsolve(ODE, func, hint=”all”). This will return a dictionary of
hint:solution terms. If a hint causes dsolve to raise the NotImplement-
edError, value of that hint’s key will be the exception object raised. The
dictionary will also include some special keys:
• order: The order of the ODE. See also ode_order() (page 1342) in
deutils.py.
• best: The simplest hint; what would be returned by best below.
• best_hint: The hint that would produce the solution given by best. If
more than one hint produces the best solution, the first one in the tuple

5.30. ODE 1263

SymPy Documentation, Release 1.3

returned by classify_ode() (page 1265) is chosen.

• default: The solution that would be returned by default. This is the one
produced by the hint that appears first in the tuple returned by clas-
sify_ode() (page 1265).
all_Integral: This is the same as all, except if a hint also has a correspond-
ing _Integral hint, it only returns the _Integral hint. This is useful if all
causes dsolve() (page 1262) to hang because of a difficult or impossible
integral. This meta-hint will also be much faster than all, because inte-
grate() (page 128) is an expensive routine.
best: To have dsolve() (page 1262) try all methods and return the simplest
one. This takes into account whether the solution is solvable in the function,
whether it contains any Integral classes (i.e. unevaluatable integrals), and
which one is the shortest in size.
See also the classify_ode() (page 1265) docstring for more info on hints, and
the ode (page 1316) docstring for a list of all supported hints.
Tips
• You can declare the derivative of an unknown function this way:

>>> from sympy import Function, Derivative

>>> from sympy.abc import x # x is the independent variable
>>> f = Function(”f”)(x) # f is a function of x
>>> # f_ will be the derivative of f with respect to x
>>> f_ = Derivative(f, x)

• See test_ode.py for many tests, which serves also as a set of examples for how to
use dsolve() (page 1262).
• dsolve() (page 1262) always returns an Equality (page 167) class (except for the
case when the hint is all or all_Integral). If possible, it solves the solution explic-
itly for the function being solved for. Otherwise, it returns an implicit solution.
• Arbitrary constants are symbols named C1, C2, and so on.
• Because all solutions should be mathematically equivalent, some hints may return
the exact same result for an ODE. Often, though, two different hints will return the
same solution formatted differently. The two should be equivalent. Also note that
sometimes the values of the arbitrary constants in two different solutions may not
be the same, because one constant may have “absorbed” other constants into it.
• Do help(ode.ode_<hintname>) to get help more information on a specific hint,
where <hintname> is the name of a hint without _Integral.

For System Of Ordinary Differential Equations

Usage
dsolve(eq, func) -> Solve a system of ordinary differential equations eq for
func being list of functions including x(t), y(t), z(t) where number of functions
in the list depends upon the number of equations provided in eq.
Details

1264 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

eq can be any supported system of ordinary differential equations This can

either be an Equality (page 167), or an expression, which is assumed to be
equal to 0.
func holds x(t) and y(t) being functions of one variable which together
with some of their derivatives make up the system of ordinary differential
equation eq. It is not necessary to provide this; it will be autodetected (and
an error raised if it couldn’t be detected).
Hints
The hints are formed by parameters returned by classify_sysode, combining
them give hints name used later for forming method name.

classify_ode()

sympy.solvers.ode.classify_ode(eq, func=None, dict=False, ics=None, **kwargs)

Returns a tuple of possible dsolve() (page 1262) classifications for an ODE.
The tuple is ordered so that first item is the classification that dsolve() (page 1262)
uses to solve the ODE by default. In general, classifications at the near the beginning
of the list will produce better solutions faster than those near the end, thought there
are always exceptions. To make dsolve() (page 1262) use a different classification,
use dsolve(ODE, func, hint=<classification>). See also the dsolve() (page 1262)
docstring for different meta-hints you can use.
If dict is true, classify_ode() (page 1265) will return a dictionary of hint:match ex-
pression terms. This is intended for internal use by dsolve() (page 1262). Note that
because dictionaries are ordered arbitrarily, this will most likely not be in the same order
as the tuple.
You can get help on different hints by executing help(ode.ode_hintname), where hint-
name is the name of the hint without _Integral.
See allhints (page 1270) or the ode (page 1316) docstring for a list of all supported
hints that can be returned from classify_ode() (page 1265).

Notes

These are remarks on hint names.

_Integral
If a classification has _Integral at the end, it will return the expression with
an unevaluated Integral (page 714) class in it. Note that a hint may do this
anyway if integrate() (page 128) cannot do the integral, though just using
an _Integral will do so much faster. Indeed, an _Integral hint will always
be faster than its corresponding hint without _Integral because integrate()
(page 128) is an expensive routine. If dsolve() (page 1262) hangs, it is probably
because integrate() (page 128) is hanging on a tough or impossible integral.
Try using an _Integral hint or all_Integral to get it return something.
Note that some hints do not have _Integral counterparts. This
is because integrate() is not used in solving the ODE for those
method. For example, nth order linear homogeneous ODEs with con-
stant coefficients do not require integration to solve, so there is no

5.30. ODE 1265

SymPy Documentation, Release 1.3

nth_linear_homogeneous_constant_coeff_Integrate hint. You can eas-

ily evaluate any unevaluated Integral (page 714)s in an expression by doing
expr.doit().
Ordinals
Some hints contain an ordinal such as 1st_linear. This is to help differentiate
them from other hints, as well as from other methods that may not be imple-
mented yet. If a hint has nth in it, such as the nth_linear hints, this means
that the method used to applies to ODEs of any order.
indep and dep
Some hints contain the words indep or dep. These reference the independent
variable and the dependent function, respectively. For example, if an ODE is in
terms of f (x), then indep will refer to x and dep will refer to f .
subs
If a hints has the word subs in it, it means the the ODE is solved by substi-
tuting the expression given after the word subs for a single dummy variable.
This is usually in terms of indep and dep as above. The substituted expression
will be written only in characters allowed for names of Python objects, mean-
ing operators will be spelled out. For example, indep/dep will be written as
indep_div_dep.
coeff
The word coeff in a hint refers to the coefficients of something in the ODE,
usually of the derivative terms. See the docstring for the individual methods
for more info (help(ode)). This is contrast to coefficients, as in undeter-
mined_coefficients, which refers to the common name of a method.
_best
Methods that have more than one fundamental way to solve will have a hint for
each sub-method and a _best meta-classification. This will evaluate all hints
and return the best, using the same considerations as the normal best meta-
hint.

Examples

>>> from sympy import Function, classify_ode, Eq

>>> from sympy.abc import x
>>> f = Function('f')
>>> classify_ode(Eq(f(x).diff(x), 0), f(x))
('separable', '1st_linear', '1st_homogeneous_coeff_best',
'1st_homogeneous_coeff_subs_indep_div_dep',
'1st_homogeneous_coeff_subs_dep_div_indep',
'1st_power_series', 'lie_group',
'nth_linear_constant_coeff_homogeneous',
'separable_Integral', '1st_linear_Integral',
'1st_homogeneous_coeff_subs_indep_div_dep_Integral',
'1st_homogeneous_coeff_subs_dep_div_indep_Integral')
>>> classify_ode(f(x).diff(x, 2) + 3*f(x).diff(x) + 2*f(x) - 4)
('nth_linear_constant_coeff_undetermined_coefficients',
'nth_linear_constant_coeff_variation_of_parameters',
'nth_linear_constant_coeff_variation_of_parameters_Integral')

1266 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

checkodesol()

sympy.solvers.ode.checkodesol(ode, sol, func=None, order=’auto’,

solve_for_func=True)
Substitutes sol into ode and checks that the result is 0.
This only works when func is one function, like f (x). sol can be a single solution or a list
of solutions. Each solution may be an Equality (page 167) that the solution satisfies,
e.g. Eq(f(x), C1), Eq(f(x) + C1, 0); or simply an Expr (page 115), e.g. f(x) -
C1. In most cases it will not be necessary to explicitly identify the function, but if the
function cannot be inferred from the original equation it can be supplied through the
func argument.
If a sequence of solutions is passed, the same sort of container will be used to return the
result for each solution.
It tries the following methods, in order, until it finds zero equivalence:
1. Substitute the solution for f in the original equation. This only works if ode is solved
for f . It will attempt to solve it first unless solve_for_func == False.
2. Take n derivatives of the solution, where n is the order of ode, and check to see if
that is equal to the solution. This only works on exact ODEs.
3. Take the 1st, 2nd, …, nth derivatives of the solution, each time solving for the deriva-
tive of f of that order (this will always be possible because f is a linear operator).
Then back substitute each derivative into ode in reverse order.
This function returns a tuple. The first item in the tuple is True if the substitution re-
sults in 0, and False otherwise. The second item in the tuple is what the substitution
results in. It should always be 0 if the first item is True. Sometimes this function will
return False even when an expression is identically equal to 0. This happens when sim-
plify() (page 1185) does not reduce the expression to 0. If an expression returned by
this function vanishes identically, then sol really is a solution to the ode.
If this function seems to hang, it is probably because of a hard simplification.
To use this function to test, test the first item of the tuple.

Examples

>>> from sympy import Eq, Function, checkodesol, symbols

>>> x, C1 = symbols('x,C1')
>>> f = Function('f')
>>> checkodesol(f(x).diff(x), Eq(f(x), C1))
(True, 0)
>>> assert checkodesol(f(x).diff(x), C1)[0]
>>> assert not checkodesol(f(x).diff(x), x)[0]
>>> checkodesol(f(x).diff(x, 2), x**2)
(False, 2)

homogeneous_order()

sympy.solvers.ode.homogeneous_order(eq, *symbols)
Returns the order n if g is homogeneous and None if it is not homogeneous.

5.30. ODE 1267

SymPy Documentation, Release 1.3

Determines if a function is homogeneous and if so of what order. A function f (x, y, · · · ) is

homogeneous of order n if f (tx, ty, · · · ) = tn f (x, y, · · · ).
If the function is of two variables, F (x, y), then f being homogeneous of any order is
equivalent to being able to rewrite F (x, y) as G(x/y) or H(y/x). This fact is used to solve 1st
order ordinary differential equations whose coefficients are homogeneous of the same
order (see the docstrings of ode_1st_homogeneous_coeff_subs_dep_div_indep() and
ode_1st_homogeneous_coeff_subs_indep_div_dep()).
Symbols can be functions, but every argument of the function must be a symbol, and the
arguments of the function that appear in the expression must match those given in the
list of symbols. If a declared function appears with different arguments than given in
the list of symbols, None is returned.

Examples

>>> from sympy import Function, homogeneous_order, sqrt

>>> from sympy.abc import x, y
>>> f = Function('f')
>>> homogeneous_order(f(x), f(x)) is None
True
>>> homogeneous_order(f(x,y), f(y, x), x, y) is None
True
>>> homogeneous_order(f(x), f(x), x)
1
>>> homogeneous_order(x**2*f(x)/sqrt(x**2+f(x)**2), x, f(x))
2
>>> homogeneous_order(x**2+f(x), x, f(x)) is None
True

infinitesimals()

sympy.solvers.ode.infinitesimals(eq, func=None, order=None, hint=’default’,

match=None)
The infinitesimal functions of an ordinary differential equation, ξ(x, y) and η(x, y), are the
infinitesimals of the Lie group of point transformations for which the differential equation
is invariant. So, the ODE y ′ = f (x, y) would admit a Lie group x∗ = X(x, y; ε) = x + εξ(x, y),
y ∗ = Y (x, y; ε) = y + εη(x, y) such that (y ∗ )′ = f (x∗ , y ∗ ). A change of coordinates, to r(x, y)
and s(x, y), can be performed so this Lie group becomes the translation group, r∗ = r and
s∗ = s + ε. They are tangents to the coordinate curves of the new system.
Consider the transformation (x, y) → (X, Y ) such that the differential equation remains
invariant. ξ and η are the tangents to the transformed coordinates X and Y , at ε = 0.
( ) ( )
∂X(x, y; ε) ∂Y (x, y; ε)
|ε=0 = ξ, |ε=0 = η,
∂ε ∂ε

The infinitesimals can be found by solving the following PDE:

>>> from sympy import Function, diff, Eq, pprint

>>> from sympy.abc import x, y
>>> xi, eta, h = map(Function, ['xi', 'eta', 'h'])
>>> h = h(x, y) # dy/dx = h
>>> eta = eta(x, y)
(continues on next page)

1268 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> xi = xi(x, y)
>>> genform = Eq(eta.diff(x) + (eta.diff(y) - xi.diff(x))*h
... - (xi.diff(y))*h**2 - xi*(h.diff(x)) - eta*(h.diff(y)), 0)
>>> pprint(genform)
/d d \ d 2 d
|--(eta(x, y)) - --(xi(x, y))|*h(x, y) - eta(x, y)*--(h(x, y)) - h (x, y)*--(x
\dy dx / dy dy
<BLANKLINE>
d d
i(x, y)) - xi(x, y)*--(h(x, y)) + --(eta(x, y)) = 0
dx dx

Solving the above mentioned PDE is not trivial, and can be solved only by making intel-
ligent assumptions for ξ and η (heuristics). Once an infinitesimal is found, the attempt
to find more heuristics stops. This is done to optimise the speed of solving the differ-
ential equation. If a list of all the infinitesimals is needed, hint should be flagged as
all, which gives the complete list of infinitesimals. If the infinitesimals for a particular
heuristic needs to be found, it can be passed as a flag to hint.

References

• Solving differential equations by Symmetry Groups, John Starrett, pp. 1 - pp. 14

Examples

>>> from sympy import Function, diff

>>> from sympy.solvers.ode import infinitesimals
>>> from sympy.abc import x
>>> f = Function('f')
>>> eq = f(x).diff(x) - x**2*f(x)
>>> infinitesimals(eq)
[{eta(x, f(x)): exp(x**3/3), xi(x, f(x)): 0}]

checkinfsol()

sympy.solvers.ode.checkinfsol(eq, infinitesimals, func=None, order=None)

This function is used to check if the given infinitesimals are the actual infinitesimals of
the given first order differential equation. This method is specific to the Lie Group Solver
of ODEs.
As of now, it simply checks, by substituting the infinitesimals in the partial differential
equation.
( )
∂η ∂η ∂ξ ∂ξ ∂h ∂h
+ − ∗h− ∗ h2 − ξ −η =0
∂x ∂y ∂x ∂y ∂x ∂y
dy
where η, and ξ are the infinitesimals and h(x, y) = dx

The infinitesimals should be given in the form of a list of dicts [{xi(x, y): inf, eta(x,
y): inf}], corresponding to the output of the function infinitesimals. It returns a list of
values of the form [(True/False, sol)] where sol is the value obtained after substi-
tuting the infinitesimals in the PDE. If it is True, then sol would be 0.

5.30. ODE 1269

SymPy Documentation, Release 1.3

5.30.2 Hint Functions

These functions are intended for internal use by dsolve() (page 1262) and others. Unlike
User Functions (page 1262), above, these are not intended for every-day use by ordinary
SymPy users. Instead, functions such as dsolve() (page 1262) should be used. Nonetheless,
these functions contain useful information in their docstrings on the various ODE solving
methods. For this reason, they are documented here.

allhints

sympy.solvers.ode.allhints = ('separable', '1st_exact', '1st_linear', 'Bernoulli', 'Riccati

This is a list of hints in the order that they should be preferred by classify_ode()
(page 1265). In general, hints earlier in the list should produce simpler solutions than
those later in the list (for ODEs that fit both). For now, the order of this list is based on
empirical observations by the developers of SymPy.
The hint used by dsolve() (page 1262) for a specific ODE can be overridden (see the
docstring).
In general, _Integral hints are grouped at the end of the list, unless there is a method
that returns an unevaluable integral most of the time (which go near the end of the list
anyway). default, all, best, and all_Integral meta-hints should not be included in
this list, but _best and _Integral hints should be included.

odesimp

sympy.solvers.ode.odesimp(eq, func, order, constants, hint)

Simplifies ODEs, including trying to solve for func and running constantsimp()
(page 1272).
It may use knowledge of the type of solution that the hint returns to apply additional
simplifications.
It also attempts to integrate any Integral (page 714)s in the expression, if the hint is
not an _Integral hint.
This function should have no effect on expressions returned by dsolve() (page 1262),
as dsolve() (page 1262) already calls odesimp() (page 1270), but the individual hint
functions do not call odesimp() (page 1270) (because the dsolve() (page 1262) wrapper
does). Therefore, this function is designed for mainly internal use.

Examples

>>> from sympy import sin, symbols, dsolve, pprint, Function

>>> from sympy.solvers.ode import odesimp
>>> x , u2, C1= symbols('x,u2,C1')
>>> f = Function('f')

>>> eq = dsolve(x*f(x).diff(x) - f(x) - x*sin(f(x)/x), f(x),

... hint='1st_homogeneous_coeff_subs_indep_div_dep_Integral',
... simplify=False)
>>> pprint(eq, wrap_line=False)
(continues on next page)

1270 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

x
----
f(x)
/
|
| / 1 \
| -|u2 + -------|
| | /1 \|
| | sin|--||
| \ \u2//
log(f(x)) = log(C1) + | ---------------- d(u2)
| 2
| u2
|
/

>>> pprint(odesimp(eq, f(x), 1, {C1},

... hint='1st_homogeneous_coeff_subs_indep_div_dep'
... )) #doctest: +SKIP
x
--------- = C1
/f(x)\
tan|----|
\2*x /

constant_renumber

sympy.solvers.ode.constant_renumber(expr, symbolname, startnumber, endnum-

ber)
Renumber arbitrary constants in expr to have numbers 1 through N where N is end-
number - startnumber + 1 at most. In the process, this reorders expression terms in
a standard way.
This is a simple function that goes through and renumbers any Symbol (page 137) with
a name in the form symbolname + num where num is in the range from startnumber to
endnumber.
Symbols are renumbered based on .sort_key(), so they should be numbered roughly
in the order that they appear in the final, printed expression. Note that this ordering is
based in part on hashes, so it can produce different results on different machines.
The structure of this function is very similar to that of constantsimp() (page 1272).

Examples

>>> from sympy import symbols, Eq, pprint

>>> from sympy.solvers.ode import constant_renumber
>>> x, C0, C1, C2, C3, C4 = symbols('x,C:5')

Only constants in the given range (inclusive) are renumbered; the renumbering always
starts from 1:

5.30. ODE 1271

SymPy Documentation, Release 1.3

>>> constant_renumber(C1 + C3 + C4, 'C', 1, 3)

C1 + C2 + C4
>>> constant_renumber(C0 + C1 + C3 + C4, 'C', 2, 4)
C0 + 2*C1 + C2
>>> constant_renumber(C0 + 2*C1 + C2, 'C', 0, 1)
C1 + 3*C2
>>> pprint(C2 + C1*x + C3*x**2)
2
C1*x + C2 + C3*x
>>> pprint(constant_renumber(C2 + C1*x + C3*x**2, 'C', 1, 3))
2
C1 + C2*x + C3*x

constantsimp

sympy.solvers.ode.constantsimp(expr, constants)
Simplifies an expression with arbitrary constants in it.
This function is written specifically to work with dsolve() (page 1262), and is not in-
tended for general use.
Simplification is done by “absorbing” the arbitrary constants into other arbitrary con-
stants, numbers, and symbols that they are not independent of.
The symbols must all have the same name with numbers after it, for example, C1, C2,
C3. The symbolname here would be ‘C’, the startnumber would be 1, and the endnumber
would be 3. If the arbitrary constants are independent of the variable x, then the inde-
pendent symbol would be x. There is no need to specify the dependent function, such as
f(x), because it already has the independent symbol, x, in it.
Because terms are “absorbed” into arbitrary constants and because constants are
renumbered after simplifying, the arbitrary constants in expr are not necessarily equal
to the ones of the same name in the returned result.
If two or more arbitrary constants are added, multiplied, or raised to the power of each
other, they are first absorbed together into a single arbitrary constant. Then the new
constant is combined into other terms if necessary.
Absorption of constants is done with limited assistance:
1. terms of Add (page 163)s are collected to try join constants so ex (C1 cos(x)+C2 cos(x))
will simplify to ex C1 cos(x);
2. powers with exponents that are Add (page 163)s are expanded so eC1 +x will be sim-
plified to C1 ex .
Use constant_renumber() (page 1271) to renumber constants after simplification or
else arbitrary numbers on constants may appear, e.g. C1 + C3 x.
In rare cases, a single constant can be “simplified” into two constants. Every differential
equation solution should have as many arbitrary constants as the order of the differential
equation. The result here will be technically correct, but it may, for example, have C1
and C2 in an expression, when C1 is actually equal to C2 . Use your discretion in such
situations, and also take advantage of the ability to use hints in dsolve() (page 1262).

1272 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> from sympy.solvers.ode import constantsimp
>>> C1, C2, C3, x, y = symbols('C1, C2, C3, x, y')
>>> constantsimp(2*C1*x, {C1, C2, C3})
C1*x
>>> constantsimp(C1 + 2 + x, {C1, C2, C3})
C1 + x
>>> constantsimp(C1*C2 + 2 + C2 + C3*x, {C1, C2, C3})
C1 + C3*x

sol_simplicity

sympy.solvers.ode.ode_sol_simplicity(sol, func, trysolving=True)

Returns an extended integer representing how simple a solution to an ODE is.
The following things are considered, in order from most simple to least:
• sol is solved for func.
• sol is not solved for func, but can be if passed to solve (e.g., a solution returned by
dsolve(ode, func, simplify=False).
• If sol is not solved for func, then base the result on the length of sol, as computed
by len(str(sol)).
• If sol has any unevaluated Integral (page 714)s, this will automatically be consid-
ered less simple than any of the above.
This function returns an integer such that if solution A is simpler than solution B by
above metric, then ode_sol_simplicity(sola, func) < ode_sol_simplicity(solb,
func).
Currently, the following are the numbers returned, but if the heuristic is ever improved,
this may change. Only the ordering is guaranteed.

Simplicity Return
sol solved for func -2
sol not solved for func but can be -1
sol is not solved nor solvable for func len(str(sol))
sol contains an Integral (page 714) oo

oo here means the SymPy infinity, which should compare greater than any integer.
If you already know solve() (page 1328) cannot solve sol, you can use trysolv-
ing=False to skip that step, which is the only potentially slow step. For example,
dsolve() (page 1262) with the simplify=False flag should do this.
If sol is a list of solutions, if the worst solution in the list returns oo it returns that,
otherwise it returns len(str(sol)), that is, the length of the string representation of
the whole list.

5.30. ODE 1273

SymPy Documentation, Release 1.3

Examples

This function is designed to be passed to min as the key argument, such as

min(listofsolutions, key=lambda i: ode_sol_simplicity(i, f(x))).

>>> from sympy import symbols, Function, Eq, tan, cos, sqrt, Integral
>>> from sympy.solvers.ode import ode_sol_simplicity
>>> x, C1, C2 = symbols('x, C1, C2')
>>> f = Function('f')

>>> ode_sol_simplicity(Eq(f(x), C1*x**2), f(x))

-2
>>> ode_sol_simplicity(Eq(x**2 + f(x), C1), f(x))
-1
>>> ode_sol_simplicity(Eq(f(x), C1*Integral(2*x, x)), f(x))
oo
>>> eq1 = Eq(f(x)/tan(f(x)/(2*x)), C1)
>>> eq2 = Eq(f(x)/tan(f(x)/(2*x) + f(x)), C2)
>>> [ode_sol_simplicity(eq, f(x)) for eq in [eq1, eq2]]
[28, 35]
>>> min([eq1, eq2], key=lambda i: ode_sol_simplicity(i, f(x)))
Eq(f(x)/tan(f(x)/(2*x)), C1)

1st_exact

sympy.solvers.ode.ode_1st_exact(eq, func, order, match)

Solves 1st order exact ordinary differential equations.
A 1st order differential equation is called exact if it is the total differential of a function.
That is, the differential equation

P (x, y) ∂x + Q(x, y) ∂y = 0

is exact if there is some function F (x, y) such that P (x, y) = ∂F /∂x and Q(x, y) = ∂F /∂y. It
can be shown that a necessary and sufficient condition for a first order ODE to be exact
is that ∂P /∂y = ∂Q/∂x. Then, the solution will be as given below:

>>> from sympy import Function, Eq, Integral, symbols, pprint

>>> x, y, t, x0, y0, C1= symbols('x,y,t,x0,y0,C1')
>>> P, Q, F= map(Function, ['P', 'Q', 'F'])
>>> pprint(Eq(Eq(F(x, y), Integral(P(t, y), (t, x0, x)) +
... Integral(Q(x0, t), (t, y0, y))), C1))
x y
/ /
| |
F(x, y) = | P(t, y) dt + | Q(x0, t) dt = C1
| |
/ /
x0 y0

Where the first partials of P and Q exist and are continuous in a simply connected region.
A note: SymPy currently has no way to represent inert substitution on an expression,
so the hint 1st_exact_Integral will return an integral with dy. This is supposed to
represent the function that you are solving for.

1274 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

• http://en.wikipedia.org/wiki/Exact_differential_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 73

# indirect doctest

Examples

>>> from sympy import Function, dsolve, cos, sin

>>> from sympy.abc import x
>>> f = Function('f')
>>> dsolve(cos(f(x)) - (x*sin(f(x)) - f(x)**2)*f(x).diff(x),
... f(x), hint='1st_exact')
Eq(x*cos(f(x)) + f(x)**3/3, C1)

1st_homogeneous_coeff_best

sympy.solvers.ode.ode_1st_homogeneous_coeff_best(eq, func, order, match)

Returns the best solution to an ODE from the two hints
1st_homogeneous_coeff_subs_dep_div_indep and 1st_homogeneous_coeff_subs_indep_div_dep.
This is as determined by ode_sol_simplicity() (page 1273).
See the ode_1st_homogeneous_coeff_subs_indep_div_dep() (page 1277)
and ode_1st_homogeneous_coeff_subs_dep_div_indep() (page 1276) doc-
strings for more information on these hints. Note that there is no
ode_1st_homogeneous_coeff_best_Integral hint.

References

• http://en.wikipedia.org/wiki/Homogeneous_differential_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 59

# indirect doctest

Examples

>>> from sympy import Function, dsolve, pprint

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(2*x*f(x) + (x**2 + f(x)**2)*f(x).diff(x), f(x),
... hint='1st_homogeneous_coeff_best', simplify=False))
/ 2 \
| 3*x |
log|----- + 1|
| 2 |
\f (x) /
log(f(x)) = log(C1) - --------------
3

5.30. ODE 1275

SymPy Documentation, Release 1.3

1st_homogeneous_coeff_subs_dep_div_indep

sympy.solvers.ode.ode_1st_homogeneous_coeff_subs_dep_div_indep(eq, func, or-

der, match)
Solves a 1st order differential equation with homogeneous coefficients using the substi-
<dependent variable>
tution u1 = <independent variable> .

This is a differential equation

P (x, y) + Q(x, y)dy/dx = 0

such that P and Q are homogeneous and of the same order. A function F (x, y) is homo-
geneous of order n if F (xt, yt) = tn F (x, y). Equivalently, F (x, y) can be rewritten as G(y/x)
or H(x/y). See also the docstring of homogeneous_order() (page 1267).
If the coefficients P and Q in the differential equation above are homogeneous functions
of the same order, then it can be shown that the substitution y = u1 x (i.e. u1 = y/x) will
turn the differential equation into an equation separable in the variables x and u. If h(u1 )
is the function that results from making the substitution u1 = f (x)/x on P (x, f (x)) and g(u2 )
is the function that results from the substitution on Q(x, f (x)) in the differential equation
P (x, f (x)) + Q(x, f (x))f ′ (x) = 0, then the general solution is:

>>> from sympy import Function, dsolve, pprint

>>> from sympy.abc import x
>>> f, g, h = map(Function, ['f', 'g', 'h'])
>>> genform = g(f(x)/x) + h(f(x)/x)*f(x).diff(x)
>>> pprint(genform)
/f(x)\ /f(x)\ d
g|----| + h|----|*--(f(x))
\ x / \ x / dx
>>> pprint(dsolve(genform, f(x),
... hint='1st_homogeneous_coeff_subs_dep_div_indep_Integral'))
f(x)
----
x
/
|
| -h(u1)
log(x) = C1 + | ---------------- d(u1)
| u1*h(u1) + g(u1)
|
/

Where u1 h(u1 ) + g(u1 ) ̸= 0 and x ̸= 0.

See also the docstrings of ode_1st_homogeneous_coeff_best() (page 1275) and
ode_1st_homogeneous_coeff_subs_indep_div_dep() (page 1277).

References

• http://en.wikipedia.org/wiki/Homogeneous_differential_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 59

# indirect doctest

1276 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, dsolve

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(2*x*f(x) + (x**2 + f(x)**2)*f(x).diff(x), f(x),
... hint='1st_homogeneous_coeff_subs_dep_div_indep', simplify=False))
/ 3 \
|3*f(x) f (x)|
log|------ + -----|
| x 3 |
\ x /
log(x) = log(C1) - -------------------
3

1st_homogeneous_coeff_subs_indep_div_dep

sympy.solvers.ode.ode_1st_homogeneous_coeff_subs_indep_div_dep(eq, func, or-

der, match)
Solves a 1st order differential equation with homogeneous coefficients using the substi-
tution u2 = <independent variable>
<dependent variable> .

This is a differential equation

P (x, y) + Q(x, y)dy/dx = 0

such that P and Q are homogeneous and of the same order. A function F (x, y) is homo-
geneous of order n if F (xt, yt) = tn F (x, y). Equivalently, F (x, y) can be rewritten as G(y/x)
or H(x/y). See also the docstring of homogeneous_order() (page 1267).
If the coefficients P and Q in the differential equation above are homogeneous functions
of the same order, then it can be shown that the substitution x = u2 y (i.e. u2 = x/y) will
turn the differential equation into an equation separable in the variables y and u2 . If
h(u2 ) is the function that results from making the substitution u2 = x/f (x) on P (x, f (x))
and g(u2 ) is the function that results from the substitution on Q(x, f (x)) in the differential
equation P (x, f (x)) + Q(x, f (x))f ′ (x) = 0, then the general solution is:

>>> from sympy import Function, dsolve, pprint

>>> from sympy.abc import x
>>> f, g, h = map(Function, ['f', 'g', 'h'])
>>> genform = g(x/f(x)) + h(x/f(x))*f(x).diff(x)
>>> pprint(genform)
/ x \ / x \ d
g|----| + h|----|*--(f(x))
\f(x)/ \f(x)/ dx
>>> pprint(dsolve(genform, f(x),
... hint='1st_homogeneous_coeff_subs_indep_div_dep_Integral'))
x
----
f(x)
/
|
| -g(u2)
| ---------------- d(u2)
| u2*g(u2) + h(u2)
(continues on next page)

5.30. ODE 1277

SymPy Documentation, Release 1.3

(continued from previous page)

|
/
<BLANKLINE>
f(x) = C1*e

Where u2 g(u2 ) + h(u2 ) ̸= 0 and f (x) ̸= 0.

See also the docstrings of ode_1st_homogeneous_coeff_best() (page 1275) and
ode_1st_homogeneous_coeff_subs_dep_div_indep() (page 1276).

References

• http://en.wikipedia.org/wiki/Homogeneous_differential_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 59

# indirect doctest

Examples

>>> from sympy import Function, pprint, dsolve

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(2*x*f(x) + (x**2 + f(x)**2)*f(x).diff(x), f(x),
... hint='1st_homogeneous_coeff_subs_indep_div_dep',
... simplify=False))
/ 2 \
| 3*x |
log|----- + 1|
| 2 |
\f (x) /
log(f(x)) = log(C1) - --------------
3

1st_linear

sympy.solvers.ode.ode_1st_linear(eq, func, order, match)

Solves 1st order linear differential equations.
These are differential equations of the form

dy/dx + P (x)y = Q(x).

These kinds
∫ of differential equations can be solved in a general way. The integrating
factor e P (x) dx will turn the equation into a separable equation. The general solution is:
>>> from sympy import Function, dsolve, Eq, pprint, diff, sin
>>> from sympy.abc import x
>>> f, P, Q = map(Function, ['f', 'P', 'Q'])
>>> genform = Eq(f(x).diff(x) + P(x)*f(x), Q(x))
>>> pprint(genform)
d
(continues on next page)

1278 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

P(x)*f(x) + --(f(x)) = Q(x)
dx
>>> pprint(dsolve(genform, f(x), hint='1st_linear_Integral'))
/ / \
| | |
| | / | /
| | | | |
| | | P(x) dx | - | P(x) dx
| | | | |
| | / | /
f(x) = |C1 + | Q(x)*e dx|*e
| | |
\ / /

References

• http://en.wikipedia.org/wiki/Linear_differential_equation#First_order_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 92

# indirect doctest

Examples

>>> f = Function('f')
>>> pprint(dsolve(Eq(x*diff(f(x), x) - f(x), x**2*sin(x)),
... f(x), '1st_linear'))
f(x) = x*(C1 - cos(x))

Bernoulli

sympy.solvers.ode.ode_Bernoulli(eq, func, order, match)

Solves Bernoulli differential equations.
These are equations of the form

dy/dx + P (x)y = Q(x)y n , n ̸= 1‘.

The substitution w = 1/y 1−n will transform an equation of this form into one that is linear
(see the docstring of ode_1st_linear() (page 1278)). The general solution is:

>>> from sympy import Function, dsolve, Eq, pprint

>>> from sympy.abc import x, n
>>> f, P, Q = map(Function, ['f', 'P', 'Q'])
>>> genform = Eq(f(x).diff(x) + P(x)*f(x), Q(x)*f(x)**n)
>>> pprint(genform)
d n
P(x)*f(x) + --(f(x)) = Q(x)*f (x)
dx
>>> pprint(dsolve(genform, f(x), hint='Bernoulli_Integral'))
1
(continues on next page)

5.30. ODE 1279

SymPy Documentation, Release 1.3

(continued from previous page)

----
1 - n
// / \ \
|| | | |
|| | / | / |
|| | | | | |
|| | (1 - n)* | P(x) dx | (-1 + n)* | P(x) dx|
|| | | | | |
|| | / | / |
f(x) = ||C1 + (-1 + n)* | -Q(x)*e dx|*e |
|| | | |
\\ / / /

Note that the equation is separable when n = 1 (see the docstring of ode_separable()
(page 1286)).

>>> pprint(dsolve(Eq(f(x).diff(x) + P(x)*f(x), Q(x)*f(x)), f(x),

... hint='separable_Integral'))
f(x)
/
| /
| 1 |
| - dy = C1 + | (-P(x) + Q(x)) dx
| y |
| /
/

References

• http://en.wikipedia.org/wiki/Bernoulli_differential_equation
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 95

# indirect doctest

Examples

>>> from sympy import Function, dsolve, Eq, pprint, log

>>> from sympy.abc import x
>>> f = Function('f')

>>> pprint(dsolve(Eq(x*f(x).diff(x) + f(x), log(x)*f(x)**2),

... f(x), hint='Bernoulli'))
1
f(x) = -------------------
/ log(x) 1\
x*|C1 + ------ + -|
\ x x/

1280 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Liouville

sympy.solvers.ode.ode_Liouville(eq, func, order, match)

Solves 2nd order Liouville differential equations.
The general form of a Liouville ODE is
( )2
d2 y dy dy
2
+ g(y) + h(x) .
dx dx dx
The general solution is:
>>> from sympy import Function, dsolve, Eq, pprint, diff
>>> from sympy.abc import x
>>> f, g, h = map(Function, ['f', 'g', 'h'])
>>> genform = Eq(diff(f(x),x,x) + g(f(x))*diff(f(x),x)**2 +
... h(x)*diff(f(x),x), 0)
>>> pprint(genform)
2 2
/d \ d d
g(f(x))*|--(f(x))| + h(x)*--(f(x)) + ---(f(x)) = 0
\dx / dx 2
dx
>>> pprint(dsolve(genform, f(x), hint='Liouville_Integral'))
f(x)
/ /
| |
| / | /
| | | |
| - | h(x) dx | | g(y) dy
| | | |
| / | /
C1 + C2* | e dx + | e dy = 0
| |
/ /

References

• Goldstein and Braun, “Advanced Methods for the Solution of Differential Equations”,
pp. 98
• http://www.maplesoft.com/support/help/Maple/view.aspx?path=odeadvisor/
Liouville

# indirect doctest

Examples

>>> from sympy import Function, dsolve, Eq, pprint

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(diff(f(x), x, x) + diff(f(x), x)**2/f(x) +
... diff(f(x), x)/x, f(x), hint='Liouville'))
________________ ________________
[f(x) = -\/ C1 + C2*log(x) , f(x) = \/ C1 + C2*log(x) ]

5.30. ODE 1281

SymPy Documentation, Release 1.3

Riccati_special_minus2

sympy.solvers.ode.ode_Riccati_special_minus2(eq, func, order, match)

The general Riccati equation has the form

dy/dx = f (x)y 2 + g(x)y + h(x).

While it does not have a general solution [1], the “special” form, dy/dx = ay 2 − bxc , does
have solutions in many cases [2]. This routine returns a solution for a(dy/dx) = by 2 +cy/x+
d/x2 that is obtained by using a suitable change of variables to reduce it to the special
form and is valid when neither a nor b are zero and either c or d is zero.

>>> from sympy.abc import x, y, a, b, c, d

>>> from sympy.solvers.ode import dsolve, checkodesol
>>> from sympy import pprint, Function
>>> f = Function('f')
>>> y = f(x)
>>> genform = a*y.diff(x) - (b*y**2 + c*y/x + d/x**2)
>>> sol = dsolve(genform, y)
>>> pprint(sol, wrap_line=False)
/ / __________________ \\
| __________________ | / 2 ||
| / 2 | \/ 4*b*d - (a + c) *log(x)||
-|a + c - \/ 4*b*d - (a + c) *tan|C1 + ----------------------------||
\ \ 2*a //
f(x) = ------------------------------------------------------------------------
2*b*x

>>> checkodesol(genform, sol, order=1)[0]

True

References

1. http://www.maplesoft.com/support/help/Maple/view.aspx?path=odeadvisor/Riccati
2. http://eqworld.ipmnet.ru/en/solutions/ode/ode0106.pdf - http://eqworld.ipmnet.ru/
en/solutions/ode/ode0123.pdf

nth_linear_constant_coeff_homogeneous

sympy.solvers.ode.ode_nth_linear_constant_coeff_homogeneous(eq, func, or-

der, match,
returns=’sol’)
Solves an nth order linear homogeneous differential equation with constant coefficients.
This is an equation of the form

an f (n) (x) + an−1 f (n−1) (x) + · · · + a1 f ′ (x) + a0 f (x) = 0.

These equations can be solved in a general manner, by taking the roots of the charac-
teristic equation an mn + an−1 mn−1 + · · · + a1 m + a0 = 0. The solution will then be the sum of
Cn xi erx terms, for each where Cn is an arbitrary constant, r is a root of the characteristic
equation and i is one of each from 0 to the multiplicity of the root - 1 (for example, a
root 3 of multiplicity 2 would create the terms C1 e3x + C2 xe3x ). The exponential is usually

1282 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

expanded for complex roots using Euler’s equation eIx = cos(x) + I sin(x). Complex roots
always come in conjugate pairs in polynomials with real coefficients, so the two roots
will be represented (after simplifying the constants) as eax (C1 cos(bx) + C2 sin(bx)).
If SymPy cannot find exact roots to the characteristic equation, a CRootOf instance will
be return instead.

>>> from sympy import Function, dsolve, Eq

>>> from sympy.abc import x
>>> f = Function('f')
>>> dsolve(f(x).diff(x, 5) + 10*f(x).diff(x) - 2*f(x), f(x),
... hint='nth_linear_constant_coeff_homogeneous')
... # doctest: +NORMALIZE_WHITESPACE
Eq(f(x), C1*exp(x*CRootOf(_x**5 + 10*_x - 2, 0)) +
C2*exp(x*CRootOf(_x**5 + 10*_x - 2, 1)) +
C3*exp(x*CRootOf(_x**5 + 10*_x - 2, 2)) +
C4*exp(x*CRootOf(_x**5 + 10*_x - 2, 3)) +
C5*exp(x*CRootOf(_x**5 + 10*_x - 2, 4)))

Note that because this method does not involve integration, there is no
nth_linear_constant_coeff_homogeneous_Integral hint.
The following is for internal use:
• returns = 'sol' returns the solution to the ODE.
• returns = 'list' returns a list of linearly independent solutions, for use with
non homogeneous solution methods like variation of parameters and undeter-
mined coefficients. Note that, though the solutions should be linearly inde-
pendent, this function does not explicitly check that. You can do assert sim-
plify(wronskian(sollist)) != 0 to check for linear independence. Also, assert
len(sollist) == order will need to pass.
• returns = 'both', return a dictionary {'sol': <solution to ODE>, 'list':
<list of linearly independent solutions>}.

References

• http://en.wikipedia.org/wiki/Linear_differential_equation section: Nonhomoge-

neous_equation_with_constant_coefficients
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 211

# indirect doctest

Examples

>>> from sympy import Function, dsolve, pprint

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(f(x).diff(x, 4) + 2*f(x).diff(x, 3) -
... 2*f(x).diff(x, 2) - 6*f(x).diff(x) + 5*f(x), f(x),
... hint='nth_linear_constant_coeff_homogeneous'))
x -2*x
f(x) = (C1 + C2*x)*e + (C3*sin(x) + C4*cos(x))*e

5.30. ODE 1283

SymPy Documentation, Release 1.3

nth_linear_constant_coeff_undetermined_coefficients

sympy.solvers.ode.ode_nth_linear_constant_coeff_undetermined_coefficients(eq,
func,
or-
der,
match)
Solves an nth order linear differential equation with constant coefficients using the
method of undetermined coefficients.
This method works on differential equations of the form

an f (n) (x) + an−1 f (n−1) (x) + · · · + a1 f ′ (x) + a0 f (x) = P (x),

where P (x) is a function that has a finite number of linearly independent derivatives.
Functions that fit this requirement are finite sums functions of the form axi ebx sin(cx + d)
or axi ebx cos(cx + d), where i is a non-negative integer and a, b, c, and d are constants.
For example any polynomial in x, functions like x2 e2x , x sin(x), and ex cos(x) can all be
used. Products of sin’s and cos’s have a finite number of derivatives, because they can
be expanded into sin(ax) and cos(bx) terms. However, SymPy currently cannot do that
expansion, so you will need to manually rewrite the expression in terms of the above
2
to use this method. So, for example, you will need to manually convert sin (x) into (1 +
cos(2x))/2 to properly apply the method of undetermined coefficients on it.
This method works by creating a trial function from the expression and all of its linear
independent derivatives and substituting them into the original ODE. The coefficients for
each term will be a system of linear equations, which are be solved for and substituted,
giving the solution. If any of the trial functions are linearly dependent on the solution
to the homogeneous equation, they are multiplied by sufficient x to make them linearly
independent.

References

• http://en.wikipedia.org/wiki/Method_of_undetermined_coefficients
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 221

# indirect doctest

Examples

>>> from sympy import Function, dsolve, pprint, exp, cos

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(f(x).diff(x, 2) + 2*f(x).diff(x) + f(x) -
... 4*exp(-x)*x**2 + cos(2*x), f(x),
... hint='nth_linear_constant_coeff_undetermined_coefficients'))
/ 4\
| x | -x 4*sin(2*x) 3*cos(2*x)
f(x) = |C1 + C2*x + --|*e - ---------- + ----------
\ 3 / 25 25

1284 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

nth_linear_constant_coeff_variation_of_parameters

sympy.solvers.ode.ode_nth_linear_constant_coeff_variation_of_parameters(eq,
func,
or-
der,
match)
Solves an nth order linear differential equation with constant coefficients using the
method of variation of parameters.
This method works on any differential equations of the form

f (n) (x) + an−1 f (n−1) (x) + · · · + a1 f ′ (x) + a0 f (x) = P (x).

This method works by assuming that the particular solution takes the form

∑
n
ci (x)yi (x),
x=1

where yi is the ith solution to the homogeneous equation. The solution is then solved
using Wronskian’s and Cramer’s Rule. The particular solution is given by

∑n (∫ )
Wi (x)
dx yi (x),
x=1
W (x)

where W (x) is the Wronskian of the fundamental system (the system of n linearly in-
dependent solutions to the homogeneous equation), and Wi (x) is the Wronskian of the
fundamental system with the ith column replaced with [0, 0, · · · , 0, P (x)].
This method is general enough to solve any nth order inhomogeneous linear
differential equation with constant coefficients, but sometimes SymPy cannot
simplify the Wronskian well enough to integrate it. If this method hangs, try
using the nth_linear_constant_coeff_variation_of_parameters_Integral
hint and simplifying the integrals manually. Also, prefer using
nth_linear_constant_coeff_undetermined_coefficients when it applies, because it
doesn’t use integration, making it faster and more reliable.
Warning, using simplify=False with ‘nth_linear_constant_coeff_variation_of_parameters’
in dsolve() (page 1262) may cause it to hang, because it will not attempt to simplify the
Wronskian before integrating. It is recommended that you only use simplify=False with
‘nth_linear_constant_coeff_variation_of_parameters_Integral’ for this method, especially
if the solution to the homogeneous equation has trigonometric functions in it.

References

• http://en.wikipedia.org/wiki/Variation_of_parameters
• http://planetmath.org/VariationOfParameters
• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 233

# indirect doctest

5.30. ODE 1285

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, dsolve, pprint, exp, log

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(f(x).diff(x, 3) - 3*f(x).diff(x, 2) +
... 3*f(x).diff(x) - f(x) - exp(x)*log(x), f(x),
... hint='nth_linear_constant_coeff_variation_of_parameters'))
/ 3 \
| 2 x *(6*log(x) - 11)| x
f(x) = |C1 + C2*x + C3*x + ------------------|*e
\ 36 /

separable

sympy.solvers.ode.ode_separable(eq, func, order, match)

Solves separable 1st order differential equations.
dy
This is any differential equation that can be written as P (y)
∫ dx = Q(x).∫ The solution can
then just be found by rearranging terms and integrating: P (y) dy = Q(x) dx. This hint
uses sympy.simplify.simplify.separatevars() (page 1187) as its back end, so if a
separable equation is not caught by this solver, it is most likely the fault of that func-
tion. separatevars() (page 1187) is smart enough to do most expansion and factoring
necessary to convert a separable equation F (x, y) into the proper form P (x) · Q(y). The
general solution is:

>>> from sympy import Function, dsolve, Eq, pprint

>>> from sympy.abc import x
>>> a, b, c, d, f = map(Function, ['a', 'b', 'c', 'd', 'f'])
>>> genform = Eq(a(x)*b(f(x))*f(x).diff(x), c(x)*d(f(x)))
>>> pprint(genform)
d
a(x)*b(f(x))*--(f(x)) = c(x)*d(f(x))
dx
>>> pprint(dsolve(genform, f(x), hint='separable_Integral'))
f(x)
/ /
| |
| b(y) | c(x)
| ---- dy = C1 + | ---- dx
| d(y) | a(x)
| |
/ /

References

• M. Tenenbaum & H. Pollard, “Ordinary Differential Equations”, Dover 1963, pp. 52

# indirect doctest

1286 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, dsolve, Eq

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(Eq(f(x)*f(x).diff(x) + x, 3*x*f(x)**2), f(x),
... hint='separable', simplify=False))
/ 2 \ 2
log\3*f (x) - 1/ x
---------------- = C1 + --
6 2

almost_linear

sympy.solvers.ode.ode_almost_linear(eq, func, order, match)

Solves an almost-linear differential equation.
The general form of an almost linear differential equation is

f (x)g(y)y + k(x)l(y) + m(x) = 0wherel′ (y) = g(y).

This can be solved by substituting l(y) = u(y). Making the given substitution reduces it
to a linear differential equation of the form u′ + P (x)u + Q(x) = 0.
The general solution is

>>> from sympy import Function, dsolve, Eq, pprint

>>> from sympy.abc import x, y, n
>>> f, g, k, l = map(Function, ['f', 'g', 'k', 'l'])
>>> genform = Eq(f(x)*(l(y).diff(y)) + k(x)*l(y) + g(x))
>>> pprint(genform)
d
f(x)*--(l(y)) + g(x) + k(x)*l(y) = 0
dy
>>> pprint(dsolve(genform, hint = 'almost_linear'))
/ // y*k(x) \\
| || ------ ||
| || f(x) || -y*k(x)
| ||-g(x)*e || --------
| ||-------------- for k(x) != 0|| f(x)
l(y) = |C1 + |< k(x) ||*e
| || ||
| || -y*g(x) ||
| || -------- otherwise ||
| || f(x) ||
\ \\ //

See also:
sympy.solvers.ode.ode_1st_linear() (page 1278)

References

• Joel Moses, “Symbolic Integration - The Stormy Decade”, Communications of the

ACM, Volume 14, Number 8, August 1971, pp. 558

5.30. ODE 1287

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, Derivative, pprint

>>> from sympy.solvers.ode import dsolve, classify_ode
>>> from sympy.abc import x
>>> f = Function('f')
>>> d = f(x).diff(x)
>>> eq = x*d + x*f(x) + 1
>>> dsolve(eq, f(x), hint='almost_linear')
Eq(f(x), (C1 - Ei(x))*exp(-x))
>>> pprint(dsolve(eq, f(x), hint='almost_linear'))
-x
f(x) = (C1 - Ei(x))*e

linear_coefficients

sympy.solvers.ode.ode_linear_coefficients(eq, func, order, match)

Solves a differential equation with linear coefficients.
The general form of a differential equation with linear coefficients is
( )
a1 x + b1 y + c1
y′ + F = 0,
a2 x + b2 y + c2

where a1 , b1 , c1 , a2 , b2 , c2 are constants and a1 b2 − a2 b1 ̸= 0.

This can be solved by substituting:
b2 c1 − b1 c2
x = x′ +
a2 b1 − a1 b2
a1 c2 − a2 c1
y = y′ + .
a2 b1 − a1 b2
This substitution reduces the equation to a homogeneous differential equation.
See also:
sympy.solvers.ode.ode_1st_homogeneous_coeff_best() (page 1275), sympy.
solvers.ode.ode_1st_homogeneous_coeff_subs_indep_div_dep() (page 1277),
sympy.solvers.ode.ode_1st_homogeneous_coeff_subs_dep_div_indep()
(page 1276)

References

• Joel Moses, “Symbolic Integration - The Stormy Decade”, Communications of the

ACM, Volume 14, Number 8, August 1971, pp. 558

Examples

>>> from sympy import Function, Derivative, pprint

>>> from sympy.solvers.ode import dsolve, classify_ode
>>> from sympy.abc import x
>>> f = Function('f')
(continues on next page)

1288 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> df = f(x).diff(x)
>>> eq = (x + f(x) + 1)*df + (f(x) - 6*x + 1)
>>> dsolve(eq, hint='linear_coefficients')
[Eq(f(x), -x - sqrt(C1 + 7*x**2) - 1), Eq(f(x), -x + sqrt(C1 + 7*x**2) - 1)]
>>> pprint(dsolve(eq, hint='linear_coefficients'))
___________ ___________
/ 2 / 2
[f(x) = -x - \/ C1 + 7*x - 1, f(x) = -x + \/ C1 + 7*x - 1]

separable_reduced

sympy.solvers.ode.ode_separable_reduced(eq, func, order, match)

Solves a differential equation that can be reduced to the separable form.
The general form of this equation is

y ′ + (y/x)H(xn y) = 0.

This can be solved by substituting u(y) = xn y. The equation then reduces to the separable
u′
form u(power−H(u)) − x1 = 0.
The general solution is:

>>> from sympy import Function, dsolve, Eq, pprint

>>> from sympy.abc import x, n
>>> f, g = map(Function, ['f', 'g'])
>>> genform = f(x).diff(x) + (f(x)/x)*g(x**n*f(x))
>>> pprint(genform)
/ n \
d f(x)*g\x *f(x)/
--(f(x)) + ---------------
dx x
>>> pprint(dsolve(genform, hint='separable_reduced'))
n
x *f(x)
/
|
| 1
| ------------ dy = C1 + log(x)
| y*(n - g(y))
|
/

See also:
sympy.solvers.ode.ode_separable() (page 1286)

References

• Joel Moses, “Symbolic Integration - The Stormy Decade”, Communications of the

ACM, Volume 14, Number 8, August 1971, pp. 558

5.30. ODE 1289

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Function, Derivative, pprint

>>> from sympy.solvers.ode import dsolve, classify_ode
>>> from sympy.abc import x
>>> f = Function('f')
>>> d = f(x).diff(x)
>>> eq = (x - x**2*f(x))*d - f(x)
>>> dsolve(eq, hint='separable_reduced')
[Eq(f(x), (-sqrt(C1*x**2 + 1) + 1)/x), Eq(f(x), (sqrt(C1*x**2 + 1) + 1)/x)]
>>> pprint(dsolve(eq, hint='separable_reduced'))
___________ ___________
/ 2 / 2
- \/ C1*x + 1 + 1 \/ C1*x + 1 + 1
[f(x) = --------------------, f(x) = ------------------]
x x

lie_group

sympy.solvers.ode.ode_lie_group(eq, func, order, match)

This hint implements the Lie group method of solving first order differential equations.
The aim is to convert the given differential equation from the given coordinate given sys-
tem into another coordinate system where it becomes invariant under the one-parameter
Lie group of translations. The converted ODE is quadrature and can be solved easily.
It makes use of the sympy.solvers.ode.infinitesimals() (page 1268) function which
returns the infinitesimals of the transformation.
The coordinates r and s can be found by solving the following Partial Differential Equa-
tions.
∂r ∂r
ξ +η =0
∂x ∂y
∂s ∂s
ξ +η =1
∂x ∂y
The differential equation becomes separable in the new coordinate system
∂s ∂s
ds ∂x + h(x, y) ∂y
= ∂r ∂r
dr ∂x + h(x, y) ∂y

After finding the solution by integration, it is then converted back to the original coordi-
nate system by substituting r and s in terms of x and y again.

References

• Solving differential equations by Symmetry Groups, John Starrett, pp. 1 - pp. 14

Examples

1290 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Function, dsolve, Eq, exp, pprint

>>> from sympy.abc import x
>>> f = Function('f')
>>> pprint(dsolve(f(x).diff(x) + 2*x*f(x) - x*exp(-x**2), f(x),
... hint='lie_group'))
/ 2\ 2
| x | -x
f(x) = |C1 + --|*e
\ 2 /

1st_power_series

sympy.solvers.ode.ode_1st_power_series(eq, func, order, match)

The power series solution is a method which gives the Taylor series expansion to the
solution of a differential equation.
dy
For a first order differential equation dx = h(x, y), a power series solution exists at a point
x = x0 if h(x, y) is analytic at x0 . The solution is given by
∑∞
Fn (x0 , b)(x − x0 )n
y(x) = y(x0 ) + ,
n=1
n!

where y(x0 ) = b is the value of y at the initial value of x0 . To compute the values of
the Fn (x0 , b) the following algorithm is followed, until the required number of terms are
generated.
1. F1 = h(x0 , b)
∂Fn ∂Fn
2. Fn+1 = ∂x + ∂y F1

References

• Travis W. Walker, Analytic power series technique for solving first-order differential
equations, p.p 17, 18

Examples

>>> from sympy import Function, Derivative, pprint, exp

>>> from sympy.solvers.ode import dsolve
>>> from sympy.abc import x
>>> f = Function('f')
>>> eq = exp(x)*(f(x).diff(x)) - f(x)
>>> pprint(dsolve(eq, hint='1st_power_series'))
3 4 5
C1*x C1*x C1*x / 6\
f(x) = C1 + C1*x - ----- + ----- + ----- + O\x /
6 24 60

2nd_power_series_ordinary

sympy.solvers.ode.ode_2nd_power_series_ordinary(eq, func, order, match)

Gives a power series solution to a second order homogeneous differential equation with

5.30. ODE 1291

SymPy Documentation, Release 1.3

polynomial coefficients at an ordinary point. A homogenous differential equation is of

the form
d2 y dy
P (x) + Q(x) + R(x) = 0
dx2 dx
For simplicity it is assumed that P (x), Q(x) and R(x) are polynomials, it is sufficient that
Q(x) R(x) ∑∞ n
P (x) and P (x) exists at x0 . A recurrence relation is obtained by substituting y as n=0 an x ,
in the differential equation, and equating the nth term. Using this relation various terms
can be generated.

References

• http://tutorial.math.lamar.edu/Classes/DE/SeriesSolutions.aspx
• George E. Simmons, “Differential Equations with Applications and Historical Notes”,
p.p 176 - 184

Examples

>>> from sympy import dsolve, Function, pprint

>>> from sympy.abc import x, y
>>> f = Function(”f”)
>>> eq = f(x).diff(x, 2) + f(x)
>>> pprint(dsolve(eq, hint='2nd_power_series_ordinary'))
/ 4 2 \ / 2 \
|x x | | x | / 6\
f(x) = C2*|-- - -- + 1| + C1*x*|- -- + 1| + O\x /
\24 2 / \ 6 /

2nd_power_series_regular

sympy.solvers.ode.ode_2nd_power_series_regular(eq, func, order, match)

Gives a power series solution to a second order homogeneous differential equation with
polynomial coefficients at a regular point. A second order homogenous differential equa-
tion is of the form
d2 y dy
P (x) 2
+ Q(x) + R(x) = 0
dx dx

A point is said to regular singular at x0 if x − x0 Q(x) 2 R(x)

P (x) and (x − x0) P (x) are analytic at x0. For
simplicity P (x), Q(x) and R(x) are assumed to be polynomials. The algorithm for finding
the power series solutions is:
1. Try expressing (x − x0)P (x) and ((x − x0)2 )Q(x) as power series solutions about x0.
Find p0 and q0 which are the constants of the power series expansions.
2. Solve the indicial equation f (m) = m(m − 1) + m ∗ p0 + q0, to obtain the roots m1 and
m2 of the indicial equation.
3. If m1 − m2 is a non integer there exists two series solutions. If m1 = m2, there exists
only one solution. If m1 − m2 is an integer, then the existence of one solution is
confirmed. The other solution may or may not exist.

1292 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

∑∞
The power series solution is of the form xm n
n=0 an x . The coefficients are determined
∑ n−1
q +(m+k)pn−k
by the following recurrence relation. an = − k=0 n−kf (m+n) . For the case in which
m1 − m2 is an integer, it can be seen from the recurrence relation that for the lower root
m, when n equals the difference of both the roots, the denominator becomes zero. So if
the numerator is not equal to zero, a second series solution exists.

References

• George E. Simmons, “Differential Equations with Applications and Historical Notes”,

p.p 176 - 184

Examples

>>> from sympy import dsolve, Function, pprint

>>> from sympy.abc import x, y
>>> f = Function(”f”)
>>> eq = x*(f(x).diff(x, 2)) + 2*(f(x).diff(x)) + x*f(x)
>>> pprint(dsolve(eq))
/ 6 4 2 \
| x x x |
/ 4 2 \ C1*|- --- + -- - -- + 1|
| x x | \ 720 24 2 / / 6\
f(x) = C2*|--- - -- + 1| + ------------------------ + O\x /
\120 6 / x

5.30.3 Lie heuristics

These functions are intended for internal use of the Lie Group Solver. Nonetheless, they
contain useful information in their docstrings on the algorithms implemented for the various
heuristics.

abaco1_simple

sympy.solvers.ode.lie_heuristic_abaco1_simple(match, comp=False)
The first heuristic uses the following four sets of assumptions on ξ and η

ξ = 0, η = f (x)

ξ = 0, η = f (y)
ξ = f (x), η = 0
ξ = f (y), η = 0
The success of this heuristic is determined by algebraic factorisation. For the first as-
sumption ξ = 0 and η to be a function of x, the PDE
∂η ∂η ∂ξ ∂ξ ∂h ∂h
+( − )∗h− ∗ h2 − ξ ∗ −η∗ =0
∂x ∂y ∂x ∂y ∂x ∂y
reduces to f ′ (x)−f ∂h ∂h
∂y = 0 If ∂y is a function of x, then this can usually be integrated easily.
A similar idea is applied to the other 3 assumptions as well.

5.30. ODE 1293

SymPy Documentation, Release 1.3

References

• E.S Cheb-Terrab, L.G.S Duarte and L.A,C.P da Mota, Computer Algebra Solving of
First Order ODEs Using Symmetry Methods, pp. 8

abaco1_product

sympy.solvers.ode.lie_heuristic_abaco1_product(match, comp=False)
The second heuristic uses the following two assumptions on ξ and η

η = 0, ξ = f (x) ∗ g(y)

η = f (x) ∗ g(y), ξ = 0
2
∂
The first assumption of this heuristic holds good if h12 ∂x∂y log(h) is separable in x and y,
then the separated factors containing x is f (x), and g(y) is obtained by
∫
e
∂
f ∂x ( f ∗h
1
) dy
( )
∂ 1
provided f ∂x f ∗h is a function of y only.
dy dy 1
The second assumption holds good if dx = h(x, y) is rewritten as dx = h(y,x) and the same
properties of the first assumption satisfies. After obtaining f (x) and g(y), the coordinates
are again interchanged, to get η as f (x) ∗ g(y)

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 7 -
pp. 8

bivariate

sympy.solvers.ode.lie_heuristic_bivariate(match, comp=False)
The third heuristic assumes the infinitesimals ξ and η to be bi-variate polynomials in x
and y. The assumption made here for the logic below is that h is a rational function in x
and y though that may not be necessary for the infinitesimals to be bivariate polynomials.
The coefficients of the infinitesimals are found out by substituting them in the PDE and
grouping similar terms that are polynomials and since they form a linear system, solve
and check for non trivial solutions. The degree of the assumed bivariates are increased
till a certain maximum value.

References

• Lie Groups and Differential Equations pp. 327 - pp. 329

1294 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

chi

sympy.solvers.ode.lie_heuristic_chi(match, comp=False)
dχ
The aim of the fourth heuristic is to find the function χ(x, y) that satisfies the PDE dx +
dx − ∂y χ = 0.
h dχ ∂h

This assumes χ to be a bivariate polynomial in x and y. By intuition, h should be a rational

function in x and y. The method used here is to substitute a general binomial for χ up to a
certain maximum degree is reached. The coefficients of the polynomials, are calculated
by by collecting terms of the same order in x and y.
After finding χ, the next step is to use η = ξ ∗ h + χ, to determine ξ and η. This can be done
by dividing χ by h which would give −ξ as the quotient and η as the remainder.

References

• E.S Cheb-Terrab, L.G.S Duarte and L.A,C.P da Mota, Computer Algebra Solving of
First Order ODEs Using Symmetry Methods, pp. 8

abaco2_similar

sympy.solvers.ode.lie_heuristic_abaco2_similar(match, comp=False)
This heuristic uses the following two assumptions on ξ and η

η = g(x), ξ = f (x)

η = f (y), ξ = g(y)
For the first assumption,
∂h
1. First ∂y
∂2 h
is calculated. Let us say this value is A
∂yy

∫ A(x)
y dx
e C
2. If this is constant, then h is matched to the form A(x) + B(x)e C then, B(x) gives
f (x) and A(x) ∗ f (x) gives g(x)
∂A
3. Otherwise ∂X
∂A = γ is calculated. If
∂Y

a] γ is a function of x alone
γ ∂h −γ ′ (x)− ∂h ∫
b] ∂y h+γ
∂x
= G is a function of x alone. then, e G dx
gives f (x) and −γ ∗ f (x) gives
g(x)
dy dy 1
The second assumption holds good if dx = h(x, y) is rewritten as dx = h(y,x) and the same
properties of the first assumption satisfies. After obtaining f (x) and g(x), the coordinates
are again interchanged, to get ξ as f (x∗ ) and η as g(y ∗ )

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 10 -
pp. 12

5.30. ODE 1295

SymPy Documentation, Release 1.3

function_sum

sympy.solvers.ode.lie_heuristic_function_sum(match, comp=False)
This heuristic uses the following two assumptions on ξ and η

η = 0, ξ = f (x) + g(y)

η = f (x) + g(y), ξ = 0
The first assumption of this heuristic holds good if

∂ ∂2
[(h 2 (h−1 ))−1 ]
∂y ∂x

is separable in x and y,
∂g
1. The separated factors containing y is ∂y . From this g(y) can be determined.
2. The separated factors containing x is f ′′ (x).
∂2
−1 f ′′ (x)
3. h ∂x 2 (h ) equals f (x)+g(y) . From this f (x) can be determined.
dy dy 1
The second assumption holds good if dx = h(x, y) is rewritten as dx = h(y,x) and the same
properties of the first assumption satisfies. After obtaining f (x) and g(y), the coordinates
are again interchanged, to get η as f (x) + g(y).
For both assumptions, the constant factors are separated among g(y) and f ′′ (x), such
that f ′′ (x) obtained from 3] is the same as that obtained from 2]. If not possible, then
this heuristic fails.

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 7 -
pp. 8

abaco2_unique_unknown

sympy.solvers.ode.lie_heuristic_abaco2_unique_unknown(match, comp=False)
This heuristic assumes the presence of unknown functions or known functions with non-
integer powers.
1. A list of all functions and non-integer powers containing x and y
∂f
2. Loop over each element f in the list, find ∂x
∂f =R
∂x

If it is separable in x and y, let X be the factors containing x. Then

a] Check if ξ = X and η = − X
R satisfy the PDE. If yes, then return ξ and η
−R
b] Check if ξ = X and η = − X
1
satisfy the PDE. If yes, then return ξ and η
If not, then check if
a] ξ = −R, η = 1
b] ξ = 1, η = − R1
are solutions.

1296 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 10 -
pp. 12

abaco2_unique_general

sympy.solvers.ode.lie_heuristic_abaco2_unique_general(match, comp=False)
This heuristic finds if infinitesimals of the form η = f (x), ξ = g(y) without making any
assumptions on h.
The complete sequence of steps is given in the paper mentioned below.

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 10 -
pp. 12

linear

sympy.solvers.ode.lie_heuristic_linear(match, comp=False)
This heuristic assumes
1. ξ = ax + by + c and
2. η = f x + gy + h
After substituting the following assumptions in the determining PDE, it reduces to

∂h ∂h
f + (g − a)h − bh2 − (ax + by + c) − (f x + gy + c)
∂x ∂y

Solving the reduced PDE obtained, using the method of characteristics, becomes imprac-
tical. The method followed is grouping similar terms and solving the system of linear
equations obtained. The difference between the bivariate heuristic is that h need not be
a rational function in this case.

References

• E.S. Cheb-Terrab, A.D. Roche, Symmetries and First Order ODE Patterns, pp. 10 -
pp. 12

5.30.4 System of ODEs

These functions are intended for internal use by dsolve() (page 1262) for system of differ-
ential equations.

5.30. ODE 1297

SymPy Documentation, Release 1.3

system_of_odes_linear_2eq_order1_type1

sympy.solvers.ode._linear_2eq_order1_type1(x, y, t, r, eq)
It is classified under system of two linear homogeneous first-order constant-coefficient
ordinary differential equations.
The equations which come under this type are
x′ = ax + by,

y ′ = cx + dy
The characteristics equation is written as
λ2 + (a + d)λ + ad − bc = 0
and its discriminant is D = (a − d)2 + 4bc. There are several cases
1. Case when ad − bc ̸= 0. The origin of coordinates, x = y = 0, is the only stationary point;
it is - a node if D = 0 - a node if D > 0 and ad − bc > 0 - a saddle if D > 0 and ad − bc < 0 - a
focus if D < 0 and a + d ̸= 0 - a centre if D < 0 and a + d ̸= 0.
1.1. If D > 0. The characteristic equation has two distinct real roots λ1 and λ2 . The
general solution of the system in question is expressed as
x = C1 beλ1 t + C2 beλ2 t

y = C1 (λ1 − a)eλ1 t + C2 (λ2 − a)eλ2 t

where C1 and C2 being arbitrary constants
1.2. If D < 0. The characteristics equation has two conjugate roots, λ1 = σ + iβ and
λ2 = σ − iβ. The general solution of the system is given by
x = beσt (C1 sin(βt) + C2 cos(βt))

y = eσt ([(σ − a)C1 − βC2 ] sin(βt) + [βC1 + (σ − a)C2 cos(βt)])

1.3. If D = 0 and a ̸= d. The characteristic equation has two equal roots, λ1 = λ2 . The
general solution of the system is written as
C2 a+d
x = 2b(C1 + + C2 t)e 2 t
a−d
a+d
y = [(d − a)C1 + C2 + (d − a)C2 t]e 2 t

1.4. If D = 0 and a = d ̸= 0 and b = 0

x = C1 eat , y = (cC1 t + C2 )eat
1.5. If D = 0 and a = d ̸= 0 and c = 0
x = (bC1 t + C2 )eat , y = C1 eat
2. Case when ad − bc = 0 and a2 + b2 > 0. The whole straight line ax + by = 0 consists of
singular points. The original system of differential equations can be rewritten as
x′ = ax + by, y ′ = k(ax + by)
2.1 If a + bk ̸= 0, solution will be
x = bC1 + C2 e(a+bk)t , y = −aC1 + kC2 e(a+bk)t
2.2 If a + bk = 0, solution will be
x = C1 (bkt − 1) + bC2 t, y = k 2 bC1 t + (bk 2 t + 1)C2

1298 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system_of_odes_linear_2eq_order1_type2

sympy.solvers.ode._linear_2eq_order1_type2(x, y, t, r, eq)
The equations of this type are

x′ = ax + by + k1, y ′ = cx + dy + k2

The general solution of this system is given by sum of its particular solution and the
general solution of the corresponding homogeneous system is obtained from type1.
1. When ad − bc ̸= 0. The particular solution will be x = x0 and y = y0 where x0 and y0 are
determined by solving linear system of equations

ax0 + by0 + k1 = 0, cx0 + dy0 + k2 = 0

2. When ad − bc = 0 and a2 + b2 > 0. In this case, the system of equation becomes

x′ = ax + by + k1 , y ′ = k(ax + by) + k2
2.1 If σ = a + bk ̸= 0, particular solution is given by

x = bσ −1 (c1 k − c2 )t − σ −2 (ac1 + bc2 )

y = kx + (c2 − c1 k)t
2.2 If σ = a + bk = 0, particular solution is given by
1
x= b(c2 − c1 k)t2 + c1 t
2
y = kx + (c2 − c1 k)t

system_of_odes_linear_2eq_order1_type3

sympy.solvers.ode._linear_2eq_order1_type3(x, y, t, r, eq)
The equations of this type of ode are

x′ = f (t)x + g(t)y

y ′ = g(t)x + f (t)y
The solution of such equations is given by

x = eF (C1 eG + C2 e−G ), y = eF (C1 eG − C2 e−G )

where C1 and C2 are arbitrary constants, and

∫ ∫
F = f (t) dt, G = g(t) dt

5.30. ODE 1299

SymPy Documentation, Release 1.3

system_of_odes_linear_2eq_order1_type4

sympy.solvers.ode._linear_2eq_order1_type4(x, y, t, r, eq)
The equations of this type of ode are .

x′ = f (t)x + g(t)y

y ′ = −g(t)x + f (t)y
The solution is given by

x = F (C1 cos(G) + C2 sin(G)), y = F (−C1 sin(G) + C2 cos(G))

where C1 and C2 are arbitrary constants, and

∫ ∫
F = f (t) dt, G = g(t) dt

system_of_odes_linear_2eq_order1_type5

sympy.solvers.ode._linear_2eq_order1_type5(x, y, t, r, eq)
The equations of this type of ode are .

x′ = f (t)x + g(t)y

y ′ = ag(t)x + [f (t) + bg(t)]y

The transformation of
∫ ∫
∫
f (t) dt f (t) dt
x=e u, y = e v, T = g(t) dt

leads to a system of constant coefficient linear differential equations

u′ (T ) = v, v ′ (T ) = au + bv

system_of_odes_linear_2eq_order1_type6

sympy.solvers.ode._linear_2eq_order1_type6(x, y, t, r, eq)
The equations of this type of ode are .

x′ = f (t)x + g(t)y

y ′ = a[f (t) + ah(t)]x + a[g(t) − h(t)]y

This is solved by first multiplying the first equation by −a and adding it to the second
equation to obtain

y ′ − ax′ = −ah(t)(y − ax)

Setting U = y − ax and integrating the equation we arrive at

∫
y − ax = C1 e−a h(t) dt

and on substituting the value of y in first equation give rise to first order ODEs. After
solving for x, we can obtain y by substituting the value of x in second equation.

1300 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system_of_odes_linear_2eq_order1_type7

sympy.solvers.ode._linear_2eq_order1_type7(x, y, t, r, eq)
The equations of this type of ode are .

x′ = f (t)x + g(t)y

y ′ = h(t)x + p(t)y
Differentiating the first equation and substituting the value of y from second equation
will give a second-order linear equation

gx′′ − (f g + gp + g ′ )x′ + (f gp − g 2 h + f g ′ − f ′ g)x = 0

This above equation can be easily integrated if following conditions are satisfied.
1. f gp − g 2 h + f g ′ − f ′ g = 0
2. f gp − g 2 h + f g ′ − f ′ g = ag, f g + gp + g ′ = bg
If first condition is satisfied then it is solved by current dsolve solver and in second case
it becomes a constant coefficient differential equation which is also solved by current
solver.
Otherwise if the above condition fails then, a particular solution is assumed as x = x0 (t)
and y = y0 (t) Then the general solution is expressed as
∫
g(t)F (t)P (t)
x = C1 x0 (t) + C2 x0 (t) dt
x20 (t)
∫
F (t)P (t) g(t)F (t)P (t)
y = C1 y0 (t) + C2 [ + y0 (t) dt]
x0 (t) x20 (t)
where C1 and C2 are arbitrary constants and
∫ ∫
f (t) dt p(t) dt
F (t) = e , P (t) = e

system_of_odes_linear_2eq_order2_type1

sympy.solvers.ode._linear_2eq_order2_type1(x, y, t, r, eq)
System of two constant-coefficient second-order linear homogeneous differential equa-
tions

x′′ = ax + by

y ′′ = cx + dy
The characteristic equation for above equations

λ4 − (a + d)λ2 + ad − bc = 0

whose discriminant is D = (a − d)2 + 4bc ̸= 0

1. When ad − bc ̸= 0

5.30. ODE 1301

SymPy Documentation, Release 1.3

1.1. If D ̸= 0. The characteristic equation has four distinct roots, λ1 , λ2 , λ3 , λ4 . The general
solution of the system is

x = C1 beλ1 t + C2 beλ2 t + C3 beλ3 t + C4 beλ4 t

y = C1 (λ21 − a)eλ1 t + C2 (λ22 − a)eλ2 t + C3 (λ23 − a)eλ3 t + C4 (λ24 − a)eλ4 t

where C1 , ..., C4 are arbitrary constants.
1.2. If D = 0 and a ̸= d:
2bk kt 2bk −kt kt −kt
x = 2C1 (bt + )e 2 + 2C2 (bt + )e 2 + 2bC3 te 2 + 2bC4 te 2
a−d a−d
kt −kt kt −kt
y = C1 (d − a)te 2 + C2 (d − a)te + C3 [(d − a)t + 2k]e 2 + C4 [(d − a)t − 2k]e
2 2

√
where C1 , ..., C4 are arbitrary constants and k = 2(a + d)
1.3. If D = 0 and a = d ̸= 0 and b = 0:
√ √ √ √
x = 2 aC1 e at + 2 aC2 e− at
√ √ √ √
y = cC1 te at
− cC2 te− at
+ C3 e at
+ C4 e− at

1.4. If D = 0 and a = d ̸= 0 and c = 0:

√ √ √ √
x = bC1 te at
− bC2 te− at
+ C3 e at
+ C4 e− at

√ √ √ √
y = 2 aC1 e at + 2 aC2 e− at
2. When ad − bc = 0 and a2 + b2 > 0. Then the original system becomes
x′′ = ax + by

y ′′ = k(ax + by)
2.1. If a + bk ̸= 0:
√ √
x = C1 et a+bk
+ C2 e−t a+bk
+ C3 bt + C4 b
√ √
y = C1 ket a+bk
+ C2 ke−t a+bk
− C3 at − C4 a
2.2. If a + bk = 0:

x = C1 bt3 + C2 bt2 + C3 t + C4

y = kx + 6C1 t + 2C2

system_of_odes_linear_2eq_order2_type2

sympy.solvers.ode._linear_2eq_order2_type2(x, y, t, r, eq)
The equations in this type are

x′′ = a1 x + b1 y + c1

y ′′ = a2 x + b2 y + c2

1302 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The general solution of this system is given by the sum of its particular solution and the
general solution of the homogeneous system. The general solution is given by the linear
system of 2 equation of order 2 and type 1
1. If a1 b2 − a2 b1 ̸= 0. A particular solution will be x = x0 and y = y0 where the constants x0
and y0 are determined by solving the linear algebraic system

a1 x0 + b1 y0 + c1 = 0, a2 x0 + b2 y0 + c2 = 0

2. If a1 b2 − a2 b1 = 0 and a21 + b21 > 0. In this case, the system in question becomes
x′′ = ax + by + c1 , y ′′ = k(ax + by) + c2
2.1. If σ = a + bk ̸= 0, the particular solution will be
1 −1
x= bσ (c1 k − c2 )t2 − σ −2 (ac1 + bc2 )
2
1
y = kx + (c2 − c1 k)t2
2
2.2. If σ = a + bk = 0, the particular solution will be
1 1
x= b(c2 − c1 k)t4 + c1 t2
24 2
1
y = kx + (c2 − c1 k)t2
2

system_of_odes_linear_2eq_order2_type3

sympy.solvers.ode._linear_2eq_order2_type3(x, y, t, r, eq)
These type of equation is used for describing the horizontal motion of a pendulum taking
into account the Earth rotation. The solution is given with a2 + 4b > 0:

x = C1 cos(αt) + C2 sin(αt) + C3 cos(βt) + C4 sin(βt)

y = −C1 sin(αt) + C2 cos(αt) − C3 sin(βt) + C4 cos(βt)

where C1 , ..., C4 and
1 1√ 2 1 1√ 2
α= a+ a + 4b, β = a − a + 4b
2 2 2 2

system_of_odes_linear_2eq_order2_type4

sympy.solvers.ode._linear_2eq_order2_type4(x, y, t, r, eq)
These equations are found in the theory of oscillations

x′′ + a1 x′ + b1 y ′ + c1 x + d1 y = k1 eiωt

y ′′ + a2 x′ + b2 y ′ + c2 x + d2 y = k2 eiωt
The general solution of this linear nonhomogeneous system of constant-coefficient dif-
ferential equations is given by the sum of its particular solution and the general solution
of the corresponding homogeneous system (with k1 = k2 = 0)
1. A particular solution is obtained by the method of undetermined coefficients:

5.30. ODE 1303

SymPy Documentation, Release 1.3

x = A∗ eiωt , y = B∗ eiωt
On substituting these expressions into the original system of differential equations, one
arrive at a linear nonhomogeneous system of algebraic equations for the coefficients A
and B.
2. The general solution of the homogeneous system of differential equations is deter-
mined by a linear combination of linearly independent particular solutions determined
by the method of undetermined coefficients in the form of exponentials:

x = Aeλt , y = Beλt

On substituting these expressions into the original system and collecting the coefficients
of the unknown A and B, one obtains

(λ2 + a1 λ + c1 )A + (b1 λ + d1 )B = 0

(a2 λ + c2 )A + (λ2 + b2 λ + d2 )B = 0
The determinant of this system must vanish for nontrivial solutions A, B to exist. This
requirement results in the following characteristic equation for λ

(λ2 + a1 λ + c1 )(λ2 + b2 λ + d2 ) − (b1 λ + d1 )(a2 λ + c2 ) = 0

If all roots k1 , ..., k4 of this equation are distinct, the general solution of the original system
of the differential equations has the form

x = C1 (b1 λ1 + d1 )eλ1 t − C2 (b1 λ2 + d1 )eλ2 t − C3 (b1 λ3 + d1 )eλ3 t − C4 (b1 λ4 + d1 )eλ4 t

y = C1 (λ21 + a1 λ1 + c1 )eλ1 t + C2 (λ22 + a1 λ2 + c1 )eλ2 t + C3 (λ23 + a1 λ3 + c1 )eλ3 t + C4 (λ24 + a1 λ4 + c1 )eλ4 t

system_of_odes_linear_2eq_order2_type5

sympy.solvers.ode._linear_2eq_order2_type5(x, y, t, r, eq)
The equation which come under this category are

x′′ = a(ty ′ − y)

y ′′ = b(tx′ − x)
The transformation

u = tx′ − x, b = ty ′ − y

leads to the first-order system

u′ = atv, v ′ = btu

The general solution of this system is given by

If ab > 0:
√ √
abt2
+ C2 ae− 2 abt2
1 1
u = C1 ae 2
√ √ √ √
v = C1 abe 2 abt − C2 abe− 2 abt
1 2 1 2

1304 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If ab < 0:
1√ 1√
u = C1 a cos( |ab|t2 ) + C2 a sin(− |ab|t2 )
2 2
√ 1√ √ 1√
v = C1 |ab| sin( |ab|t2 ) + C2 |ab| cos(− |ab|t2 )
2 2
where C1 and C2 are arbitrary constants. On substituting the value of u and v in above
equations and integrating the resulting expressions, the general solution will become
∫ ∫
u u
x = C3 t + t dt, y = C 4 t + t dt
t2 t2
where C3 and C4 are arbitrary constants.

system_of_odes_linear_2eq_order2_type6

sympy.solvers.ode._linear_2eq_order2_type6(x, y, t, r, eq)
The equations are

x′′ = f (t)(a1 x + b1 y)

y ′′ = f (t)(a2 x + b2 y)
If k1 and k2 are roots of the quadratic equation

k 2 − (a1 + b2 )k + a1 b2 − a2 b1 = 0

Then by multiplying appropriate constants and adding together original equations we

obtain two independent equations:

z1′′ = k1 f (t)z1 , z1 = a2 x + (k1 − a1 )y

z2′′ = k2 f (t)z2 , z2 = a2 x + (k2 − a1 )y

Solving the equations will give the values of x and y after obtaining the value of z1 and
z2 by solving the differential equation and substituting the result.

system_of_odes_linear_2eq_order2_type7

sympy.solvers.ode._linear_2eq_order2_type7(x, y, t, r, eq)
The equations are given as

x′′ = f (t)(a1 x′ + b1 y ′ )

y ′′ = f (t)(a2 x′ + b2 y ′ )
If k1 and ‘k_2‘ are roots of the quadratic equation

k 2 − (a1 + b2 )k + a1 b2 − a2 b1 = 0

Then the system can be reduced by adding together the two equations multiplied by
appropriate constants give following two independent equations:

z1′′ = k1 f (t)z1′ , z1 = a2 x + (k1 − a1 )y

5.30. ODE 1305

SymPy Documentation, Release 1.3

z2′′ = k2 f (t)z2′ , z2 = a2 x + (k2 − a1 )y

Integrating these and returning to the original variables, one arrives at a linear algebraic
system for the unknowns x and y:
∫
a2 x + (k1 − a1 )y = C1 ek1 F (t) dt + C2
∫
a2 x + (k2 − a1 )y = C3 ek2 F (t) dt + C4
∫
where C1 , ..., C4 are arbitrary constants and F (t) = f (t) dt

system_of_odes_linear_2eq_order2_type8

sympy.solvers.ode._linear_2eq_order2_type8(x, y, t, r, eq)
The equation of this category are

x′′ = af (t)(ty ′ − y)

y ′′ = bf (t)(tx′ − x)
The transformation

u = tx′ − x, v = ty ′ − y

leads to the system of first-order equations

u′ = atf (t)v, v ′ = btf (t)u

The general solution of this system has the form

If ab > 0:
√ ∫ √ ∫
u = C1 ae ab tf (t) dt
+ C2 ae− ab tf (t) dt

√ √ ∫ √ √ ∫
v = C1 abe ab tf (t) dt − C2 abe− ab tf (t) dt
If ab < 0:
√ ∫ √ ∫
u = C1 a cos( |ab| tf (t) dt) + C2 a sin(− |ab| tf (t) dt)

√ √ ∫ √ √ ∫
v = C1 |ab| sin( |ab| tf (t) dt) + C2 |ab| cos(− |ab| tf (t) dt)

where C1 and C2 are arbitrary constants. On substituting the value of u and v in above
equations and integrating the resulting expressions, the general solution will become
∫ ∫
u u
x = C3 t + t 2
dt, y = C4 t + t dt
t t2

where C3 and C4 are arbitrary constants.

1306 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system_of_odes_linear_2eq_order2_type9

sympy.solvers.ode._linear_2eq_order2_type9(x, y, t, r, eq)

t2 x′′ + a1 tx′ + b1 ty ′ + c1 x + d1 y = 0

t2 y ′′ + a2 tx′ + b2 ty ′ + c2 x + d2 y = 0
These system of equations are euler type.
The substitution of t = σeτ (σ ̸= 0) leads to the system of constant coefficient linear differ-
ential equations

x′′ + (a1 − 1)x′ + b1 y ′ + c1 x + d1 y = 0

y ′′ + a2 x′ + (b2 − 1)y ′ + c2 x + d2 y = 0
The general solution of the homogeneous system of differential equations is determined
by a linear combination of linearly independent particular solutions determined by the
method of undetermined coefficients in the form of exponentials

x = Aeλt , y = Beλt

On substituting these expressions into the original system and collecting the coefficients
of the unknown A and B, one obtains

(λ2 + (a1 − 1)λ + c1 )A + (b1 λ + d1 )B = 0

(a2 λ + c2 )A + (λ2 + (b2 − 1)λ + d2 )B = 0

The determinant of this system must vanish for nontrivial solutions A, B to exist. This
requirement results in the following characteristic equation for λ

(λ2 + (a1 − 1)λ + c1 )(λ2 + (b2 − 1)λ + d2 ) − (b1 λ + d1 )(a2 λ + c2 ) = 0

If all roots k1 , ..., k4 of this equation are distinct, the general solution of the original system
of the differential equations has the form

x = C1 (b1 λ1 + d1 )eλ1 t − C2 (b1 λ2 + d1 )eλ2 t − C3 (b1 λ3 + d1 )eλ3 t − C4 (b1 λ4 + d1 )eλ4 t

y = C1 (λ21 + (a1 − 1)λ1 + c1 )eλ1 t + C2 (λ22 + (a1 − 1)λ2 + c1 )eλ2 t + C3 (λ23 + (a1 − 1)λ3 + c1 )eλ3 t + C4 (λ24 + (a1 − 1)λ4 +

system_of_odes_linear_2eq_order2_type10

sympy.solvers.ode._linear_2eq_order2_type10(x, y, t, r, eq)
The equation of this category are

(αt2 + βt + γ)2 x′′ = ax + by

(αt2 + βt + γ)2 y ′′ = cx + dy
The transformation
∫
1 x y
τ= dt, u = √ ,v = √
αt2 + βt + γ |αt + βt + γ|
2 |αt + βt + γ|
2

5.30. ODE 1307

SymPy Documentation, Release 1.3

leads to a constant coefficient linear system of equations

1
u′′ = (a − αγ + β 2 )u + bv
4
1
v ′′ = cu + (d − αγ + β 2 )v
4
These system of equations obtained can be solved by type1 of System of two constant-
coefficient second-order linear homogeneous differential equations.

system_of_odes_linear_2eq_order2_type11

sympy.solvers.ode._linear_2eq_order2_type11(x, y, t, r, eq)
The equations which comes under this type are

x′′ = f (t)(tx′ − x) + g(t)(ty ′ − y)

y ′′ = h(t)(tx′ − x) + p(t)(ty ′ − y)
The transformation

u = tx′ − x, v = ty ′ − y

leads to the linear system of first-order equations

u′ = tf (t)u + tg(t)v, v ′ = th(t)u + tp(t)v

On substituting the value of u and v in transformed equation gives value of x and y as

∫ ∫
u v
x = C3 t + t 2
dt, y = C4 t + t dt.
t t2
where C3 and C4 are arbitrary constants.

system_of_odes_linear_3eq_order1_type1

sympy.solvers.ode._linear_3eq_order1_type1(x, y, z, t, r, eq)

x′ = ax

y ′ = bx + cy

z ′ = dx + ky + pz
Solution of such equations are forward substitution. Solving first equations gives the
value of x, substituting it in second and third equation and solving second equation gives
y and similarly substituting y in third equation give z.

x = C1 eat

bC1 at
y= e + C2 ect
a−c
C1 bk kC2 ct
z= (d + )eat + e + C3 ept
a−p a−c c−p
where C1 , C2 and C3 are arbitrary constants.

1308 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system_of_odes_linear_3eq_order1_type2

sympy.solvers.ode._linear_3eq_order1_type2(x, y, z, t, r, eq)
The equations of this type are

x′ = cy − bz

y ′ = az − cx
z ′ = bx − ay
1. First integral:
ax + by + cz = A − (1)
x2 + y 2 + z 2 = B 2 − (2)
where A and B are arbitrary constants. It follows from these integrals that the integral
lines are circles formed by the intersection of the planes (1) and sphere (2)
2. Solution:
x = aC0 + kC1 cos(kt) + (cC2 − bC3 ) sin(kt)
y = bC0 + kC2 cos(kt) + (aC2 − cC3 ) sin(kt)
z = cC0 + kC3 cos(kt) + (bC2 − aC3 ) sin(kt)
√
where k = a2 + b2 + c2 and the four constants of integration, C1 , ..., C4 are constrained by
a single relation,

aC1 + bC2 + cC3 = 0

system_of_odes_linear_3eq_order1_type3

sympy.solvers.ode._linear_3eq_order1_type3(x, y, z, t, r, eq)
Equations of this system of ODEs

ax′ = bc(y − z)

by ′ = ac(z − x)
cz ′ = ab(x − y)
1. First integral:
a2 x + b2 y + c2 z = A
where A is an arbitrary constant. It follows that the integral lines are plane curves.
2. Solution:
x = C0 + kC1 cos(kt) + a−1 bc(C2 − C3 ) sin(kt)
y = C0 + kC2 cos(kt) + ab−1 c(C3 − C1 ) sin(kt)
z = C0 + kC3 cos(kt) + abc−1 (C1 − C2 ) sin(kt)
√
where k = a2 + b2 + c2 and the four constants of integration, C1 , ..., C4 are constrained by
a single relation

a2 C1 + b2 C2 + c2 C3 = 0

5.30. ODE 1309

SymPy Documentation, Release 1.3

system_of_odes_linear_3eq_order1_type4

sympy.solvers.ode._linear_3eq_order1_type4(x, y, z, t, r, eq)
Equations:

x′ = (a1 f (t) + g(t))x + a2 f (t)y + a3 f (t)z

y ′ = b1 f (t)x + (b2 f (t) + g(t))y + b3 f (t)z

z ′ = c1 f (t)x + c2 f (t)y + (c3 f (t) + g(t))z

The transformation
∫ ∫ ∫
∫
g(t) dt g(t) dt g(t) dt
x=e u, y = e v, z = e w, τ = f (t) dt

leads to the system of constant coefficient linear differential equations

u′ = a1 u + a2 v + a3 w

v ′ = b1 u + b2 v + b3 w

w′ = c1 u + c2 v + c3 w
These system of equations are solved by homogeneous linear system of constant coef-
ficients of n equations of first order. Then substituting the value of u, v and w in trans-
formed equation gives value of x, y and z.

system_of_odes_linear_neq_order1_type1

sympy.solvers.ode._linear_neq_order1_type1(match_)
System of n first-order constant-coefficient linear nonhomogeneous differential equation

yk′ = ak1 y1 + ak2 y2 + ... + akn yn ; k = 1, 2, ..., n

or that can be written as y⃗′ = A.⃗y where ⃗y is matrix of yk for k = 1, 2, ...n and A is a n × n
matrix.
Since these equations are equivalent to a first order homogeneous linear differential
equation. So the general solution will contain n linearly independent parts and solution
will consist some type of exponential functions. Assuming y = ⃗v ert is a solution of the
system where ⃗v is a vector of coefficients of y1 , ..., yn . Substituting y and y ′ = rvert into the
equation y⃗′ = A.⃗y , we get

r⃗v ert = A⃗v ert

r⃗v = A⃗v
where r comes out to be eigenvalue of A and vector ⃗v is the eigenvector of A correspond-
ing to r. There are three possibilities of eigenvalues of A
• n distinct real eigenvalues
• complex conjugate eigenvalues
• eigenvalues with multiplicity k

1310 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

1. When all eigenvalues r1 , .., rn are distinct with n different eigenvectors v1 , ...vn then the
solution is given by

⃗y = C1 er1 t v⃗1 + C2 er2 t v⃗2 + ... + Cn ern t v⃗n

where C1 , C2 , ..., Cn are arbitrary constants.

2. When some eigenvalues are complex then in order to make the solution real, we
take a linear combination: if r = a + bi has an eigenvector ⃗v = w⃗1 + iw⃗2 then to obtain
real-valued solutions to the system, replace the complex-valued solutions erx⃗v with real-
valued solution eax (w⃗1 cos(bx) − w⃗2 sin(bx)) and for r = a − bi replace the solution e−rx⃗v with
eax (w⃗1 sin(bx) + w⃗2 cos(bx))
3. If some eigenvalues are repeated. Then we get fewer than n linearly independent
eigenvectors, we miss some of the solutions and need to construct the missing ones. We
do this via generalized eigenvectors, vectors which are not eigenvectors but are close
enough that we can use to write down the remaining solutions. For a eigenvalue r with
eigenvector w⃗ we obtain w⃗2 , ..., w⃗k using

(A − rI).w⃗2 = w
⃗

(A − rI).w⃗3 = w⃗2
..
.
(A − rI).w⃗k = wk−1
⃗
2
Then the solutions to the system for the eigenspace are ert [w], ⃗ + w⃗2 ], ert [ t2 w
⃗ ert [tw ⃗ + tw⃗2 +
k−1 k−2
rt t t
w⃗3 ], ..., e [ (k−1)! w
⃗ + (k−2)! w⃗2 + ... + twk−1
⃗ + w⃗k ]
So, If y⃗1 , ..., y⃗n are n solution of obtained from three categories of A, then general solution
to the system y⃗′ = A.⃗y

⃗y = C1 y⃗1 + C2 y⃗2 + · · · + Cn y⃗n

system_of_odes_nonlinear_2eq_order1_type1

sympy.solvers.ode._nonlinear_2eq_order1_type1(x, y, t, eq)
Equations:

x′ = xn F (x, y)

y ′ = g(y)F (x, y)
Solution:
∫
1
x = φ(y), dy = t + C2
g(y)F (φ(y), y)
where
if n ̸= 1
∫
1 1
φ = [C1 + (1 − n) dy] 1−n
g(y)
if n = 1
∫ 1
dy
φ = C1 e g(y)

where C1 and C2 are arbitrary constants.

5.30. ODE 1311

SymPy Documentation, Release 1.3

system_of_odes_nonlinear_2eq_order1_type2

sympy.solvers.ode._nonlinear_2eq_order1_type2(x, y, t, eq)
Equations:

x′ = eλx F (x, y)

y ′ = g(y)F (x, y)
Solution:
∫
1
x = φ(y), dy = t + C2
g(y)F (φ(y), y)

where
if λ ̸= 0
∫
1 1
φ = − log(C1 − λ dy)
λ g(y)

if λ = 0
∫
1
φ = C1 + dy
g(y)

where C1 and C2 are arbitrary constants.

system_of_odes_nonlinear_2eq_order1_type3

sympy.solvers.ode._nonlinear_2eq_order1_type3(x, y, t, eq)
Autonomous system of general form

x′ = F (x, y)

y ′ = G(x, y)
Assuming y = y(x, C1 ) where C1 is an arbitrary constant is the general solution of the
first-order equation

F (x, y)yx′ = G(x, y)

Then the general solution of the original system of equations has the form
∫
1
dx = t + C1
F (x, y(x, C1 ))

system_of_odes_nonlinear_2eq_order1_type4

sympy.solvers.ode._nonlinear_2eq_order1_type4(x, y, t, eq)
Equation:

x′ = f1 (x)g1 (y)ϕ(x, y, t)

y ′ = f2 (x)g2 (y)ϕ(x, y, t)

1312 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

First integral:
∫ ∫
f2 (x) g1 (y)
dx − dy = C
f1 (x) g2 (y)

where C is an arbitrary constant.

On solving the first integral for x (resp., y ) and on substituting the resulting expression
into either equation of the original solution, one arrives at a first-order equation for
determining y (resp., x ).

system_of_odes_nonlinear_2eq_order1_type5

sympy.solvers.ode._nonlinear_2eq_order1_type5(func, t, eq)
Clairaut system of ODEs

x = tx′ + F (x′ , y ′ )

y = ty ′ + G(x′ , y ′ )
The following are solutions of the system
(i) straight lines:

x = C1 t + F (C1 , C2 ), y = C2 t + G(C1 , C2 )

where C1 and C2 are arbitrary constants;

(ii) envelopes of the above lines;
(iii) continuously differentiable lines made up from segments of the lines (i) and (ii).

system_of_odes_nonlinear_3eq_order1_type1

sympy.solvers.ode._nonlinear_3eq_order1_type1(x, y, z, t, eq)
Equations:

ax′ = (b − c)yz, by ′ = (c − a)zx, cz ′ = (a − b)xy

First Integrals:

ax2 + by 2 + cz 2 = C1

a2 x2 + b2 y 2 + c2 z 2 = C2
where C1 and C2 are arbitrary constants. On solving the integrals for y and z and on
substituting the resulting expressions into the first equation of the system, we arrives at
a separable first-order equation on x. Similarly doing that for other two equations, we
will arrive at first order equation on y and z too.

References

-http://eqworld.ipmnet.ru/en/solutions/sysode/sode0401.pdf

5.30. ODE 1313

SymPy Documentation, Release 1.3

system_of_odes_nonlinear_3eq_order1_type2

sympy.solvers.ode._nonlinear_3eq_order1_type2(x, y, z, t, eq)
Equations:

ax′ = (b − c)yzf (x, y, z, t)

by ′ = (c − a)zxf (x, y, z, t)

cz ′ = (a − b)xyf (x, y, z, t)
First Integrals:

ax2 + by 2 + cz 2 = C1

a2 x2 + b2 y 2 + c2 z 2 = C2
where C1 and C2 are arbitrary constants. On solving the integrals for y and z and on
substituting the resulting expressions into the first equation of the system, we arrives at
a first-order differential equations on x. Similarly doing that for other two equations we
will arrive at first order equation on y and z.

References

-http://eqworld.ipmnet.ru/en/solutions/sysode/sode0402.pdf

system_of_odes_nonlinear_3eq_order1_type3

sympy.solvers.ode._nonlinear_3eq_order1_type3(x, y, z, t, eq)
Equations:

x′ = cF2 − bF3 , y ′ = aF3 − cF1 , z ′ = bF1 − aF2

where Fn = Fn (x, y, z, t).

1. First Integral:
ax + by + cz = C1 ,
where C is an arbitrary constant.
2. If we assume function Fn to be independent of t,i.e, Fn = Fn (x, y, z) Then, on eliminating
t and z from the first two equation of the system, one arrives at the first-order equation

dy aF3 (x, y, z) − cF1 (x, y, z)

=
dx cF2 (x, y, z) − bF3 (x, y, z)

where z = 1c (C1 − ax − by)

References

-http://eqworld.ipmnet.ru/en/solutions/sysode/sode0404.pdf

1314 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system_of_odes_nonlinear_3eq_order1_type4

sympy.solvers.ode._nonlinear_3eq_order1_type4(x, y, z, t, eq)
Equations:

x′ = czF2 − byF3 , y ′ = axF3 − czF1 , z ′ = byF1 − axF2

where Fn = Fn (x, y, z, t)
1. First integral:
ax2 + by 2 + cz 2 = C1
where C is an arbitrary constant.
2. Assuming the function Fn is independent of t: Fn = Fn (x, y, z). Then on eliminating t
and z from the first two equations of the system, one arrives at the first-order equation

dy axF3 (x, y, z) − czF1 (x, y, z)

=
dx czF2 (x, y, z) − byF3 (x, y, z)
√
where z = ± 1
c (C1 − ax2 − by 2 )

References

-http://eqworld.ipmnet.ru/en/solutions/sysode/sode0405.pdf

system_of_odes_nonlinear_3eq_order1_type5

sympy.solvers.ode._nonlinear_3eq_order1_type5(x, y, t, eq)

x′ = x(cF2 − bF3 ), y ′ = y(aF3 − cF1 ), z ′ = z(bF1 − aF2 )

where Fn = Fn (x, y, z, t) and are arbitrary functions.

First Integral:
a b c
|x| |y| |z| = C1

where C is an arbitrary constant. If the function Fn is independent of t, then, by elim-

inating t and z from the first two equations of the system, one arrives at a first-order
equation.

References

-http://eqworld.ipmnet.ru/en/solutions/sysode/sode0406.pdf

5.30. ODE 1315

SymPy Documentation, Release 1.3

5.30.5 Information on the ode module

This module contains dsolve() (page 1262) and different helper functions that it uses.
dsolve() (page 1262) solves ordinary differential equations. See the docstring on the various
functions for their uses. Note that partial differential equations support is in pde.py. Note
that hint functions have docstrings describing their various methods, but they are intended
for internal use. Use dsolve(ode, func, hint=hint) to solve an ODE using a specific hint.
See also the docstring on dsolve() (page 1262).
Functions in this module
These are the user functions in this module:
• dsolve() (page 1262) - Solves ODEs.
• classify_ode() (page 1265) - Classifies ODEs into possible hints for dsolve()
(page 1262).
• checkodesol() (page 1267) - Checks if an equation is the solution to an ODE.
• homogeneous_order() (page 1267) - Returns the homogeneous order of an ex-
pression.
• infinitesimals() (page 1268) - Returns the infinitesimals of the Lie group of
point transformations of an ODE, such that it is invariant.
• ode_checkinfsol() - Checks if the given infinitesimals are the actual infinites-
imals of a first order ODE.
These are the non-solver helper functions that are for internal use. The user should
use the various options to dsolve() (page 1262) to obtain the functionality provided
by these functions:
• odesimp() (page 1270) - Does all forms of ODE simplification.
• ode_sol_simplicity() (page 1273) - A key function for comparing solutions
by simplicity.
• constantsimp() (page 1272) - Simplifies arbitrary constants.
• constant_renumber() (page 1271) - Renumber arbitrary constants.
• _handle_Integral() - Evaluate unevaluated Integrals.
See also the docstrings of these functions.
Currently implemented solver methods
The following methods are implemented for solving ordinary differential equations. See the
docstrings of the various hint functions for more information on each (run help(ode)):
• 1st order separable differential equations.
• 1st order differential equations whose coefficients or dx and dy are functions homoge-
neous of the same order.
• 1st order exact differential equations.
• 1st order linear differential equations.
• 1st order Bernoulli differential equations.
• Power series solutions for first order differential equations.
• Lie Group method of solving first order differential equations.

1316 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• 2nd order Liouville differential equations.

• Power series solutions for second order differential equations at ordinary and regular
singular points.
• nth order linear homogeneous differential equation with constant coefficients.
• nth order linear inhomogeneous differential equation with constant coefficients using
the method of undetermined coefficients.
• nth order linear inhomogeneous differential equation with constant coefficients using
the method of variation of parameters.
Philosophy behind this module
This module is designed to make it easy to add new ODE solving methods without having to
mess with the solving code for other methods. The idea is that there is a classify_ode()
(page 1265) function, which takes in an ODE and tells you what hints, if any, will solve the
ODE. It does this without attempting to solve the ODE, so it is fast. Each solving method is a
hint, and it has its own function, named ode_<hint>. That function takes in the ODE and any
match expression gathered by classify_ode() (page 1265) and returns a solved result. If this
result has any integrals in it, the hint function will return an unevaluated Integral (page 714)
class. dsolve() (page 1262), which is the user wrapper function around all of this, will then
call odesimp() (page 1270) on the result, which, among other things, will attempt to solve the
equation for the dependent variable (the function we are solving for), simplify the arbitrary
constants in the expression, and evaluate any integrals, if the hint allows it.
How to add new solution methods
If you have an ODE that you want dsolve() (page 1262) to be able to solve, try to avoid adding
special case code here. Instead, try finding a general method that will solve your ODE, as well
as others. This way, the ode (page 1316) module will become more robust, and unhindered
by special case hacks. WolphramAlpha and Maple’s DETools[odeadvisor] function are two
resources you can use to classify a specific ODE. It is also better for a method to work with
an nth order ODE instead of only with specific orders, if possible.
To add a new method, there are a few things that you need to do. First, you need a hint name
for your method. Try to name your hint so that it is unambiguous with all other methods,
including ones that may not be implemented yet. If your method uses integrals, also in-
clude a hint_Integral hint. If there is more than one way to solve ODEs with your method,
include a hint for each one, as well as a <hint>_best hint. Your ode_<hint>_best() func-
tion should choose the best using min with ode_sol_simplicity as the key argument. See
ode_1st_homogeneous_coeff_best() (page 1275), for example. The function that uses your
method will be called ode_<hint>(), so the hint must only use characters that are allowed in
a Python function name (alphanumeric characters and the underscore ‘_’ character). Include
a function for every hint, except for _Integral hints (dsolve() (page 1262) takes care of
those automatically). Hint names should be all lowercase, unless a word is commonly cap-
italized (such as Integral or Bernoulli). If you have a hint that you do not want to run with
all_Integral that doesn’t have an _Integral counterpart (such as a best hint that would
defeat the purpose of all_Integral), you will need to remove it manually in the dsolve()
(page 1262) code. See also the classify_ode() (page 1265) docstring for guidelines on writ-
ing a hint name.
Determine in general how the solutions returned by your method compare with other methods
that can potentially solve the same ODEs. Then, put your hints in the allhints (page 1270)
tuple in the order that they should be called. The ordering of this tuple determines which
hints are default. Note that exceptions are ok, because it is easy for the user to choose indi-
vidual hints with dsolve() (page 1262). In general, _Integral variants should go at the end
of the list, and _best variants should go before the various hints they apply to. For example,

5.30. ODE 1317

SymPy Documentation, Release 1.3

the undetermined_coefficients hint comes before the variation_of_parameters hint be-

cause, even though variation of parameters is more general than undetermined coefficients,
undetermined coefficients generally returns cleaner results for the ODEs that it can solve
than variation of parameters does, and it does not require integration, so it is much faster.
Next, you need to have a match expression or a function that matches the type of the ODE,
which you should put in classify_ode() (page 1265) (if the match function is more than
just a few lines, like _undetermined_coefficients_match(), it should go outside of clas-
sify_ode() (page 1265)). It should match the ODE without solving for it as much as possible,
so that classify_ode() (page 1265) remains fast and is not hindered by bugs in solving code.
Be sure to consider corner cases. For example, if your solution method involves dividing by
something, make sure you exclude the case where that division will be 0.
In most cases, the matching of the ODE will also give you the various parts that you
need to solve it. You should put that in a dictionary (.match() will do this for you),
and add that as matching_hints['hint'] = matchdict in the relevant part of clas-
sify_ode() (page 1265). classify_ode() (page 1265) will then send this to dsolve()
(page 1262), which will send it to your function as the match argument. Your function
should be named ode_<hint>(eq, func, order, match)`. If you need to send more
information, put it in the ``match dictionary. For example, if you had to substitute in
a dummy variable in classify_ode() (page 1265) to match the ODE, you will need to pass
it to your function using the match dict to access it. You can access the independent variable
using func.args[0], and the dependent variable (the function you are trying to solve for)
as func.func. If, while trying to solve the ODE, you find that you cannot, raise NotImple-
mentedError. dsolve() (page 1262) will catch this error with the all meta-hint, rather than
causing the whole routine to fail.
Add a docstring to your function that describes the method employed. Like with anything
else in SymPy, you will need to add a doctest to the docstring, in addition to real tests in
test_ode.py. Try to maintain consistency with the other hint functions’ docstrings. Add
your method to the list at the top of this docstring. Also, add your method to ode.rst in
the docs/src directory, so that the Sphinx docs will pull its docstring into the main SymPy
documentation. Be sure to make the Sphinx documentation by running make html from within
the doc directory to verify that the docstring formats correctly.
If your solution method involves integrating, use Integral() instead of integrate()
(page 128). This allows the user to bypass hard/slow integration by using the _Integral
variant of your hint. In most cases, calling sympy.core.basic.Basic.doit() (page 104)
will integrate your solution. If this is not the case, you will need to write special code in
_handle_Integral(). Arbitrary constants should be symbols named C1, C2, and so on. All
solution methods should return an equality instance. If you need an arbitrary number of ar-
bitrary constants, you can use constants = numbered_symbols(prefix='C', cls=Symbol,
start=1). If it is possible to solve for the dependent function in a general way, do so. Other-
wise, do as best as you can, but do not call solve in your ode_<hint>() function. odesimp()
(page 1270) will attempt to solve the solution for you, so you do not need to do that. Lastly,
if your ODE has a common simplification that can be applied to your solutions, you can add
a special case in odesimp() (page 1270) for it. For example, solutions returned from the
1st_homogeneous_coeff hints often have many log() terms, so odesimp() (page 1270) calls
logcombine() (page 1191) on them (it also helps to write the arbitrary constant as log(C1)
instead of C1 in this case). Also consider common ways that you can rearrange your solution
to have constantsimp() (page 1272) take better advantage of it. It is better to put simplifi-
cation in odesimp() (page 1270) than in your method, because it can then be turned off with
the simplify flag in dsolve() (page 1262). If you have any extraneous simplification in your
function, be sure to only run it using if match.get('simplify', True):, especially if it can
be slow or if it can reduce the domain of the solution.

1318 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Finally, as with every contribution to SymPy, your method will need to be tested. Add a
test for each method in test_ode.py. Follow the conventions there, i.e., test the solver us-
ing dsolve(eq, f(x), hint=your_hint), and also test the solution using checkodesol()
(page 1267) (you can put these in a separate tests and skip/XFAIL if it runs too slow/doesn’t
work). Be sure to call your hint specifically in dsolve() (page 1262), that way the test won’t be
broken simply by the introduction of another matching hint. If your method works for higher
order (>1) ODEs, you will need to run sol = constant_renumber(sol, 'C', 1, order) for
each solution, where order is the order of the ODE. This is because constant_renumber
renumbers the arbitrary constants by printing order, which is platform dependent. Try to
test every corner case of your solver, including a range of orders if it is a nth order solver,
but if your solver is slow, such as if it involves hard integration, try to keep the test run time
down.
Feel free to refactor existing hints to avoid duplicating code or creating inconsistencies. If you
can show that your method exactly duplicates an existing method, including in the simplicity
and speed of obtaining the solutions, then you can remove the old, less general method. The
existing code is tested extensively in test_ode.py, so if anything is broken, one of those tests
will surely fail.

5.31 PDE

5.31.1 User Functions

These are functions that are imported into the global namespace with from sympy import *.
They are intended for user use.

pde_separate()

sympy.solvers.pde.pde_separate(eq, fun, sep, strategy=’mul’)

Separate variables in partial differential equation either by additive or multiplicative
separation approach. It tries to rewrite an equation so that one of the specified variables
occurs on a different side of the equation than the others.
Parameters
• eq – Partial differential equation
• fun – Original function F(x, y, z)
• sep – List of separated functions [X(x), u(y, z)]
• strategy – Separation strategy. You can choose between additive sepa-
ration (‘add’) and multiplicative separation (‘mul’) which is default.
See also:
pde_separate_add (page 1320), pde_separate_mul (page 1320)

Examples

>>> from sympy import E, Eq, Function, pde_separate, Derivative as D

>>> from sympy.abc import x, t
>>> u, X, T = map(Function, 'uXT')

5.31. PDE 1319

SymPy Documentation, Release 1.3

>>> eq = Eq(D(u(x, t), x), E**(u(x, t))*D(u(x, t), t))

>>> pde_separate(eq, u(x, t), [X(x), T(t)], strategy='add')
[exp(-X(x))*Derivative(X(x), x), exp(T(t))*Derivative(T(t), t)]

>>> eq = Eq(D(u(x, t), x, 2), D(u(x, t), t, 2))

>>> pde_separate(eq, u(x, t), [X(x), T(t)], strategy='mul')
[Derivative(X(x), (x, 2))/X(x), Derivative(T(t), (t, 2))/T(t)]

pde_separate_add()

sympy.solvers.pde.pde_separate_add(eq, fun, sep)

Helper function for searching additive separable solutions.
Consider an equation of two independent variables x, y and a dependent variable w, we
look for the product of two functions depending on different arguments:
w(x, y, z) = X(x) + y(y, z)

Examples

>>> from sympy import E, Eq, Function, pde_separate_add, Derivative as D

>>> from sympy.abc import x, t
>>> u, X, T = map(Function, 'uXT')

>>> eq = Eq(D(u(x, t), x), E**(u(x, t))*D(u(x, t), t))

>>> pde_separate_add(eq, u(x, t), [X(x), T(t)])
[exp(-X(x))*Derivative(X(x), x), exp(T(t))*Derivative(T(t), t)]

pde_separate_mul()

sympy.solvers.pde.pde_separate_mul(eq, fun, sep)

Helper function for searching multiplicative separable solutions.
Consider an equation of two independent variables x, y and a dependent variable w, we
look for the product of two functions depending on different arguments:
w(x, y, z) = X(x) ∗ u(y, z)

Examples

>>> from sympy import Function, Eq, pde_separate_mul, Derivative as D

>>> from sympy.abc import x, y
>>> u, X, Y = map(Function, 'uXY')

>>> eq = Eq(D(u(x, y), x, 2), D(u(x, y), y, 2))

>>> pde_separate_mul(eq, u(x, y), [X(x), Y(y)])
[Derivative(X(x), (x, 2))/X(x), Derivative(Y(y), (y, 2))/Y(y)]

1320 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

pdsolve()

sympy.solvers.pde.pdsolve(eq, func=None, hint=’default’, dict=False, solve-

fun=None, **kwargs)
Solves any (supported) kind of partial differential equation.
Usage
pdsolve(eq, f(x,y), hint) -> Solve partial differential equation eq for function
f(x,y), using method hint.
Details
eq can be any supported partial differential equation (see the pde doc-
string for supported methods). This can either be an Equality, or an ex-
pression, which is assumed to be equal to 0.
f(x,y) is a function of two variables whose derivatives in that variable
make up the partial differential equation. In many cases it is not necessary
to provide this; it will be autodetected (and an error raised if it couldn’t be
detected).
hint is the solving method that you want pdsolve to use. Use
classify_pde(eq, f(x,y)) to get all of the possible hints for a PDE. The default
hint, ‘default’, will use whatever hint is returned first by classify_pde(). See
Hints below for more options that you can use for hint.
solvefun is the convention used for arbitrary functions returned by the
PDE solver. If not set by the user, it is set by default to be F.
Hints
Aside from the various solving methods, there are also some meta-hints that you
can pass to pdsolve():
“default”: This uses whatever hint is returned first by classify_pde(). This is
the default argument to pdsolve().
“all”: To make pdsolve apply all relevant classification hints, use pdsolve(PDE,
func, hint=”all”). This will return a dictionary of hint:solution terms. If a
hint causes pdsolve to raise the NotImplementedError, value of that hint’s
key will be the exception object raised. The dictionary will also include some
special keys:
• order: The order of the PDE. See also ode_order() in deutils.py
• default: The solution that would be returned by default. This is the one
produced by the hint that appears first in the tuple returned by clas-
sify_pde().
“all_Integral”: This is the same as “all”, except if a hint also has a correspond-
ing “_Integral” hint, it only returns the “_Integral” hint. This is useful if
“all” causes pdsolve() to hang because of a difficult or impossible integral.
This meta-hint will also be much faster than “all”, because integrate() is an
expensive routine.
See also the classify_pde() docstring for more info on hints, and the pde doc-
string for a list of all supported hints.

Tips
• You can declare the derivative of an unknown function this way:

5.31. PDE 1321

SymPy Documentation, Release 1.3

>>> from sympy import Function, Derivative

>>> from sympy.abc import x, y # x and y are the independent variables
>>> f = Function(”f”)(x, y) # f is a function of x and y
>>> # fx will be the partial derivative of f with respect to x
>>> fx = Derivative(f, x)
>>> # fy will be the partial derivative of f with respect to y
>>> fy = Derivative(f, y)

• See test_pde.py for many tests, which serves also as a set of examples for how
to use pdsolve().
• pdsolve always returns an Equality class (except for the case when the hint is
“all” or “all_Integral”). Note that it is not possible to get an explicit solution for
f(x, y) as in the case of ODE’s
• Do help(pde.pde_hintname) to get help more information on a specific hint

Examples

>>> from sympy.solvers.pde import pdsolve

>>> from sympy import Function, diff, Eq
>>> from sympy.abc import x, y
>>> f = Function('f')
>>> u = f(x, y)
>>> ux = u.diff(x)
>>> uy = u.diff(y)
>>> eq = Eq(1 + (2*(ux/u)) + (3*(uy/u)))
>>> pdsolve(eq)
Eq(f(x, y), F(3*x - 2*y)*exp(-2*x/13 - 3*y/13))

classify_pde()

sympy.solvers.pde.classify_pde(eq, func=None, dict=False, **kwargs)

Returns a tuple of possible pdsolve() classifications for a PDE.
The tuple is ordered so that first item is the classification that pdsolve() uses to solve the
PDE by default. In general, classifications near the beginning of the list will produce bet-
ter solutions faster than those near the end, though there are always exceptions. To make
pdsolve use a different classification, use pdsolve(PDE, func, hint=<classification>). See
also the pdsolve() docstring for different meta-hints you can use.
If dict is true, classify_pde() will return a dictionary of hint:match expression terms.
This is intended for internal use by pdsolve(). Note that because dictionaries are ordered
arbitrarily, this will most likely not be in the same order as the tuple.
You can get help on different hints by doing help(pde.pde_hintname), where hintname is
the name of the hint without “_Integral”.
See sympy.pde.allhints or the sympy.pde docstring for a list of all supported hints that
can be returned from classify_pde.

1322 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.solvers.pde import classify_pde

>>> from sympy import Function, diff, Eq
>>> from sympy.abc import x, y
>>> f = Function('f')
>>> u = f(x, y)
>>> ux = u.diff(x)
>>> uy = u.diff(y)
>>> eq = Eq(1 + (2*(ux/u)) + (3*(uy/u)))
>>> classify_pde(eq)
('1st_linear_constant_coeff_homogeneous',)

checkpdesol()

sympy.solvers.pde.checkpdesol(pde, sol, func=None, solve_for_func=True)

Checks if the given solution satisfies the partial differential equation.
pde is the partial differential equation which can be given in the form of an equation or
an expression. sol is the solution for which the pde is to be checked. This can also be
given in an equation or an expression form. If the function is not provided, the helper
function _preprocess from deutils is used to identify the function.
If a sequence of solutions is passed, the same sort of container will be used to return the
result for each solution.
The following methods are currently being implemented to check if the solution satisfies
the PDE:
1. Directly substitute the solution in the PDE and check. If the solution hasn’t been
solved for f, then it will solve for f provided solve_for_func hasn’t been set to False.
If the solution satisfies the PDE, then a tuple (True, 0) is returned. Otherwise a tuple
(False, expr) where expr is the value obtained after substituting the solution in the PDE.
However if a known solution returns False, it may be due to the inability of doit() to
simplify it to zero.

Examples

>>> from sympy import Function, symbols, diff

>>> from sympy.solvers.pde import checkpdesol, pdsolve
>>> x, y = symbols('x y')
>>> f = Function('f')
>>> eq = 2*f(x,y) + 3*f(x,y).diff(x) + 4*f(x,y).diff(y)
>>> sol = pdsolve(eq)
>>> assert checkpdesol(eq, sol)[0]
>>> eq = x*f(x,y) + f(x,y).diff(x)
>>> checkpdesol(eq, sol)
(False, (x*F(4*x - 3*y) - 6*F(4*x - 3*y)/25 + 4*Subs(Derivative(F(_xi_1), _xi_1),␣
,→(_xi_1,), (4*x - 3*y,)))*exp(-6*x/25 - 8*y/25))

5.31. PDE 1323

SymPy Documentation, Release 1.3

5.31.2 Hint Methods

These functions are meant for internal use. However they contain useful information on the
various solving methods.

pde_1st_linear_constant_coeff_homogeneous

sympy.solvers.pde.pde_1st_linear_constant_coeff_homogeneous(eq, func, or-

der, match,
solvefun)
Solves a first order linear homogeneous partial differential equation with constant coef-
ficients.
The general form of this partial differential equation is

df (x, y) df (x, y)
a +b + cf (x, y) = 0
dx dy

where a, b and c are constants.

The general solution is of the form:
>>> from sympy.solvers import pdsolve
>>> from sympy.abc import x, y, a, b, c
>>> from sympy import Function, pprint
>>> f = Function('f')
>>> u = f(x,y)
>>> ux = u.diff(x)
>>> uy = u.diff(y)
>>> genform = a*ux + b*uy + c*u
>>> pprint(genform)
d d
a*--(f(x, y)) + b*--(f(x, y)) + c*f(x, y)
dx dy

>>> pprint(pdsolve(genform))
-c*(a*x + b*y)
---------------
2 2
a + b
f(x, y) = F(-a*y + b*x)*e

References

• Viktor Grigoryan, “Partial Differential Equations” Math 124A - Fall 2010, pp.7

Examples

>>> from sympy.solvers.pde import (

... pde_1st_linear_constant_coeff_homogeneous)
>>> from sympy import pdsolve
>>> from sympy import Function, diff, pprint
>>> from sympy.abc import x,y
(continues on next page)

1324 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> f = Function('f')
>>> pdsolve(f(x,y) + f(x,y).diff(x) + f(x,y).diff(y))
Eq(f(x, y), F(x - y)*exp(-x/2 - y/2))
>>> pprint(pdsolve(f(x,y) + f(x,y).diff(x) + f(x,y).diff(y)))
x y
- - - -
2 2
f(x, y) = F(x - y)*e

pde_1st_linear_constant_coeff

sympy.solvers.pde.pde_1st_linear_constant_coeff(eq, func, order, match, solve-

fun)
Solves a first order linear partial differential equation with constant coefficients.
The general form of this partial differential equation is
df (x, y) df (x, y)
a +b + cf (x, y) = G(x, y)
dx dy
where a, b and c are constants and G(x, y) can be an arbitrary function in x and y.
The general solution of the PDE is:
>>> from sympy.solvers import pdsolve
>>> from sympy.abc import x, y, a, b, c
>>> from sympy import Function, pprint
>>> f = Function('f')
>>> G = Function('G')
>>> u = f(x,y)
>>> ux = u.diff(x)
>>> uy = u.diff(y)
>>> genform = a*u + b*ux + c*uy - G(x,y)
>>> pprint(genform)
d d
a*f(x, y) + b*--(f(x, y)) + c*--(f(x, y)) - G(x, y)
dx dy
>>> pprint(pdsolve(genform, hint='1st_linear_constant_coeff_Integral'))
// b*x + c*y \
|| / |
|| | |
|| | a*xi |
|| | ------- |
|| | 2 2 |
|| | /b*xi + c*eta -b*eta + c*xi\ b + c |
|| | G|------------, -------------|*e d(xi)|
|| | | 2 2 2 2 | |
|| | \ b + c b + c / |
|| | |
|| / |
|| |
f(x, y) = ||F(eta) + -------------------------------------------------------|*
|| 2 2 |
\\ b + c /

\|
(continues on next page)

5.31. PDE 1325

SymPy Documentation, Release 1.3

(continued from previous page)

||
||
||
||
||
||
||
||
-a*xi ||
-------||
2 2||
b + c ||
e ||
||
/|eta=-b*y + c*x, xi=b*x + c*y

References

• Viktor Grigoryan, “Partial Differential Equations” Math 124A - Fall 2010, pp.7

Examples

>>> from sympy.solvers.pde import pdsolve

>>> from sympy import Function, diff, pprint, exp
>>> from sympy.abc import x,y
>>> f = Function('f')
>>> eq = -2*f(x,y).diff(x) + 4*f(x,y).diff(y) + 5*f(x,y) - exp(x + 3*y)
>>> pdsolve(eq)
Eq(f(x, y), (F(4*x + 2*y) + exp(x/2 + 4*y)/15)*exp(x/2 - y))

pde_1st_linear_variable_coeff

sympy.solvers.pde.pde_1st_linear_variable_coeff(eq, func, order, match, solve-

fun)
Solves a first order linear partial differential equation with variable coefficients. The
general form of this partial differential equation is
df (x, y) df (x, y)
a(x, y) + a(x, y) + c(x, y)f (x, y) − G(x, y)
dx dy
where a(x, y), b(x, y), c(x, y) and G(x, y) are arbitrary functions in x and y. This PDE is
converted into an ODE by making the following transformation.
1] ξ as x
2] η as the constant in the solution to the differential equation dy
dx = − ab
Making the following substitutions reduces it to the linear ODE
du
a(ξ, η) + c(ξ, η)u − d(ξ, η) = 0
dξ
which can be solved using dsolve.
The general form of this PDE is:

1326 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.solvers.pde import pdsolve

>>> from sympy.abc import x, y
>>> from sympy import Function, pprint
>>> a, b, c, G, f= [Function(i) for i in ['a', 'b', 'c', 'G', 'f']]
>>> u = f(x,y)
>>> ux = u.diff(x)
>>> uy = u.diff(y)
>>> genform = a(x, y)*u + b(x, y)*ux + c(x, y)*uy - G(x,y)
>>> pprint(genform)
d d
-G(x, y) + a(x, y)*f(x, y) + b(x, y)*--(f(x, y)) + c(x, y)*--(f(x, y))
dx dy

References

• Viktor Grigoryan, “Partial Differential Equations” Math 124A - Fall 2010, pp.7

Examples

>>> from sympy.solvers.pde import pdsolve

>>> from sympy import Function, diff, pprint, exp
>>> from sympy.abc import x,y
>>> f = Function('f')
>>> eq = x*(u.diff(x)) - y*(u.diff(y)) + y**2*u - y**2
>>> pdsolve(eq)
Eq(f(x, y), F(x*y)*exp(y**2/2) + 1)

5.31.3 Information on the pde module

This module contains pdsolve() and different helper functions that it uses. It is heavily inspired
by the ode module and hence the basic infrastructure remains the same.
Functions in this module
These are the user functions in this module:
• pdsolve() - Solves PDE’s
• classify_pde() - Classifies PDEs into possible hints for dsolve().
• pde_separate() - Separate variables in partial differential equation either by
additive or multiplicative separation approach.
These are the helper functions in this module:
• pde_separate_add() - Helper function for searching additive separable solu-
tions.
• pde_separate_mul() - Helper function for searching multiplicative
separable solutions.
Currently implemented solver methods
The following methods are implemented for solving partial differential equations. See the
docstrings of the various pde_hint() functions for more information on each (run help(pde)):

5.31. PDE 1327

SymPy Documentation, Release 1.3

• 1st order linear homogeneous partial differential equations with constant coefficients.
• 1st order linear general partial differential equations with constant coefficients.
• 1st order linear partial differential equations with variable coefficients.

5.32 Solvers

The solvers module in SymPy implements methods for solving equations.

Note: It is recommended to use solveset() (page 1375) to solve univariate equations,

sympy.solvers.solveset.linsolve() (page 1388) to solve system of linear equations in-
stead of solve() and sympy.solvers.solveset.nonlinsolve() (page 1390) to solve system
of non linear equations since sooner or later the solveset will take over solve either inter-
nally or externally.

5.32.1 Algebraic equations

Use solve() to solve algebraic equations. We suppose all equations are equaled to 0, so
solving x**2 == 1 translates into the following code:

>>> from sympy.solvers import solve

>>> from sympy import Symbol
>>> x = Symbol('x')
>>> solve(x**2 - 1, x)
[-1, 1]

The first argument for solve() is an equation (equaled to zero) and the second argument is
the symbol that we want to solve the equation for.
sympy.solvers.solvers.solve(f, *symbols, **flags)
Algebraically solves equations and systems of equations.
Currently supported are:
• polynomial,
• transcendental
• piecewise combinations of the above
• systems of linear and polynomial equations
• systems containing relational expressions.
Input is formed as:
• f
– a single Expr or Poly that must be zero,
– an Equality
– a Relational expression or boolean
– iterable of one or more of the above
• symbols (object(s) to solve for) specified as

1328 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

– none given (other non-numeric objects will be used)

– single symbol
– denested list of symbols e.g. solve(f, x, y)
– ordered iterable of symbols e.g. solve(f, [x, y])
• flags
‘dict’=True (default is False) return list (perhaps empty) of solution map-
pings
‘set’=True (default is False) return list of symbols and set of tuple(s) of solu-
tion(s)
‘exclude=[] (default)’ don’t try to solve for any of the free symbols in exclude;
if expressions are given, the free symbols in them will be extracted automat-
ically.
‘check=True (default)’ If False, don’t do any testing of solutions. This can be
useful if one wants to include solutions that make any denominator zero.
‘numerical=True (default)’ do a fast numerical check if f has only one sym-
bol.
‘minimal=True (default is False)’ a very fast, minimal testing.
‘warn=True (default is False)’ show a warning if checksol() could not con-
clude.
‘simplify=True (default)’ simplify all but polynomials of order 3 or greater be-
fore returning them and (if check is not False) use the general simplify func-
tion on the solutions and the expression obtained when they are substituted
into the function which should be zero
‘force=True (default is False)’ make positive all symbols without assump-
tions regarding sign.
‘rational=True (default)’ recast Floats as Rational; if this option is not used,
the system containing floats may fail to solve because of issues with polys.
If rational=None, Floats will be recast as rationals but the answer will be
recast as Floats. If the flag is False then nothing will be done to the Floats.
‘manual=True (default is False)’ do not use the polys/matrix method to solve
a system of equations, solve them one at a time as you might “manually”
‘implicit=True (default is False)’ allows solve to return a solution for a pat-
tern in terms of other functions that contain that pattern; this is only needed
if the pattern is inside of some invertible function like cos, exp, ….
‘particular=True (default is False)’ instructs solve to try to find a particular
solution to a linear system with as many zeros as possible; this is very expen-
sive
‘quick=True (default is False)’ when using particular=True, use a fast
heuristic instead to find a solution with many zeros (instead of using the very
slow method guaranteed to find the largest number of zeros possible)
‘cubics=True (default)’ return explicit solutions when cubic expressions are
encountered
‘quartics=True (default)’ return explicit solutions when quartic expressions
are encountered

5.32. Solvers 1329

SymPy Documentation, Release 1.3

‘quintics=True (default)’ return explicit solutions (if possible) when quintic

expressions are encountered

Notes

solve() with check=True (default) will run through the symbol tags to elimate unwanted
solutions. If no assumptions are included all possible solutions will be returned.
>>> from sympy import Symbol, solve
>>> x = Symbol(”x”)
>>> solve(x**2 - 1)
[-1, 1]

By using the positive tag only one solution will be returned:

>>> pos = Symbol(”pos”, positive=True)
>>> solve(pos**2 - 1)
[1]

Assumptions aren’t checked when solve() input involves relationals or bools.

When the solutions are checked, those that make any denominator zero are automatically
excluded. If you do not want to exclude such solutions then use the check=False option:
>>> from sympy import sin, limit
>>> solve(sin(x)/x) # 0 is excluded
[pi]

If check=False then a solution to the numerator being zero is found: x = 0. In this case,
this is a spurious solution since sin(x)/x has the well known limit (without dicontinuity)
of 1 at x = 0:
>>> solve(sin(x)/x, check=False)
[0, pi]

In the following case, however, the limit exists and is equal to the value of x = 0 that is
excluded when check=True:
>>> eq = x**2*(1/x - z**2/x)
>>> solve(eq, x)
[]
>>> solve(eq, x, check=False)
[0]
>>> limit(eq, x, 0, '-')
0
>>> limit(eq, x, 0, '+')
0

Examples

The output varies according to the input and can be seen by example:
>>> from sympy import solve, Poly, Eq, Function, exp
>>> from sympy.abc import x, y, z, a, b
>>> f = Function('f')

1330 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• boolean or univariate Relational

>>> solve(x < 3)

(-oo < x) & (x < 3)

• to always get a list of solution mappings, use flag dict=True

>>> solve(x - 3, dict=True)

[{x: 3}]
>>> sol = solve([x - 3, y - 1], dict=True)
>>> sol
[{x: 3, y: 1}]
>>> sol[0][x]
3
>>> sol[0][y]
1

• to get a list of symbols and set of solution(s) use flag set=True

>>> solve([x**2 - 3, y - 1], set=True)

([x, y], {(-sqrt(3), 1), (sqrt(3), 1)})

• single expression and single symbol that is in the expression

>>> solve(x - y, x)
[y]
>>> solve(x - 3, x)
[3]
>>> solve(Eq(x, 3), x)
[3]
>>> solve(Poly(x - 3), x)
[3]
>>> solve(x**2 - y**2, x, set=True)
([x], {(-y,), (y,)})
>>> solve(x**4 - 1, x, set=True)
([x], {(-1,), (1,), (-I,), (I,)})

• single expression with no symbol that is in the expression

>>> solve(3, x)
[]
>>> solve(x - 3, y)
[]

• single expression with no symbol given

In this case, all free symbols will be selected as potential symbols to solve
for. If the equation is univariate then a list of solutions is returned; otherwise
– as is the case when symbols are given as an iterable of length > 1 – a list
of mappings will be returned.

>>> solve(x - 3)
[3]
>>> solve(x**2 - y**2)
[{x: -y}, {x: y}]
>>> solve(z**2*x**2 - z**2*y**2)
[{x: -y}, {x: y}, {z: 0}]
(continues on next page)

5.32. Solvers 1331

SymPy Documentation, Release 1.3

(continued from previous page)

>>> solve(z**2*x - z**2*y**2)
[{x: y**2}, {z: 0}]

• when an object other than a Symbol is given as a symbol, it is isolated algebraically

and an implicit solution may be obtained. This is mostly provided as a convenience
to save one from replacing the object with a Symbol and solving for that Symbol. It
will only work if the specified object can be replaced with a Symbol using the subs
method.
>>> solve(f(x) - x, f(x))
[x]
>>> solve(f(x).diff(x) - f(x) - x, f(x).diff(x))
[x + f(x)]
>>> solve(f(x).diff(x) - f(x) - x, f(x))
[-x + Derivative(f(x), x)]
>>> solve(x + exp(x)**2, exp(x), set=True)
([exp(x)], {(-sqrt(-x),), (sqrt(-x),)})

>>> from sympy import Indexed, IndexedBase, Tuple, sqrt

>>> A = IndexedBase('A')
>>> eqs = Tuple(A[1] + A[2] - 3, A[1] - A[2] + 1)
>>> solve(eqs, eqs.atoms(Indexed))
{A[1]: 1, A[2]: 2}

– To solve for a symbol implicitly, use ‘implicit=True’:

>>> solve(x + exp(x), x)
[-LambertW(1)]
>>> solve(x + exp(x), x, implicit=True)
[-exp(x)]

– It is possible to solve for anything that can be targeted with subs:

>>> solve(x + 2 + sqrt(3), x + 2)
[-sqrt(3)]
>>> solve((x + 2 + sqrt(3), x + 4 + y), y, x + 2)
{y: -2 + sqrt(3), x + 2: -sqrt(3)}

– Nothing heroic is done in this implicit solving so you may end up with a
symbol still in the solution:
>>> eqs = (x*y + 3*y + sqrt(3), x + 4 + y)
>>> solve(eqs, y, x + 2)
{y: -sqrt(3)/(x + 3), x + 2: (-2*x - 6 + sqrt(3))/(x + 3)}
>>> solve(eqs, y*x, x)
{x: -y - 4, x*y: -3*y - sqrt(3)}

– if you attempt to solve for a number remember that the number you have
obtained does not necessarily mean that the value is equivalent to the
expression obtained:
>>> solve(sqrt(2) - 1, 1)
[sqrt(2)]
>>> solve(x - y + 1, 1) # /!\ -1 is targeted, too
[x/(y - 1)]
(continues on next page)

1332 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> [_.subs(z, -1) for _ in solve((x - y + 1).subs(-1, z), 1)]
[-x + y]

– To solve for a function within a derivative, use dsolve.

• single expression and more than 1 symbol

– when there is a linear solution

>>> solve(x - y**2, x, y)

[(y**2, y)]
>>> solve(x**2 - y, x, y)
[(x, x**2)]
>>> solve(x**2 - y, x, y, dict=True)
[{y: x**2}]

– when undetermined coefficients are identified

∗ that are linear

>>> solve((a + b)*x - b + 2, a, b)

{a: -2, b: 2}

∗ that are nonlinear

>>> solve((a + b)*x - b**2 + 2, a, b, set=True)

([a, b], {(-sqrt(2), sqrt(2)), (sqrt(2), -sqrt(2))})

– if there is no linear solution then the first successful attempt for a nonlinear
solution will be returned

>>> solve(x**2 - y**2, x, y, dict=True)

[{x: -y}, {x: y}]
>>> solve(x**2 - y**2/exp(x), x, y, dict=True)
[{x: 2*LambertW(y/2)}]
>>> solve(x**2 - y**2/exp(x), y, x)
[(-x*sqrt(exp(x)), x), (x*sqrt(exp(x)), x)]

• iterable of one or more of the above

– involving relationals or bools

>>> solve([x < 3, x - 2])

Eq(x, 2)
>>> solve([x > 3, x - 2])
False

– when the system is linear

∗ with a solution

>>> solve([x - 3], x)

{x: 3}
>>> solve((x + 5*y - 2, -3*x + 6*y - 15), x, y)
{x: -3, y: 1}
>>> solve((x + 5*y - 2, -3*x + 6*y - 15), x, y, z)
{x: -3, y: 1}
(continues on next page)

5.32. Solvers 1333

SymPy Documentation, Release 1.3

(continued from previous page)

>>> solve((x + 5*y - 2, -3*x + 6*y - z), z, x, y)
{x: -5*y + 2, z: 21*y - 6}

∗ without a solution

>>> solve([x + 3, x - 3])

[]

– when the system is not linear

>>> solve([x**2 + y -2, y**2 - 4], x, y, set=True)

([x, y], {(-2, -2), (0, 2), (2, -2)})

– if no symbols are given, all free symbols will be selected and a list of mappings
returned

>>> solve([x - 2, x**2 + y])

[{x: 2, y: -4}]
>>> solve([x - 2, x**2 + f(x)], {f(x), x})
[{x: 2, f(x): -4}]

– if any equation doesn’t depend on the symbol(s) given it will be eliminated from
the equation set and an answer may be given implicitly in terms of variables that
were not of interest

>>> solve([x - y, y - 3], x)

{x: y}

Disabling High-order, Explicit Solutions

When solving polynomial expressions, one might not want explicit solutions (which can
be quite long). If the expression is univariate, CRootOf instances will be returned in-
stead:

>>> solve(x**3 - x + 1)
[-1/((-1/2 - sqrt(3)*I/2)*(3*sqrt(69)/2 + 27/2)**(1/3)) - (-1/2 -
sqrt(3)*I/2)*(3*sqrt(69)/2 + 27/2)**(1/3)/3, -(-1/2 +
sqrt(3)*I/2)*(3*sqrt(69)/2 + 27/2)**(1/3)/3 - 1/((-1/2 +
sqrt(3)*I/2)*(3*sqrt(69)/2 + 27/2)**(1/3)), -(3*sqrt(69)/2 +
27/2)**(1/3)/3 - 1/(3*sqrt(69)/2 + 27/2)**(1/3)]
>>> solve(x**3 - x + 1, cubics=False)
[CRootOf(x**3 - x + 1, 0),
CRootOf(x**3 - x + 1, 1),
CRootOf(x**3 - x + 1, 2)]

If the expression is multivariate, no solution might be returned:

>>> solve(x**3 - x + a, x, cubics=False)

[]

Sometimes solutions will be obtained even when a flag is False because the expression
could be factored. In the following example, the equation can be factored as the product
of a linear and a quadratic factor so explicit solutions (which did not require solving a
cubic expression) are obtained:

1334 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> eq = x**3 + 3*x**2 + x - 1

>>> solve(eq, cubics=False)
[-1, -1 + sqrt(2), -sqrt(2) - 1]

Solving Equations Involving Radicals

Because of SymPy’s use of the principle root (issue #8789), some solutions to radical
equations will be missed unless check=False:

>>> from sympy import root

>>> eq = root(x**3 - 3*x**2, 3) + 1 - x
>>> solve(eq)
[]
>>> solve(eq, check=False)
[1/3]

In the above example there is only a single solution to the equation. Other expressions
will yield spurious roots which must be checked manually; roots which give a negative
argument to odd-powered radicals will also need special checking:

>>> from sympy import real_root, S

>>> eq = root(x, 3) - root(x, 5) + S(1)/7
>>> solve(eq) # this gives 2 solutions but misses a 3rd
[CRootOf(7*_p**5 - 7*_p**3 + 1, 1)**15,
CRootOf(7*_p**5 - 7*_p**3 + 1, 2)**15]
>>> sol = solve(eq, check=False)
>>> [abs(eq.subs(x,i).n(2)) for i in sol]
[0.48, 0.e-110, 0.e-110, 0.052, 0.052]

The first solution is negative so real_root must be used to see that it satisfies
the expression:

>>> abs(real_root(eq.subs(x, sol[0])).n(2))

0.e-110

If the roots of the equation are not real then more care will be necessary to find the roots,
especially for higher order equations. Consider the following expression:

>>> expr = root(x, 3) - root(x, 5)

We will construct a known value for this expression at x = 3 by selecting the 1-th root
for each radical:

>>> expr1 = root(x, 3, 1) - root(x, 5, 1)

>>> v = expr1.subs(x, -3)

The solve function is unable to find any exact roots to this equation:

>>> eq = Eq(expr, v); eq1 = Eq(expr1, v)

>>> solve(eq, check=False), solve(eq1, check=False)
([], [])

The function unrad, however, can be used to get a form of the equation for which nu-
merical roots can be found:

5.32. Solvers 1335

SymPy Documentation, Release 1.3

>>> from sympy.solvers.solvers import unrad

>>> from sympy import nroots
>>> e, (p, cov) = unrad(eq)
>>> pvals = nroots(e)
>>> inversion = solve(cov, x)[0]
>>> xvals = [inversion.subs(p, i) for i in pvals]

Although eq or eq1 could have been used to find xvals, the solution can only be verified
with expr1:
>>> z = expr - v
>>> [xi.n(chop=1e-9) for xi in xvals if abs(z.subs(x, xi).n()) < 1e-9]
[]
>>> z1 = expr1 - v
>>> [xi.n(chop=1e-9) for xi in xvals if abs(z1.subs(x, xi).n()) < 1e-9]
[-3.0]

sympy.solvers.solvers.solve_linear(lhs, rhs=0, symbols=[], exclude=[])

Return a tuple derived from f = lhs - rhs that is one of the following:
(0, 1) meaning that f is independent of the symbols in symbols that aren’t in
exclude, e.g:
>>> from sympy.solvers.solvers import solve_linear
>>> from sympy.abc import x, y, z
>>> from sympy import cos, sin
>>> eq = y*cos(x)**2 + y*sin(x)**2 - y # = y*(1 - 1) = 0
>>> solve_linear(eq)
(0, 1)
>>> eq = cos(x)**2 + sin(x)**2 # = 1
>>> solve_linear(eq)
(0, 1)
>>> solve_linear(x, exclude=[x])
(0, 1)

(0, 0) meaning that there is no solution to the equation amongst the symbols
given.
(If the first element of the tuple is not zero then the function is guaran-
teed to be dependent on a symbol in symbols.)
(symbol, solution) where symbol appears linearly in the numerator of f, is in
symbols (if given) and is not in exclude (if given). No simplification is done to
f other than a mul=True expansion, so the solution will correspond strictly to a
unique solution.
(n, d) where n and d are the numerator and denominator of f when the nu-
merator was not linear in any symbol of interest; n will never be a symbol unless
a solution for that symbol was found (in which case the second element is the
solution, not the denominator).

Examples

>>> from sympy.core.power import Pow

>>> from sympy.polys.polytools import cancel

The variable x appears as a linear variable in each of the following:

1336 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> solve_linear(x + y**2)

(x, -y**2)
>>> solve_linear(1/x - y**2)
(x, y**(-2))

When not linear in x or y then the numerator and denominator are returned.

>>> solve_linear(x**2/y**2 - 3)
(x**2 - 3*y**2, y**2)

If the numerator of the expression is a symbol then (0, 0) is returned if the solution for
that symbol would have set any denominator to 0:

>>> eq = 1/(1/x - 2)
>>> eq.as_numer_denom()
(x, -2*x + 1)
>>> solve_linear(eq)
(0, 0)

But automatic rewriting may cause a symbol in the denominator to appear in the numer-
ator so a solution will be returned:

>>> (1/x)**-1
x
>>> solve_linear((1/x)**-1)
(x, 0)

Use an unevaluated expression to avoid this:

>>> solve_linear(Pow(1/x, -1, evaluate=False))

(0, 0)

If x is allowed to cancel in the following expression, then it appears to be linear in x, but

this sort of cancellation is not done by solve_linear so the solution will always satisfy
the original expression without causing a division by zero error.

>>> eq = x**2*(1/x - z**2/x)

>>> solve_linear(cancel(eq))
(x, 0)
>>> solve_linear(eq)
(x**2*(-z**2 + 1), x)

A list of symbols for which a solution is desired may be given:

>>> solve_linear(x + y + z, symbols=[y])

(y, -x - z)

A list of symbols to ignore may also be given:

>>> solve_linear(x + y + z, exclude=[x])

(y, -x - z)

(A solution for y is obtained because it is the first variable from the canonically sorted
list of symbols that had a linear solution.)
sympy.solvers.solvers.solve_linear_system(system, *symbols, **flags)
Solve system of N linear equations with M variables, which means both under- and

5.32. Solvers 1337

SymPy Documentation, Release 1.3

overdetermined systems are supported. The possible number of solutions is zero, one
or infinite. Respectively, this procedure will return None or a dictionary with solutions.
In the case of underdetermined systems, all arbitrary parameters are skipped. This may
cause a situation in which an empty dictionary is returned. In that case, all symbols can
be assigned arbitrary values.
Input to this functions is a Nx(M+1) matrix, which means it has to be in augmented
form. If you prefer to enter N equations and M unknowns then use solve(N eqs, ∗M symbols)
instead. Note: a local copy of the matrix is made by this routine so the matrix that is
passed will not be modified.
The algorithm used here is fraction-free Gaussian elimination, which results, after elimi-
nation, in an upper-triangular matrix. Then solutions are found using back-substitution.
This approach is more efficient and compact than the Gauss-Jordan method.

>>> from sympy import Matrix, solve_linear_system

>>> from sympy.abc import x, y

Solve the following system:

x + 4 y == 2
-2 x + y == 14

>>> system = Matrix(( (1, 4, 2), (-2, 1, 14)))

>>> solve_linear_system(system, x, y)
{x: -6, y: 2}

A degenerate system returns an empty dictionary.

>>> system = Matrix(( (0,0,0), (0,0,0) ))

>>> solve_linear_system(system, x, y)
{}

sympy.solvers.solvers.solve_linear_system_LU(matrix, syms)
Solves the augmented matrix system using LUsolve and returns a dictionary in which
solutions are keyed to the symbols of syms as ordered.
The matrix must be invertible.
See also:
sympy.matrices.LUsolve

Examples

>>> from sympy import Matrix

>>> from sympy.abc import x, y, z
>>> from sympy.solvers.solvers import solve_linear_system_LU

>>> solve_linear_system_LU(Matrix([
... [1, 2, 0, 1],
... [3, 2, 2, 1],
... [2, 0, 0, 1]]), [x, y, z])
{x: 1/2, y: 1/4, z: -1/2}

1338 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.solvers.solvers.solve_undetermined_coeffs(equ, coeffs, sym, **flags)

Solve equation of a type p(x; a_1, …, a_k) == q(x) where both p, q are univariate poly-
nomials and f depends on k parameters. The result of this functions is a dictionary with
symbolic values of those parameters with respect to coefficients in q.
This functions accepts both Equations class instances and ordinary SymPy expressions.
Specification of parameters and variable is obligatory for efficiency and simplicity rea-
son.

>>> from sympy import Eq

>>> from sympy.abc import a, b, c, x
>>> from sympy.solvers import solve_undetermined_coeffs

>>> solve_undetermined_coeffs(Eq(2*a*x + a+b, x), [a, b], x)

{a: 1/2, b: -1/2}

>>> solve_undetermined_coeffs(Eq(a*c*x + a+b, x), [a, b], x)

{a: 1/c, b: -1/c}

sympy.solvers.solvers.nsolve(*args, **kwargs)
Solve a nonlinear equation system numerically:

nsolve(f, [args,] x0, modules=['mpmath'], **kwargs)

f is a vector function of symbolic expressions representing the system. args are the
variables. If there is only one variable, this argument can be omitted. x0 is a starting
vector close to a solution.
Use the modules keyword to specify which modules should be used to evaluate the func-
tion and the Jacobian matrix. Make sure to use a module that supports matrices. For
more information on the syntax, please see the docstring of lambdify.
If the keyword arguments contain ‘dict’=True (default is False) nsolve will return a list
(perhaps empty) of solution mappings. This might be especially useful if you want to use
nsolve as a fallback to solve since using the dict argument for both methods produces
return values of consistent type structure. Please note: to keep this consistency with
solve, the solution will be returned in a list even though nsolve (currently at least) only
finds one solution at a time.
Overdetermined systems are supported.

>>> from sympy import Symbol, nsolve

>>> import sympy
>>> import mpmath
>>> mpmath.mp.dps = 15
>>> x1 = Symbol('x1')
>>> x2 = Symbol('x2')
>>> f1 = 3 * x1**2 - 2 * x2**2 - 1
>>> f2 = x1**2 - 2 * x1 + x2**2 + 2 * x2 - 8
>>> print(nsolve((f1, f2), (x1, x2), (-1, 1)))
Matrix([[-1.19287309935246], [1.27844411169911]])

For one-dimensional functions the syntax is simplified:

>>> from sympy import sin, nsolve

>>> from sympy.abc import x
>>> nsolve(sin(x), x, 2)
(continues on next page)

5.32. Solvers 1339

SymPy Documentation, Release 1.3

(continued from previous page)

3.14159265358979
>>> nsolve(sin(x), 2)
3.14159265358979

To solve with higher precision than the default, use the prec argument.
>>> from sympy import cos
>>> nsolve(cos(x) - x, 1)
0.739085133215161
>>> nsolve(cos(x) - x, 1, prec=50)
0.73908513321516064165531208767387340401341175890076
>>> cos(_)
0.73908513321516064165531208767387340401341175890076

To solve for complex roots of real functions, a nonreal initial point must be specified:
>>> from sympy import I
>>> nsolve(x**2 + 2, I)
1.4142135623731*I

mpmath.findroot is used and you can find there more extensive documentation, espe-
cially concerning keyword parameters and available solvers. Note, however, that func-
tions which are very steep near the root the verification of the solution may fail. In this
case you should use the flag verif y = F alse and independently verify the solution.
>>> from sympy import cos, cosh
>>> from sympy.abc import i
>>> f = cos(x)*cosh(x) - 1
>>> nsolve(f, 3.14*100)
Traceback (most recent call last):
...
ValueError: Could not find root within given tolerance. (1.39267e+230 > 2.1684e-
,→19)

>>> ans = nsolve(f, 3.14*100, verify=False); ans

312.588469032184
>>> f.subs(x, ans).n(2)
2.1e+121
>>> (f/f.diff(x)).subs(x, ans).n(2)
7.4e-15

One might safely skip the verification if bounds of the root are known and a bisection
method is used:
>>> bounds = lambda i: (3.14*i, 3.14*(i + 1))
>>> nsolve(f, bounds(100), solver='bisect', verify=False)
315.730061685774

Alternatively, a function may be better behaved when the denominator is ignored. Since
this is not always the case, however, the decision of what function to use is left to the
discretion of the user.
>>> eq = x**2/(1 - x)/(1 - 2*x)**2 - 100
>>> nsolve(eq, 0.46)
Traceback (most recent call last):
...
ValueError: Could not find root within given tolerance. (10000 > 2.1684e-19)
(continues on next page)

1340 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Try another starting point or tweak arguments.
>>> nsolve(eq.as_numer_denom()[0], 0.46)
0.46792545969349058

sympy.solvers.solvers.check_assumptions(expr, against=None, **assumptions)

Checks whether expression expr satisfies all assumptions.
assumptions is a dict of assumptions: {‘assumption’: True|False, …}.
See also:
failing_assumptions

Examples

>>> from sympy import Symbol, pi, I, exp, check_assumptions

>>> check_assumptions(-5, integer=True)

True
>>> check_assumptions(pi, real=True, integer=False)
True
>>> check_assumptions(pi, real=True, negative=True)
False
>>> check_assumptions(exp(I*pi/7), real=False)
True

>>> x = Symbol('x', real=True, positive=True)

>>> check_assumptions(2*x + 1, real=True, positive=True)
True
>>> check_assumptions(-2*x - 5, real=True, positive=True)
False

To check assumptions of expr against another variable or expression, pass the expres-
sion or variable as against.

>>> check_assumptions(2*x + 1, x)
True

N one is returned if check_assumptions() could not conclude.

>>> check_assumptions(2*x - 1, real=True, positive=True)

>>> z = Symbol('z')
>>> check_assumptions(z, real=True)

sympy.solvers.solvers.checksol(f, symbol, sol=None, **flags)

Checks whether sol is a solution of equation f == 0.
Input can be either a single symbol and corresponding value or a dictionary of symbols
and values. When given as a dictionary and flag simplify=True, the values in the dictio-
nary will be simplified. f can be a single equation or an iterable of equations. A solution
must satisfy all equations in f to be considered valid; if a solution does not satisfy any
equation, False is returned; if one or more checks are inconclusive (and none are False)
then None is returned.

5.32. Solvers 1341

SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> from sympy.solvers import checksol
>>> x, y = symbols('x,y')
>>> checksol(x**4 - 1, x, 1)
True
>>> checksol(x**4 - 1, x, 0)
False
>>> checksol(x**2 + y**2 - 5**2, {x: 3, y: 4})
True

To check if an expression is zero using checksol, pass it as f and send an empty dictionary
for symbol:

>>> checksol(x**2 + x - x*(x + 1), {})

True

None is returned if checksol() could not conclude.

flags:
‘numerical=True (default)’ do a fast numerical check if f has only one symbol.
‘minimal=True (default is False)’ a very fast, minimal testing.
‘warn=True (default is False)’ show a warning if checksol() could not conclude.
‘simplify=True (default)’ simplify solution before substituting into function and
simplify the function before trying specific simplifications
‘force=True (default is False)’ make positive all symbols without assumptions re-
garding sign.

5.32.2 Ordinary Differential equations (ODEs)

See ODE (page 1262).

5.32.3 Partial Differential Equations (PDEs)

See PDE (page 1319).

5.32.4 Deutils (Utilities for solving ODE’s and PDE’s)

sympy.solvers.deutils.ode_order(expr, func)
Returns the order of a given differential equation with respect to func.
This function is implemented recursively.

Examples

1342 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Function

>>> from sympy.solvers.deutils import ode_order
>>> from sympy.abc import x
>>> f, g = map(Function, ['f', 'g'])
>>> ode_order(f(x).diff(x, 2) + f(x).diff(x)**2 +
... f(x).diff(x), f(x))
2
>>> ode_order(f(x).diff(x, 2) + g(x).diff(x, 3), f(x))
2
>>> ode_order(f(x).diff(x, 2) + g(x).diff(x, 3), g(x))
3

5.32.5 Recurrence Equations

sympy.solvers.recurr.rsolve(f, y, init=None)
Solve univariate recurrence with rational coefficients.
Given k-th order linear recurrence L y = f , or equivalently:

ak (n)y(n + k) + ak−1 (n)y(n + k − 1) + · · · + a0 (n)y(n) = f (n)

where ai (n), for i = 0, . . . , k, are polynomials or rational functions in n, and f is a hyperge-

ometric function or a sum of a fixed number of pairwise dissimilar hypergeometric terms
in n, finds all solutions or returns None, if none were found.
Initial conditions can be given as a dictionary in two forms:
(1) { n_0 : v_0, n_1 : v_1, ..., n_m : v_m}
(2) {y(n_0) : v_0, y(n_1) : v_1, ..., y(n_m) : v_m}
or as a list L of values:
L = [v_0, v_1, ..., v_m]
where L[i] = v_i, for i = 0, . . . , m, maps to y(ni ).
See also:
rsolve_poly (page 1344), rsolve_ratio (page 1344), rsolve_hyper (page 1345)

Examples

Lets consider the following recurrence:

(n − 1)y(n + 2) − (n2 + 3n − 2)y(n + 1) + 2n(n + 1)y(n) = 0

>>> from sympy import Function, rsolve

>>> from sympy.abc import n
>>> y = Function('y')

>>> f = (n - 1)*y(n + 2) - (n**2 + 3*n - 2)*y(n + 1) + 2*n*(n + 1)*y(n)

>>> rsolve(f, y(n))

2**n*C0 + C1*factorial(n)

5.32. Solvers 1343

SymPy Documentation, Release 1.3

>>> rsolve(f, y(n), {y(0):0, y(1):3})

3*2**n - 3*factorial(n)

sympy.solvers.recurr.rsolve_poly(coeffs, f, n, **hints)
Given linear recurrence operator L of order k with polynomial coefficients and inhomo-
geneous equation L y = f , where f is a polynomial, we seek for all polynomial solutions
over field K of characteristic zero.
The algorithm performs two basic steps:
(1) Compute degree N of the general polynomial solution.
(2) Find all polynomials of degree N or less of L y = f .
There are two methods for computing the polynomial solutions. If the degree bound
is relatively small, i.e. it’s smaller than or equal to the order of the recurrence, then
naive method of undetermined coefficients is being used. This gives system of algebraic
equations with N + 1 unknowns.
In the other case, the algorithm performs transformation of the initial equation to an
equivalent one, for which the system of algebraic equations has only r indeterminates.
This method is quite sophisticated (in comparison with the naive one) and was invented
together by Abramov, Bronstein and Petkovsek.
It is possible to generalize the algorithm implemented here to the case of linear q-
difference and differential equations.
Lets say that we would like to compute m-th Bernoulli polynomial up to a constant. For
this we can use b(n + 1) − b(n) = mnm−1 recurrence, which has solution b(n) = Bm + C. For
example:

>>> from sympy import Symbol, rsolve_poly

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

>>> rsolve_poly([-1, 1], 4*n**3, n)

C0 + n**4 - 2*n**3 + n**2

References

[R532], [R533], [R534]

sympy.solvers.recurr.rsolve_ratio(coeffs, f, n, **hints)
Given linear recurrence operator L of order k with polynomial coefficients and inhomo-
geneous equation L y = f , where f is a polynomial, we seek for all rational solutions over
field K of characteristic zero.
This procedure accepts only polynomials, however if you are interested in solving re-
currence with rational coefficients then use rsolve which will pre-process the given
equation and run this procedure with polynomial arguments.
The algorithm performs two basic steps:
(1) Compute polynomial v(n) which can be used as universal denominator of any rational
solution of equation L y = f .
(2) Construct new linear difference equation by substitution y(n) = u(n)/v(n) and solve
it for u(n) finding all its polynomial solutions. Return None if none were found.

1344 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Algorithm implemented here is a revised version of the original Abramov’s algorithm,

developed in 1989. The new approach is much simpler to implement and has better
overall efficiency. This method can be easily adapted to q-difference equations case.
Besides finding rational solutions alone, this functions is an important part of Hyper al-
gorithm were it is used to find particular solution of inhomogeneous part of a recurrence.
See also:
rsolve_hyper (page 1345)

References

[R535]

Examples

>>> from sympy.abc import x

>>> from sympy.solvers.recurr import rsolve_ratio
>>> rsolve_ratio([-2*x**3 + x**2 + 2*x - 1, 2*x**3 + x**2 - 6*x,
... - 2*x**3 - 11*x**2 - 18*x - 9, 2*x**3 + 13*x**2 + 22*x + 8], 0, x)
C2*(2*x - 3)/(2*(x**2 - 1))

sympy.solvers.recurr.rsolve_hyper(coeffs, f, n, **hints)
Given linear recurrence operator L of order k with polynomial coefficients and inho-
mogeneous equation L y = f we seek for all hypergeometric solutions over field K of
characteristic zero.
The inhomogeneous part can be either hypergeometric or a sum of a fixed number of
pairwise dissimilar hypergeometric terms.
The algorithm performs three basic steps:
(1) Group together similar hypergeometric terms in the inhomogeneous part of L y = f ,
and find particular solution using Abramov’s algorithm.
(2) Compute generating set of L and find basis in it, so that all solutions are linearly
independent.
(3) Form final solution with the number of arbitrary constants equal to dimension of
basis of L.
Term a(n) is hypergeometric if it is annihilated by first order linear difference equations
with polynomial coefficients or, in simpler words, if consecutive term ratio is a rational
function.
The output of this procedure is a linear combination of fixed number of hypergeomet-
ric terms. However the underlying method can generate larger class of solutions -
D’Alembertian terms.
Note also that this method not only computes the kernel of the inhomogeneous equation,
but also reduces in to a basis so that solutions generated by this procedure are linearly
independent

References

[R536], [R537]

5.32. Solvers 1345

SymPy Documentation, Release 1.3

Examples

>>> from sympy.solvers import rsolve_hyper

>>> from sympy.abc import x

>>> rsolve_hyper([-1, -1, 1], 0, x)

C0*(1/2 + sqrt(5)/2)**x + C1*(-sqrt(5)/2 + 1/2)**x

>>> rsolve_hyper([-1, 1], 1 + x, x)

C0 + x*(x + 1)/2

5.32.6 Systems of Polynomial Equations

sympy.solvers.polysys.solve_poly_system(seq, *gens, **args)

Solve a system of polynomial equations.

Examples

>>> from sympy import solve_poly_system

>>> from sympy.abc import x, y

>>> solve_poly_system([x*y - 2*y, 2*y**2 - x**2], x, y)

[(0, 0), (2, -sqrt(2)), (2, sqrt(2))]

sympy.solvers.polysys.solve_triangulated(polys, *gens, **args)

Solve a polynomial system using Gianni-Kalkbrenner algorithm.
The algorithm proceeds by computing one Groebner basis in the ground domain and
then by iteratively computing polynomial factorizations in appropriately constructed al-
gebraic extensions of the ground domain.

References

1. Patrizia Gianni, Teo Mora, Algebraic Solution of System of Polynomial Equations

using Groebner Bases, AAECC-5 on Applied Algebra, Algebraic Algorithms and Error-
Correcting Codes, LNCS 356 247–257, 1989

Examples

>>> from sympy.solvers.polysys import solve_triangulated

>>> from sympy.abc import x, y, z

>>> F = [x**2 + y + z - 1, x + y**2 + z - 1, x + y + z**2 - 1]

>>> solve_triangulated(F, x, y, z)
[(0, 0, 1), (0, 1, 0), (1, 0, 0)]

1346 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.32.7 Diophantine Equations (DEs)

See Diophantine (page 1347)

5.32.8 Inequalities

See Inequality Solvers (page 1372)

5.33 Diophantine

5.33.1 Diophantine equations

The word “Diophantine” comes with the name Diophantus, a mathematician lived in the great
city of Alexandria sometime around 250 AD. Often referred to as the “father of Algebra”, Dio-
phantus in his famous work “Arithmetica” presented 150 problems that marked the early
beginnings of number theory, the field of study about integers and their properties. Diophan-
tine equations play a central and an important part in number theory.
We call a “Diophantine equation” to an equation of the form, f (x1 , x2 , . . . xn ) = 0 where n ≥ 2 and
x1 , x2 , . . . xn are integer variables. If we can find n integers a1 , a2 , . . . an such that x1 = a1 , x2 =
a2 , . . . xn = an satisfies the above equation, we say that the equation is solvable. You can read
more about Diophantine equations in1 and2 .
Currently, following five types of Diophantine equations can be solved using diophantine()
(page 1352) and other helper functions of the Diophantine module.
• Linear Diophantine equations: a1 x1 + a2 x2 + . . . + an xn = b.
• General binary quadratic equation: ax2 + bxy + cy 2 + dx + ey + f = 0
• Homogeneous ternary quadratic equation: ax2 + by 2 + cz 2 + dxy + eyz + f zx = 0
• Extended Pythagorean equation: a1 x21 + a2 x22 + . . . + an x2n = an+1 x2n+1
• General sum of squares: x21 + x22 + . . . + x2n = k

5.33.2 Module structure

This module contains diophantine() (page 1352) and helper functions that are needed to
solve certain Diophantine equations. It’s structured in the following manner.
• diophantine() (page 1352)
– diop_solve() (page 1354)
∗ classify_diop() (page 1353)
∗ diop_linear() (page 1354)
∗ diop_quadratic() (page 1356)
∗ diop_ternary_quadratic() (page 1360)
1 Andreescu, Titu. Andrica, Dorin. Cucurezeanu, Ion. An Introduction to Diophantine Equations
2 Diophantine Equation, Wolfram Mathworld, [online]. Available: http://mathworld.wolfram.com/
DiophantineEquation.html

5.33. Diophantine 1347

SymPy Documentation, Release 1.3

∗ diop_ternary_quadratic_normal() (page 1369)

∗ diop_general_pythagorean() (page 1362)
∗ diop_general_sum_of_squares() (page 1362)
∗ diop_general_sum_of_even_powers() (page 1363)
– merge_solution() (page 1367)
When an equation is given to diophantine() (page 1352), it factors the equation(if possible)
and solves the equation given by each factor by calling diop_solve() (page 1354) separately.
Then all the results are combined using merge_solution() (page 1367).
diop_solve() (page 1354) internally uses classify_diop() (page 1353) to find the type of
the equation(and some other details) given to it and then calls the appropriate solver function
based on the type returned. For example, if classify_diop() (page 1353) returned “linear”
as the type of the equation, then diop_solve() (page 1354) calls diop_linear() (page 1354)
to solve the equation.
Each of the functions, diop_linear() (page 1354), diop_quadratic() (page 1356),
diop_ternary_quadratic() (page 1360), diop_general_pythagorean() (page 1362) and
diop_general_sum_of_squares() (page 1362) solves a specific type of equations and the
type can be easily guessed by it’s name.
Apart from these functions, there are a considerable number of other functions in the “Dio-
phantine Module” and all of them are listed under User functions and Internal functions.

5.33.3 Tutorial

First, let’s import the highest API of the Diophantine module.

>>> from sympy.solvers.diophantine import diophantine

Before we start solving the equations, we need to define the variables.

>>> from sympy import symbols

>>> x, y, z = symbols(”x, y, z”, integer=True)

Let’s start by solving the easiest type of Diophantine equations, i.e. linear Diophantine equa-
tions. Let’s solve 2x + 3y = 5. Note that although we write the equation in the above form,
when we input the equation to any of the functions in Diophantine module, it needs to be in
the form eq = 0.

>>> diophantine(2*x + 3*y - 5)

{(3*t_0 - 5, -2*t_0 + 5)}

Note that stepping one more level below the highest API, we can solve the very same equation
by calling diop_solve() (page 1354).

>>> from sympy.solvers.diophantine import diop_solve

>>> diop_solve(2*x + 3*y - 5)
(3*t_0 - 5, -2*t_0 + 5)

Note that it returns a tuple rather than a set. diophantine() (page 1352) always return a
set of tuples. But diop_solve() (page 1354) may return a single tuple or a set of tuples
depending on the type of the equation given.

1348 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

We can also solve this equation by calling diop_linear() (page 1354), which is what
diop_solve() (page 1354) calls internally.
>>> from sympy.solvers.diophantine import diop_linear
>>> diop_linear(2*x + 3*y - 5)
(3*t_0 - 5, -2*t_0 + 5)

If the given equation has no solutions then the outputs will look like below.
>>> diophantine(2*x + 4*y - 3)
set()
>>> diop_solve(2*x + 4*y - 3)
(None, None)
>>> diop_linear(2*x + 4*y - 3)
(None, None)

Note that except for the highest level API, in case of no solutions, a tuple of N one are re-
turned. Size of the tuple is the same as the number of variables. Also, one can specifically
set the parameter to be used in the solutions by passing a customized parameter. Consider
the following example:
>>> m = symbols(”m”, integer=True)
>>> diop_solve(2*x + 3*y - 5, m)
(3*m_0 - 5, -2*m_0 + 5)

For linear Diophantine equations, the customized parameter is the prefix used for each free
variable in the solution. Consider the following example:
>>> diop_solve(2*x + 3*y - 5*z + 7, m)
(m_0, m_0 + 5*m_1 - 14, m_0 + 3*m_1 - 7)

In the solution above, m_0 and m_1 are independent free variables.
Please note that for the moment, users can set the parameter only for linear Diophantine
equations and binary quadratic equations.
Let’s try solving a binary quadratic equation which is an equation with two variables and
has a degree of two. Before trying to solve these equations, an idea about various cases
associated with the equation would help a lot. Please refer3 and4 for detailed analysis of
different cases and the nature of the solutions. Let us define ∆ = b2 − 4ac w.r.t. the binary
quadratic ax2 + bxy + cy 2 + dx + ey + f = 0.
When ∆ < 0, there are either no solutions or only a finite number of solutions.
>>> diophantine(x**2 - 4*x*y + 8*y**2 - 3*x + 7*y - 5)
{(2, 1), (5, 1)}

In the above equation ∆ = (−4)2 − 4 ∗ 1 ∗ 8 = −16 and hence only a finite number of solutions
exist.
When ∆ = 0 we might have either no solutions or parameterized solutions.
>>> diophantine(3*x**2 - 6*x*y + 3*y**2 - 3*x + 7*y - 5)
set()
>>> diophantine(x**2 - 4*x*y + 4*y**2 - 3*x + 7*y - 5)
(continues on next page)
3 Methods to solve Ax^2 + Bxy + Cy^2 + Dx + Ey + F = 0,[online], Available: http://www.alpertron.com.ar/

METHODS.HTM
4
Solving the equation ax^2+ bxy + cy^2 + dx + ey + f= 0, [online], Available: http://www.jpr2718.org/ax2p.pdf

5.33. Diophantine 1349

SymPy Documentation, Release 1.3

(continued from previous page)

{(-2*t**2 - 7*t + 10, -t**2 - 3*t + 5)}
>>> diophantine(x**2 + 2*x*y + y**2 - 3*x - 3*y)
{(t_0, -t_0), (t_0, -t_0 + 3)}

The most interesting case is when ∆ > 0 and it is not a perfect square. In this case, the
equation has either no solutions or an infinite number of solutions. Consider the below cases
where ∆ = 8.
>>> diophantine(x**2 - 4*x*y + 2*y**2 - 3*x + 7*y - 5)
set()
>>> from sympy import sqrt
>>> n = symbols(”n”, integer=True)
>>> s = diophantine(x**2 - 2*y**2 - 2*x - 4*y, n)
>>> x_1, y_1 = s.pop()
>>> x_2, y_2 = s.pop()
>>> x_n = -(-2*sqrt(2) + 3)**n/2 + sqrt(2)*(-2*sqrt(2) + 3)**n/2 - sqrt(2)*(2*sqrt(2)␣
,→+ 3)**n/2 - (2*sqrt(2) + 3)**n/2 + 1

>>> x_1 == x_n or x_2 == x_n

True
>>> y_n = -sqrt(2)*(-2*sqrt(2) + 3)**n/4 + (-2*sqrt(2) + 3)**n/2 + sqrt(2)*(2*sqrt(2)␣
,→+ 3)**n/4 + (2*sqrt(2) + 3)**n/2 - 1

>>> y_1 == y_n or y_2 == y_n

True

Here n is an integer. Although x_n and y_n may not look like integers, substituting in specific
values for n (and simplifying) shows that they are. For example consider the following example
where we set n equal to 9.
>>> from sympy import simplify
>>> simplify(x_n.subs({n: 9}))
-9369318

Any binary quadratic of the form ax2 + bxy + cy 2 + dx + ey + f = 0 can be transformed to an

equivalent form X 2 − DY 2 = N .
>>> from sympy.solvers.diophantine import find_DN, diop_DN, transformation_to_DN
>>> find_DN(x**2 - 3*x*y + y**2 - 7*x + 5*y - 3)
(5, 920)

So, the above equation is equivalent to the equation X 2 − 5Y 2 = 920 after a linear transfor-
mation. If we want to find the linear transformation, we can use transformation_to_DN()
(page 1358)
>>> A, B = transformation_to_DN(x**2 - 3*x*y + y**2 - 7*x + 5*y - 3)

Here A is a 2 X 2 matrix and B is a 2 X 1 matrix such that the transformation

[ ] [ ]
X x
=A +B
Y y

gives the equation X 2 − 5Y 2 = 920. Values of A and B are as belows.

>>> A
Matrix([
[1/10, 3/10],
[ 0, 1/5]])
(continues on next page)

1350 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> B
Matrix([
[ 1/5],
[-11/5]])

We can solve an equation of the form X 2 − DY 2 = N by passing D and N to diop_DN()

(page 1356)

>>> diop_DN(5, 920)

[]

Unfortunately, our equation has no solution.

Now let’s turn to homogeneous ternary quadratic equations. These equations are of the form
ax2 +by 2 +cz 2 +dxy +eyz +f zx = 0. These type of equations either have infinitely many solutions
or no solutions (except the obvious solution (0, 0, 0))

>>> diophantine(3*x**2 + 4*y**2 - 5*z**2 + 4*x*y + 6*y*z + 7*z*x)

{(0, 0, 0)}
>>> diophantine(3*x**2 + 4*y**2 - 5*z**2 + 4*x*y - 7*y*z + 7*z*x)
{(-16*p**2 + 28*p*q + 20*q**2, 3*p**2 + 38*p*q - 25*q**2, 4*p**2 - 24*p*q + 68*q**2)}

If you are only interested in a base solution rather than the parameterized general solution
(to be more precise, one of the general solutions), you can use diop_ternary_quadratic()
(page 1360).

>>> from sympy.solvers.diophantine import diop_ternary_quadratic

>>> diop_ternary_quadratic(3*x**2 + 4*y**2 - 5*z**2 + 4*x*y - 7*y*z + 7*z*x)
(-4, 5, 1)

diop_ternary_quadratic() (page 1360) first converts the given equation to an equivalent

equation of the form w2 = AX 2 + BY 2 and then it uses descent() (page 1361) to solve the
latter equation. You can refer to the docs of transformation_to_normal() to find more on
this. The equation w2 = AX 2 + BY 2 can be solved more easily by using the Aforementioned
descent() (page 1361).

>>> from sympy.solvers.diophantine import descent

>>> descent(3, 1) # solves the equation w**2 = 3*Y**2 + Z**2
(1, 0, 1)

Here the solution tuple is in the order (w, Y, Z)

The extended Pythagorean equation, a1 x21 + a2 x22 + . . . + an x2n = an+1 x2n+1 and the general sum
of squares equation, x21 + x22 + . . . + x2n = k can also be solved using the Diophantine module.

>>> from sympy.abc import a, b, c, d, e, f

>>> diophantine(9*a**2 + 16*b**2 + c**2 + 49*d**2 + 4*e**2 - 25*f**2)
{(70*t1**2 + 70*t2**2 + 70*t3**2 + 70*t4**2 - 70*t5**2, 105*t1*t5, 420*t2*t5,␣
,→60*t3*t5, 210*t4*t5, 42*t1**2 + 42*t2**2 + 42*t3**2 + 42*t4**2 + 42*t5**2)}

function diop_general_pythagorean() (page 1362) can also be called directly to solve the
same equation. Either you can call diop_general_pythagorean() (page 1362) or use the
high level API. For the general sum of squares, this is also true, but one advantage of calling
diop_general_sum_of_squares() (page 1362) is that you can control how many solutions
are returned.

5.33. Diophantine 1351

SymPy Documentation, Release 1.3

>>> from sympy.solvers.diophantine import diop_general_sum_of_squares

>>> eq = a**2 + b**2 + c**2 + d**2 - 18
>>> diophantine(eq)
{(0, 0, 3, 3), (0, 1, 1, 4), (1, 2, 2, 3)}
>>> diop_general_sum_of_squares(eq, 2)
{(0, 0, 3, 3), (1, 2, 2, 3)}

The sum_of_squares() (page 1366) routine will providean iterator that returns solutions and
one may control whether the solutions contain zeros or not (and the solutions not containing
zeros are returned first):

>>> from sympy.solvers.diophantine import sum_of_squares

>>> sos = sum_of_squares(18, 4, zeros=True)
>>> next(sos)
(1, 2, 2, 3)
>>> next(sos)
(0, 0, 3, 3)

Simple Eqyptian fractions can be found with the Diophantine module, too. For example, here
are the ways that one might represent 1/2 as a sum of two unit fractions:

>>> from sympy import Eq, S

>>> diophantine(Eq(1/x + 1/y, S(1)/2))
{(-2, 1), (1, -2), (3, 6), (4, 4), (6, 3)}

To get a more thorough understanding of the Diophantine module, please refer to the follow-
ing blog.
http://thilinaatsympy.wordpress.com/

5.33.4 References

5.33.5 User Functions

This functions is imported into the global namespace with from sympy import *:

diophantine()

sympy.solvers.diophantine.diophantine(eq, param=t, syms=None, per-

mute=False)
Simplify the solution procedure of diophantine equation eq by converting it into a product
of terms which should equal zero.
For example, when solving, x2 − y 2 = 0 this is treated as (x + y)(x − y) = 0 and x + y = 0
and x − y = 0 are solved independently and combined. Each term is solved by calling
diop_solve().
Output of diophantine() is a set of tuples. The elements of the tuple are the solutions
for each variable in the equation and are arranged according to the alphabetic ordering
of the variables. e.g. For an equation with two variables, a and b, the first element of the
tuple is the solution for a and the second for b.
See also:

1352 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

diop_solve (page 1354), sympy.utilities.iterables.permute_signs (page 1471),

sympy.utilities.iterables.signed_permutations (page 1475)

Examples

>>> from sympy.abc import x, y, z

>>> diophantine(x**2 - y**2)
{(t_0, -t_0), (t_0, t_0)}

>>> diophantine(x*(2*x + 3*y - z))

{(0, n1, n2), (t_0, t_1, 2*t_0 + 3*t_1)}
>>> diophantine(x**2 + 3*x*y + 4*x)
{(0, n1), (3*t_0 - 4, -t_0)}

Usage

diophantine(eq, t, syms): Solve the diophantine equation eq. t is the optional param-
eter to be used by diop_solve(). syms is an optional list of symbols which determines
the order of the elements in the returned tuple.
By default, only the base solution is returned. If permute is set to True then permutations
of the base solution and/or permutations of the signs of the values will be returned when
applicable.

>>> from sympy.solvers.diophantine import diophantine

>>> from sympy.abc import a, b
>>> eq = a**4 + b**4 - (2**4 + 3**4)
>>> diophantine(eq)
{(2, 3)}
>>> diophantine(eq, permute=True)
{(-3, -2), (-3, 2), (-2, -3), (-2, 3), (2, -3), (2, 3), (3, -2), (3, 2)}

Details

eq should be an expression which is assumed to be zero. t is the parameter to be used

in the solution.
And this function is imported with from sympy.solvers.diophantine import *:

classify_diop()

sympy.solvers.diophantine.classify_diop(eq, _dict=True)

5.33.6 Internal Functions

These functions are intended for internal use in the Diophantine module.

5.33. Diophantine 1353

SymPy Documentation, Release 1.3

diop_solve()

sympy.solvers.diophantine.diop_solve(eq, param=t)
Solves the diophantine equation eq.
Unlike diophantine(), factoring of eq is not attempted. Uses classify_diop() to de-
termine the type of the equation and calls the appropriate solver function.
See also:
diophantine (page 1352)

Examples

>>> from sympy.solvers.diophantine import diop_solve

>>> from sympy.abc import x, y, z, w
>>> diop_solve(2*x + 3*y - 5)
(3*t_0 - 5, -2*t_0 + 5)
>>> diop_solve(4*x + 3*y - 4*z + 5)
(t_0, 8*t_0 + 4*t_1 + 5, 7*t_0 + 3*t_1 + 5)
>>> diop_solve(x + 3*y - 4*z + w - 6)
(t_0, t_0 + t_1, 6*t_0 + 5*t_1 + 4*t_2 - 6, 5*t_0 + 4*t_1 + 3*t_2 - 6)
>>> diop_solve(x**2 + y**2 - 5)
{(-2, -1), (-2, 1), (-1, -2), (-1, 2), (1, -2), (1, 2), (2, -1), (2, 1)}

Usage

diop_solve(eq, t): Solve diophantine equation, eq using t as a parameter if needed.

Details

eq should be an expression which is assumed to be zero. t is a parameter to be used in

the solution.

diop_linear()

sympy.solvers.diophantine.diop_linear(eq, param=t)
Solves linear diophantine equations.
A linear diophantine equation is an equation of the form a1 x1 + a2 x2 + .. + an xn = 0 where
a1 , a2 , ..an are integer constants and x1 , x2 , ..xn are integer variables.
See also:
diop_quadratic (page 1356), diop_ternary_quadratic (page 1360),
diop_general_pythagorean (page 1362), diop_general_sum_of_squares (page 1362)

Examples

1354 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.solvers.diophantine import diop_linear

>>> from sympy.abc import x, y, z, t
>>> diop_linear(2*x - 3*y - 5) # solves equation 2*x - 3*y - 5 == 0
(3*t_0 - 5, 2*t_0 - 5)

Here x = -3*t_0 - 5 and y = -2*t_0 - 5

>>> diop_linear(2*x - 3*y - 4*z -3)

(t_0, 2*t_0 + 4*t_1 + 3, -t_0 - 3*t_1 - 3)

Usage

diop_linear(eq): Returns a tuple containing solutions to the diophantine equation eq.

Values in the tuple is arranged in the same order as the sorted variables.

Details

eq is a linear diophantine equation which is assumed to be zero. param is the parameter

to be used in the solution.

base_solution_linear()

sympy.solvers.diophantine.base_solution_linear(c, a, b, t=None)
Return the base solution for the linear equation, ax + by = c.
Used by diop_linear() to find the base solution of a linear Diophantine equation. If t
is given then the parametrized solution is returned.

Examples

>>> from sympy.solvers.diophantine import base_solution_linear

>>> from sympy.abc import t
>>> base_solution_linear(5, 2, 3) # equation 2*x + 3*y = 5
(-5, 5)
>>> base_solution_linear(0, 5, 7) # equation 5*x + 7*y = 0
(0, 0)
>>> base_solution_linear(5, 2, 3, t) # equation 2*x + 3*y = 5
(3*t - 5, -2*t + 5)
>>> base_solution_linear(0, 5, 7, t) # equation 5*x + 7*y = 0
(7*t, -5*t)

Usage

base_solution_linear(c, a, b, t): a, b, c are coefficients in ax + by = c and t is the

parameter to be used in the solution.

5.33. Diophantine 1355

SymPy Documentation, Release 1.3

diop_quadratic()

sympy.solvers.diophantine.diop_quadratic(eq, param=t)
Solves quadratic diophantine equations.
i.e. equations of the form Ax2 + Bxy + Cy 2 + Dx + Ey + F = 0. Returns a set containing
the tuples (x, y) which contains the solutions. If there are no solutions then (N one, N one)
is returned.
See also:
diop_linear (page 1354), diop_ternary_quadratic (page 1360),
diop_general_sum_of_squares (page 1362), diop_general_pythagorean (page 1362)

References

[R509], [R510]

Examples

>>> from sympy.abc import x, y, t

>>> from sympy.solvers.diophantine import diop_quadratic
>>> diop_quadratic(x**2 + y**2 + 2*x + 2*y + 2, t)
{(-1, -1)}

Usage

diop_quadratic(eq, param): eq is a quadratic binary diophantine equation. param is

used to indicate the parameter to be used in the solution.

Details

eq should be an expression which is assumed to be zero. param is a parameter to be used

in the solution.

diop_DN()

sympy.solvers.diophantine.diop_DN(D, N, t=t)
Solves the equation x2 − Dy 2 = N .
Mainly concerned with the case D > 0, D is not a perfect square, which is the same as
the generalized Pell equation. The LMM algorithm [R511] is used to solve this equation.
Returns one solution tuple, (x, y) for each class of the solutions. Other solutions of the
class can be constructed according to the values of D and N.
See also:
find_DN (page 1360), diop_bf_DN (page 1358)

1356 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R511]

Examples

>>> from sympy.solvers.diophantine import diop_DN

>>> diop_DN(13, -4) # Solves equation x**2 - 13*y**2 = -4
[(3, 1), (393, 109), (36, 10)]

The output can be interpreted as follows: There are three fundamental solutions to the
equation x2 − 13y 2 = −4 given by (3, 1), (393, 109) and (36, 10). Each tuple is in the form
(x, y), i.e. solution (3, 1) means that x = 3 and y = 1.

>>> diop_DN(986, 1) # Solves equation x**2 - 986*y**2 = 1

[(49299, 1570)]

Usage

diop_DN(D, N, t): D and N are integers as in x2 − Dy 2 = N and t is the parameter to

be used in the solutions.

Details

D and N correspond to D and N in the equation. t is the parameter to be used in the

solutions.

cornacchia()

sympy.solvers.diophantine.cornacchia(a, b, m)
Solves ax2 + by 2 = m where gcd(a, b) = 1 = gcd(a, m) and a, b > 0.
Uses the algorithm due to Cornacchia. The method only finds primitive solutions, i.e.
ones with gcd(x, y) = 1. So this method can’t be used to find the solutions of x2 + y 2 = 20
since the only solution to former is (x, y) = (4, 2) and it is not primitive. When a = b, only
the solutions with x ≤ y are found. For more details, see the References.
See also:
sympy.utilities.iterables.signed_permutations (page 1475)

References

[R512], [R513]

Examples

5.33. Diophantine 1357

SymPy Documentation, Release 1.3

>>> from sympy.solvers.diophantine import cornacchia

>>> cornacchia(2, 3, 35) # equation 2x**2 + 3y**2 = 35
{(2, 3), (4, 1)}
>>> cornacchia(1, 1, 25) # equation x**2 + y**2 = 25
{(4, 3)}

diop_bf_DN()

sympy.solvers.diophantine.diop_bf_DN(D, N, t=t)
Uses brute force to solve the equation, x2 − Dy 2 = N .
Mainly concerned with the generalized Pell equation which is the case when D > 0, D
is not a perfect square. For more information on the case refer [R514]. Let (t, u) be
the minimal positive solution of the equation x2 − Dy 2 = 1. Then this method requires
√
f rac| N | (t ± 1)2D to be small.
See also:
diop_DN (page 1356)

References

[R514]

Examples

>>> from sympy.solvers.diophantine import diop_bf_DN

>>> diop_bf_DN(13, -4)
[(3, 1), (-3, 1), (36, 10)]
>>> diop_bf_DN(986, 1)
[(49299, 1570)]

Usage

diop_bf_DN(D, N, t): D and N are coefficients in x2 − Dy 2 = N and t is the parameter

to be used in the solutions.

Details

D and N correspond to D and N in the equation. t is the parameter to be used in the

solutions.

transformation_to_DN()

sympy.solvers.diophantine.transformation_to_DN(eq)
This function transforms general quadratic, ax2 + bxy + cy 2 + dx + ey + f = 0 to more easy
to deal with X 2 − DY 2 = N form.

1358 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

This is used to solve the general quadratic equation by transforming it to the latter form.
Refer [R515] for more detailed information on the transformation. This function returns
a tuple (A, B) where A is a 2 X 2 matrix and B is a 2 X 1 matrix such that,
Transpose([x y]) = A * Transpose([X Y]) + B
See also:
find_DN (page 1360)

References

[R515]

Examples

>>> from sympy.abc import x, y

>>> from sympy.solvers.diophantine import transformation_to_DN
>>> from sympy.solvers.diophantine import classify_diop
>>> A, B = transformation_to_DN(x**2 - 3*x*y - y**2 - 2*y + 1)
>>> A
Matrix([
[1/26, 3/26],
[ 0, 1/13]])
>>> B
Matrix([
[-6/13],
[-4/13]])

A, B returned are such that Transpose((x y)) = A * Transpose((X Y)) + B. Substituting

these values for x and y and a bit of simplifying work will give an equation of the form
x2 − Dy 2 = N .

>>> from sympy.abc import X, Y

>>> from sympy import Matrix, simplify
>>> u = (A*Matrix([X, Y]) + B)[0] # Transformation for x
>>> u
X/26 + 3*Y/26 - 6/13
>>> v = (A*Matrix([X, Y]) + B)[1] # Transformation for y
>>> v
Y/13 - 4/13

Next we will substitute these formulas for x and y and do simplify().

>>> eq = simplify((x**2 - 3*x*y - y**2 - 2*y + 1).subs(zip((x, y), (u, v))))

>>> eq
X**2/676 - Y**2/52 + 17/13

By multiplying the denominator appropriately, we can get a Pell equation in the standard
form.

>>> eq * 676
X**2 - 13*Y**2 + 884

If only the final equation is needed, find_DN() can be used.

5.33. Diophantine 1359

SymPy Documentation, Release 1.3

Usage

transformation_to_DN(eq): where eq is the quadratic to be transformed.

find_DN()

sympy.solvers.diophantine.find_DN(eq)
This function returns a tuple, (D, N ) of the simplified form, x2 − Dy 2 = N , corresponding
to the general quadratic, ax2 + bxy + cy 2 + dx + ey + f = 0.
Solving the general quadratic is then equivalent to solving the equation X 2 − DY 2 = N
and transforming the solutions by using the transformation matrices returned by trans-
formation_to_DN().
See also:
transformation_to_DN (page 1358)

References

[R516]

Examples

>>> from sympy.abc import x, y

>>> from sympy.solvers.diophantine import find_DN
>>> find_DN(x**2 - 3*x*y - y**2 - 2*y + 1)
(13, -884)

Interpretation of the output is that we get X 2 − 13Y 2 = −884 after transforming x2 − 3xy −
y 2 − 2y + 1 using the transformation returned by transformation_to_DN().

Usage

find_DN(eq): where eq is the quadratic to be transformed.

diop_ternary_quadratic()

sympy.solvers.diophantine.diop_ternary_quadratic(eq)
Solves the general quadratic ternary form, ax2 + by 2 + cz 2 + f xy + gyz + hxz = 0.
Returns a tuple (x, y, z) which is a base solution for the above equation. If there are no
solutions, (N one, N one, N one) is returned.

Examples

1360 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import x, y, z

>>> from sympy.solvers.diophantine import diop_ternary_quadratic
>>> diop_ternary_quadratic(x**2 + 3*y**2 - z**2)
(1, 0, 1)
>>> diop_ternary_quadratic(4*x**2 + 5*y**2 - z**2)
(1, 0, 2)
>>> diop_ternary_quadratic(45*x**2 - 7*y**2 - 8*x*y - z**2)
(28, 45, 105)
>>> diop_ternary_quadratic(x**2 - 49*y**2 - z**2 + 13*z*y -8*x*y)
(9, 1, 5)

Usage

diop_ternary_quadratic(eq): Return a tuple containing a basic solution to eq.

Details

eq should be an homogeneous expression of degree two in three variables and it is as-

sumed to be zero.

square_factor()

sympy.solvers.diophantine.square_factor(a)
Returns an integer c s.t. a = c2 k, c, k ∈ Z. Here k is square free. a can be given as an
integer or a dictionary of factors.
See also:
sympy.ntheory.factor_.core (page 327)

Examples

>>> from sympy.solvers.diophantine import square_factor

>>> square_factor(24)
2
>>> square_factor(-36*3)
6
>>> square_factor(1)
1
>>> square_factor({3: 2, 2: 1, -1: 1}) # -18
3

descent()

sympy.solvers.diophantine.descent(A, B)
Returns a non-trivial solution, (x, y, z), to x2 = Ay 2 +Bz 2 using Lagrange’s descent method
with lattice-reduction. A and B are assumed to be valid for such a solution to exist.
This is faster than the normal Lagrange’s descent algorithm because the Gaussian re-
duction is used.

5.33. Diophantine 1361

SymPy Documentation, Release 1.3

References

[R517]

Examples

>>> from sympy.solvers.diophantine import descent

>>> descent(3, 1) # x**2 = 3*y**2 + z**2
(1, 0, 1)

(x, y, z) = (1, 0, 1) is a solution to the above equation.

>>> descent(41, -113)

(-16, -3, 1)

diop_general_pythagorean()

sympy.solvers.diophantine.diop_general_pythagorean(eq, param=m)
Solves the general pythagorean equation, a21 x21 + a22 x22 + ... + a2n x2n − a2n+1 x2n+1 = 0.
Returns a tuple which contains a parametrized solution to the equation, sorted in the
same order as the input variables.

Examples

>>> from sympy.solvers.diophantine import diop_general_pythagorean

>>> from sympy.abc import a, b, c, d, e
>>> diop_general_pythagorean(a**2 + b**2 + c**2 - d**2)
(m1**2 + m2**2 - m3**2, 2*m1*m3, 2*m2*m3, m1**2 + m2**2 + m3**2)
>>> diop_general_pythagorean(9*a**2 - 4*b**2 + 16*c**2 + 25*d**2 + e**2)
(10*m1**2 + 10*m2**2 + 10*m3**2 - 10*m4**2, 15*m1**2 + 15*m2**2 + 15*m3**2 +␣
,→15*m4**2, 15*m1*m4, 12*m2*m4, 60*m3*m4)

Usage

diop_general_pythagorean(eq, param): where eq is a general pythagorean equation

which is assumed to be zero and param is the base parameter used to construct other
parameters by subscripting.

diop_general_sum_of_squares()

sympy.solvers.diophantine.diop_general_sum_of_squares(eq, limit=1)
Solves the equation x21 + x22 + ... + x2n − k = 0.
Returns at most limit number of solutions.

1362 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.solvers.diophantine import diop_general_sum_of_squares

>>> from sympy.abc import a, b, c, d, e, f
>>> diop_general_sum_of_squares(a**2 + b**2 + c**2 + d**2 + e**2 - 2345)
{(15, 22, 22, 24, 24)}

Usage

general_sum_of_squares(eq, limit) : Here eq is an expression which is assumed to

be zero. Also, eq should be in the form, x21 + x22 + ... + x2n − k = 0.

Details

When n = 3 if k = 4a (8m + 7) for some a, m ∈ Z then there will be no solutions. Refer

[R518] for more details.

Reference

diop_general_sum_of_even_powers()

sympy.solvers.diophantine.diop_general_sum_of_even_powers(eq, limit=1)
Solves the equation xe1 + xe2 + ... + xen − k = 0 where e is an even, integer power.
Returns at most limit number of solutions.
See also:
power_representation

Examples

>>> from sympy.solvers.diophantine import diop_general_sum_of_even_powers

>>> from sympy.abc import a, b
>>> diop_general_sum_of_even_powers(a**4 + b**4 - (2**4 + 3**4))
{(2, 3)}

Usage

general_sum_of_even_powers(eq, limit) : Here eq is an expression which is assumed

to be zero. Also, eq should be in the form, xe1 + xe2 + ... + xen − k = 0.

partition()

sympy.solvers.diophantine.partition(n, k=None, zeros=False)

Returns a generator that can be used to generate partitions of an integer n.
A partition of n is a set of positive integers which add up to n. For example, partitions of
3 are 3, 1 + 2, 1 + 1 + 1. A partition is returned as a tuple. If k equals None, then all

5.33. Diophantine 1363

SymPy Documentation, Release 1.3

possible partitions are returned irrespective of their size, otherwise only the partitions
of size k are returned. If the zero parameter is set to True then a suitable number of
zeros are added at the end of every partition of size less than k.
zero parameter is considered only if k is not None. When the partitions are over, the
last next() call throws the StopIteration exception, so this function should always be
used inside a try - except block.

Examples

>>> from sympy.solvers.diophantine import partition

>>> f = partition(5)
>>> next(f)
(1, 1, 1, 1, 1)
>>> next(f)
(1, 1, 1, 2)
>>> g = partition(5, 3)
>>> next(g)
(1, 1, 3)
>>> next(g)
(1, 2, 2)
>>> g = partition(5, 3, zeros=True)
>>> next(g)
(0, 0, 5)

Details

partition(n, k): Here n is a positive integer and k is the size of the partition which is
also positive integer.

sum_of_three_squares()

sympy.solvers.diophantine.sum_of_three_squares(n)
Returns a 3-tuple (a, b, c) such that a2 + b2 + c2 = n and a, b, c ≥ 0.
Returns None if n = 4a (8m + 7) for some a, m ∈ Z. See [R519] for more details.
See also:
sum_of_squares (page 1366)

References

[R519]

Examples

>>> from sympy.solvers.diophantine import sum_of_three_squares

>>> sum_of_three_squares(44542)
(18, 37, 207)

1364 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Usage

sum_of_three_squares(n): Here n is a non-negative integer.

sum_of_four_squares()

sympy.solvers.diophantine.sum_of_four_squares(n)
Returns a 4-tuple (a, b, c, d) such that a2 + b2 + c2 + d2 = n.
Here a, b, c, d ≥ 0.
See also:
sum_of_squares (page 1366)

References

[R520]

Examples

>>> from sympy.solvers.diophantine import sum_of_four_squares

>>> sum_of_four_squares(3456)
(8, 8, 32, 48)
>>> sum_of_four_squares(1294585930293)
(0, 1234, 2161, 1137796)

Usage

sum_of_four_squares(n): Here n is a non-negative integer.

sum_of_powers()

sympy.solvers.diophantine.sum_of_powers(n, p, k, zeros=False)
Returns a generator for finding k-tuples of integers, (n1 , n2 , ...nk ), such that n = np1 + np2 +
...npk .

Examples

>>> from sympy.solvers.diophantine import power_representation

Represent 1729 as a sum of two cubes:

>>> f = power_representation(1729, 3, 2)
>>> next(f)
(9, 10)
>>> next(f)
(1, 12)

5.33. Diophantine 1365

SymPy Documentation, Release 1.3

If the flag zeros is True, the solution may contain tuples with zeros; any such solutions
will be generated after the solutions without zeros:

>>> list(power_representation(125, 2, 3, zeros=True))

[(5, 6, 8), (3, 4, 10), (0, 5, 10), (0, 2, 11)]

For even p the permutes ign function can be used to get all signed values:

>>> from sympy.utilities.iterables import permute_signs

>>> list(permute_signs((1, 12)))
[(1, 12), (-1, 12), (1, -12), (-1, -12)]

All possible signed permutations can also be obtained:

>>> from sympy.utilities.iterables import signed_permutations

>>> list(signed_permutations((1, 12)))
[(1, 12), (-1, 12), (1, -12), (-1, -12), (12, 1), (-12, 1), (12, -1), (-12, -1)]

Usage

power_representation(n, p, k, zeros): Represent non-negative number n as a sum

of k p``th powers. If ``zeros is true, then the solutions is allowed to contain zeros.

sum_of_squares()

sympy.solvers.diophantine.sum_of_squares(n, k, zeros=False)
Return a generator that yields the k-tuples of nonnegative values, the squares of which
sum to n. If zeros is False (default) then the solution will not contain zeros. The nonneg-
ative elements of a tuple are sorted.
• If k == 1 and n is square, (n,) is returned.
• If k == 2 then n can only be written as a sum of squares if every prime in the
factorization of n that has the form 4*k + 3 has an even multiplicity. If n is prime
then it can only be written as a sum of two squares if it is in the form 4*k + 1.
• if k == 3 then n can be written as a sum of squares if it does not have the form
4**m*(8*k + 7).
• all integers can be written as the sum of 4 squares.
• if k > 4 then n can be partitioned and each partition can be written as a sum of 4
squares; if n is not evenly divisible by 4 then n can be written as a sum of squares
only if the an additional partition can be written as sum of squares. For example,
if k = 6 then n is partitioned into two parts, the first being written as a sum of 4
squares and the second being written as a sum of 2 squares – which can only be
done if the condition above for k = 2 can be met, so this will automatically reject
certain partitions of n.
See also:
sympy.utilities.iterables.signed_permutations (page 1475)

1366 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.solvers.diophantine import sum_of_squares

>>> list(sum_of_squares(25, 2))
[(3, 4)]
>>> list(sum_of_squares(25, 2, True))
[(3, 4), (0, 5)]
>>> list(sum_of_squares(25, 4))
[(1, 2, 2, 4)]

merge_solution

sympy.solvers.diophantine.merge_solution(var, var_t, solution)

This is used to construct the full solution from the solutions of sub equations.
For example when solving the equation (x − y)(x2 + y 2 − z 2 ) = 0, solutions for each of
the equations x − y = 0 and x2 + y 2 − z 2 are found independently. Solutions for x − y = 0
are (x, y) = (t, t). But we should introduce a value for z when we output the solution
for the original equation. This function converts (t, t) into (t, t, n1 ) where n1 is an integer
parameter.

divisible

sympy.solvers.diophantine.divisible(a, b)
Returns T rue if a is divisible by b and F alse otherwise.

PQa

sympy.solvers.diophantine.PQa(P_0, Q_0, D)
Returns useful information needed to solve the Pell equation.
There are six sequences of integers defined related to the continued fraction represen-
tation of√
f racP + DQ, namely {Pi }, {Qi }, {ai },{Ai }, {Bi }, {Gi }. PQa() Returns these values as
a 6-tuple in the same order as mentioned above. Refer [R521] for more detailed infor-
mation.

References

[R521]

Examples

>>> from sympy.solvers.diophantine import PQa

>>> pqa = PQa(13, 4, 5) # (13 + sqrt(5))/4
>>> next(pqa) # (P_0, Q_0, a_0, A_0, B_0, G_0)
(13, 4, 3, 3, 1, -1)
>>> next(pqa) # (P_1, Q_1, a_1, A_1, B_1, G_1)
(-1, 1, 1, 4, 1, 3)

5.33. Diophantine 1367

SymPy Documentation, Release 1.3

Usage

PQa(P_0, Q_0, D): P_0, Q_0 and D are integers corresponding to P0 , Q0 and D in the
continued√ fraction
f racP0 + DQ0 . Also it’s assumed that P02 == Dmod(|Q0 |) and D is square free.

equivalent

sympy.solvers.diophantine.equivalent(u, v, r, s, D, N)
Returns True if two solutions (u, v) and (r, s) of x2 − Dy 2 = N belongs to the same equiva-
lence class and False otherwise.
Two solutions (u, v) and (r, s) to the above equation fall to the same equivalence class iff
both (ur−Dvs) and (us−vr) are divisible by N . See reference [R522]. No test is performed
to test whether (u, v) and (r, s) are actually solutions to the equation. User should take
care of this.

References

[R522]

Examples

>>> from sympy.solvers.diophantine import equivalent

>>> equivalent(18, 5, -18, -5, 13, -1)
True
>>> equivalent(3, 1, -18, 393, 109, -4)
False

Usage

equivalent(u, v, r, s, D, N): (u, v) and (r, s) are two solutions of the equation x2 −
Dy 2 = N and all parameters involved are integers.

parametrize_ternary_quadratic

sympy.solvers.diophantine.parametrize_ternary_quadratic(eq)
Returns the parametrized general solution for the ternary quadratic equation eq which
has the form ax2 + by 2 + cz 2 + f xy + gyz + hxz = 0.

References

[R523]

1368 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.abc import x, y, z

>>> from sympy.solvers.diophantine import parametrize_ternary_quadratic
>>> parametrize_ternary_quadratic(x**2 + y**2 - z**2)
(2*p*q, p**2 - q**2, p**2 + q**2)

Here p and q are two co-prime integers.

>>> parametrize_ternary_quadratic(3*x**2 + 2*y**2 - z**2 - 2*x*y + 5*y*z - 7*y*z)

(2*p**2 - 2*p*q - q**2, 2*p**2 + 2*p*q - q**2, 2*p**2 - 2*p*q + 3*q**2)
>>> parametrize_ternary_quadratic(124*x**2 - 30*y**2 - 7729*z**2)
(-1410*p**2 - 363263*q**2, 2700*p**2 + 30916*p*q - 695610*q**2, -60*p**2 +␣
,→5400*p*q + 15458*q**2)

diop_ternary_quadratic_normal

sympy.solvers.diophantine.diop_ternary_quadratic_normal(eq)
Solves the quadratic ternary diophantine equation, ax2 + by 2 + cz 2 = 0.
Here the coefficients a, b, and c should be non zero. Otherwise the equation will be a
quadratic binary or univariate equation. If solvable, returns a tuple (x, y, z) that satisfies
the given equation. If the equation does not have integer solutions, (N one, N one, N one) is
returned.

Examples

>>> from sympy.abc import x, y, z

>>> from sympy.solvers.diophantine import diop_ternary_quadratic_normal
>>> diop_ternary_quadratic_normal(x**2 + 3*y**2 - z**2)
(1, 0, 1)
>>> diop_ternary_quadratic_normal(4*x**2 + 5*y**2 - z**2)
(1, 0, 2)
>>> diop_ternary_quadratic_normal(34*x**2 - 3*y**2 - 301*z**2)
(4, 9, 1)

Usage

diop_ternary_quadratic_normal(eq): where eq is an equation of the form ax2 + by 2 +

cz 2 = 0.

ldescent

sympy.solvers.diophantine.ldescent(A, B)
Return a non-trivial solution to w2 = Ax2 + By 2 using Lagrange’s method; return None if
there is no such solution. .
Here, A ̸= 0 and B ̸= 0 and A and B are square free. Output a tuple (w0 , x0 , y0 ) which is a
solution to the above equation.

5.33. Diophantine 1369

SymPy Documentation, Release 1.3

References

[R524], [R525]

Examples

>>> from sympy.solvers.diophantine import ldescent

>>> ldescent(1, 1) # w^2 = x^2 + y^2
(1, 1, 0)
>>> ldescent(4, -7) # w^2 = 4x^2 - 7y^2
(2, -1, 0)

This means that x = −1, y = 0 and w = 2 is a solution to the equation w2 = 4x2 − 7y 2

>>> ldescent(5, -1) # w^2 = 5x^2 - y^2

(2, 1, -1)

gaussian_reduce

sympy.solvers.diophantine.gaussian_reduce(w, a, b)
Returns a reduced solution (x, z) to the congruence X 2 − aZ 2 ≡ 0 (mod b) so that x2 + |a|z 2
is minimal.

References

[R526], [R527]

Details

Here w is a solution of the congruence x2 ≡ a (mod b)

holzer

sympy.solvers.diophantine.holzer(x, y, z, a, b, c)
Simplify the solution (x, y, z) of the equation ax2 + by 2 = cz 2 with a, b, c > 0 and z 2 ≥| ab | to
a new reduced solution (x′ , y ′ , z ′ ) such that z ′2 ≤| ab |.
The algorithm is an interpretation of Mordell’s reduction as described on page 8 of Cre-
mona and Rusin’s paper [R528] and the work of Mordell in reference [R529].

References

[R528], [R529]

1370 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

prime_as_sum_of_two_squares

sympy.solvers.diophantine.prime_as_sum_of_two_squares(p)
Represent a prime p as a unique sum of two squares; this can only be done if the prime
is congruent to 1 mod 4.
See also:
sum_of_squares (page 1366)

Examples

>>> from sympy.solvers.diophantine import prime_as_sum_of_two_squares

>>> prime_as_sum_of_two_squares(7) # can't be done
>>> prime_as_sum_of_two_squares(5)
(1, 2)

Reference

sqf_normal

sympy.solvers.diophantine.sqf_normal(a, b, c, steps=False)
Return a′ , b′ , c′ , the coefficients of the square-free normal form of ax2 + by 2 + cz 2 = 0, where
a′ , b′ , c′ are pairwise prime. If steps is True then also return three tuples: sq, sqf , and
(a′ , b′ , c′ ) where sq contains the square factors of a, b and c after removing the gcd(a, b, c);
sqf contains the values of a, b and c after removing both the gcd(a, b, c) and the square
factors.
The solutions for ax2 +by 2 +cz 2 = 0 can be recovered from the solutions of a′ x2 +b′ y 2 +c′ z 2 =
0.
See also:
reconstruct (page 1372)

References

[R531]

Examples

>>> from sympy.solvers.diophantine import sqf_normal

>>> sqf_normal(2 * 3**2 * 5, 2 * 5 * 11, 2 * 7**2 * 11)
(11, 1, 5)
>>> sqf_normal(2 * 3**2 * 5, 2 * 5 * 11, 2 * 7**2 * 11, True)
((3, 1, 7), (5, 55, 11), (11, 1, 5))

5.33. Diophantine 1371

SymPy Documentation, Release 1.3

reconstruct

sympy.solvers.diophantine.reconstruct(A, B, z)
Reconstruct the z value of an equivalent solution of ax2 + by 2 + cz 2 from the z value of a
solution of the square-free normal form of the equation, a′ ∗ x2 + b′ ∗ y 2 + c′ ∗ z 2 , where a′ ,
b′ and c′ are square free and gcd(a′ , b′ , c′ ) == 1.

5.34 Inequality Solvers

sympy.solvers.inequalities.solve_rational_inequalities(eqs)
Solve a system of rational inequalities with rational coefficients.
See also:
solve_poly_inequality (page 1372)

Examples

>>> from sympy.abc import x

>>> from sympy import Poly
>>> from sympy.solvers.inequalities import solve_rational_inequalities

>>> solve_rational_inequalities([[
... ((Poly(-x + 1), Poly(1, x)), '>='),
... ((Poly(-x + 1), Poly(1, x)), '<=')]])
{1}

>>> solve_rational_inequalities([[
... ((Poly(x), Poly(1, x)), '!='),
... ((Poly(-x + 1), Poly(1, x)), '>=')]])
Union(Interval.open(-oo, 0), Interval.Lopen(0, 1))

sympy.solvers.inequalities.solve_poly_inequality(poly, rel)
Solve a polynomial inequality with rational coefficients.
See also:
solve_poly_inequalities

Examples

>>> from sympy import Poly

>>> from sympy.abc import x
>>> from sympy.solvers.inequalities import solve_poly_inequality

>>> solve_poly_inequality(Poly(x, x, domain='ZZ'), '==')

[{0}]

>>> solve_poly_inequality(Poly(x**2 - 1, x, domain='ZZ'), '!=')

[Interval.open(-oo, -1), Interval.open(-1, 1), Interval.open(1, oo)]

1372 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> solve_poly_inequality(Poly(x**2 - 1, x, domain='ZZ'), '==')

[{-1}, {1}]

sympy.solvers.inequalities.reduce_rational_inequalities(exprs, gen, rela-

tional=True)
Reduce a system of rational inequalities with rational coefficients.

Examples

>>> from sympy import Poly, Symbol

>>> from sympy.solvers.inequalities import reduce_rational_inequalities

>>> x = Symbol('x', real=True)

>>> reduce_rational_inequalities([[x**2 <= 0]], x)

Eq(x, 0)

>>> reduce_rational_inequalities([[x + 2 > 0]], x)

(-2 < x) & (x < oo)
>>> reduce_rational_inequalities([[(x + 2, ”>”)]], x)
(-2 < x) & (x < oo)
>>> reduce_rational_inequalities([[x + 2]], x)
Eq(x, -2)

sympy.solvers.inequalities.reduce_abs_inequality(expr, rel, gen)

Reduce an inequality with nested absolute values.
See also:
reduce_abs_inequalities (page 1373)

Examples

>>> from sympy import Abs, Symbol

>>> from sympy.solvers.inequalities import reduce_abs_inequality
>>> x = Symbol('x', real=True)

>>> reduce_abs_inequality(Abs(x - 5) - 3, '<', x)

(2 < x) & (x < 8)

>>> reduce_abs_inequality(Abs(x + 2)*3 - 13, '<', x)

(-19/3 < x) & (x < 7/3)

sympy.solvers.inequalities.reduce_abs_inequalities(exprs, gen)
Reduce a system of inequalities with nested absolute values.
See also:
reduce_abs_inequality (page 1373)

5.34. Inequality Solvers 1373

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Abs, Symbol

>>> from sympy.abc import x
>>> from sympy.solvers.inequalities import reduce_abs_inequalities
>>> x = Symbol('x', real=True)

>>> reduce_abs_inequalities([(Abs(3*x - 5) - 7, '<'),

... (Abs(x + 25) - 13, '>')], x)
(-2/3 < x) & (x < 4) & (((-oo < x) & (x < -38)) | ((-12 < x) & (x < oo)))

>>> reduce_abs_inequalities([(Abs(x - 4) + Abs(3*x - 5) - 7, '<')], x)

(1/2 < x) & (x < 4)

sympy.solvers.inequalities.reduce_inequalities(inequalities, symbols=[])
Reduce a system of inequalities with rational coefficients.

Examples

>>> from sympy import sympify as S, Symbol

>>> from sympy.abc import x, y
>>> from sympy.solvers.inequalities import reduce_inequalities

>>> reduce_inequalities(0 <= x + 3, [])

(-3 <= x) & (x < oo)

>>> reduce_inequalities(0 <= x + y*2 - 1, [x])

(x < oo) & (x >= -2*y + 1)

sympy.solvers.inequalities.solve_univariate_inequality(expr, gen, rela-

tional=True, do-
main=Reals, continu-
ous=False)
Solves a real univariate inequality.
Parameters expr : Relational
The target inequality
gen : Symbol
The variable for which the inequality is solved
relational : bool
A Relational type output is expected or not
domain : Set
The domain over which the equation is solved
continuous: bool
True if expr is known to be continuous over the given domain (and so
continuous_domain() doesn’t need to be called on it)
Raises NotImplementedError

1374 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The solution of the inequality cannot be determined due to limitation

in solvif y.
See also:

solvify solver returning solveset solutions with solve’s output API

Notes

Currently, we cannot solve all the inequalities due to limitations in solvif y. Also, the
solution returned for trigonometric inequalities are restricted in its periodic interval.

Examples

>>> from sympy.solvers.inequalities import solve_univariate_inequality

>>> from sympy import Symbol, sin, Interval, S
>>> x = Symbol('x')

>>> solve_univariate_inequality(x**2 >= 4, x)

((2 <= x) & (x < oo)) | ((x <= -2) & (-oo < x))

>>> solve_univariate_inequality(x**2 >= 4, x, relational=False)

Union(Interval(-oo, -2), Interval(2, oo))

>>> domain = Interval(0, S.Infinity)

>>> solve_univariate_inequality(x**2 >= 4, x, False, domain)
Interval(2, oo)

>>> solve_univariate_inequality(sin(x) > 0, x, relational=False)

Interval.open(0, pi)

5.35 Solveset

This is the official documentation of the solveset module in solvers. It contains the frequently
asked questions about our new module to solve equations.

5.35.1 What’s wrong with solve():

SymPy already has a pretty powerful solve function. But it has a lot of major issues
1. It doesn’t have a consistent output for various types of solutions It needs to return a lot
of types of solutions consistently:
• Single solution : x = 1
• Multiple solutions: x2 = 1
• No Solution: x2 + 1 = 0; x ∈ R
• Interval of solution: ⌊x⌋ = 0

5.35. Solveset 1375

SymPy Documentation, Release 1.3

• Infinitely many solutions: sin(x) = 0

• Multivariate functions with point solutions: x2 + y 2 = 0
• Multivariate functions with non-point solution: x2 + y 2 = 1
• System of equations: x + y = 1 and x − y = 0
• Relational: x > 0
• And the most important case: “We don’t Know”
2. The input API is also a mess, there are a lot of parameters. Many of them are not needed
and they make it hard for the user and the developers to work on solvers.
3. There are cases like finding the maxima and minima of function using critical points
where it is important to know if it has returned all the solutions. solve does not guar-
antee this.

5.35.2 Why Solveset?

• solveset has a cleaner input and output interface: solveset returns a set object and
a set object takes care of all types of output. For cases where it doesn’t “know” all the
solutions a ConditionSet with a partial solution is returned. For input it only takes the
equation, the variables to solve for and the optional argument domain over which the
equation is to be solved.
• solveset can return infinitely many solutions. For example solving for sin (x) = 0 returns
{2nπ|n ∈ Z} ∪ {2nπ + π|n ∈ Z}, whereas solve only returns [0, π].
• There is a clear code level and interface level separation between solvers for equations
in the complex domain and the real domain. For example solving ex = 1 when x is to
be solved in the complex domain, returns the set of all solutions, that is {2niπ|n ∈ Z},
whereas if x is to be solved in the real domain then only {0} is returned.

5.35.3 Why do we use Sets as an output type?

SymPy has a well developed sets module, which can represent most of the set containers in
Mathematics such as:
• FiniteSet
Represents a finite set of discrete numbers.
• Interval
Represents a real interval as a set.
• ProductSet
Represents a Cartesian product of sets.
• ImageSet
Represents the image of a set under a mathematical function

>>> from sympy import ImageSet, S, Lambda

>>> from sympy.abc import x
>>> squares = ImageSet(Lambda(x, x**2), S.Naturals) # {x**2 for x in N}
(continues on next page)

1376 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> 4 in squares
True

• ComplexRegion
Represents the set of all complex numbers in a region in the Argand plane.
• ConditionSet
Represents the set of elements, which satisfies a given condition.
Also, the predefined set classes such as:
• Naturals N
Represents the natural numbers (or counting numbers), which are all positive
integers starting from 1.
• Naturals0 N⊬
Represents the whole numbers, which are all the non-negative integers, inclu-
sive of 0.
• Integers Z
Represents all integers: positive, negative and zero.
• Reals R
Represents the set of all real numbers.
• Complexes C
Represents the set of all complex numbers.
• EmptySet ϕ
Represents the empty set.
The above six sets are available as Singletons, like S.Integers.
It is capable of most of the set operations in mathematics:
• Union
• Intersection
• Complement
• SymmetricDifference
The main reason for using sets as output to solvers is that it can consistently represent many
types of solutions. For the single variable case it can represent:
• No solution (by the empty set).
• Finitely many solutions (by FiniteSet).
• Infinitely many solutions, both countably and uncountably infinite solutions (using the
ImageSet module).
• Interval
• There can also be bizarre solutions to equations like the set of rational numbers.

5.35. Solveset 1377

SymPy Documentation, Release 1.3

No other Python object (list, dictionary, generator, Python sets) provides the flexibility of
mathematical sets which our sets module tries to emulate. The second reason to use sets is
that they are close to the entities which mathematicians deal with and it makes it easier to
reason about them. Set objects conform to Pythonic conventions when possible, i.e., x in A
and for i in A both work when they can be computed. Another advantage of using objects
closer to mathematical entities is that the user won’t have to “learn” our representation and
she can have her expectations transferred from her mathematical experience.
For the multivariate case we represent solutions as a set of points in a n-dimensional space
and a point is represented by a FiniteSet of ordered tuples, which is a point in Rn or Cn .
Please note that, the general FiniteSet is unordered, but a FiniteSet with a tuple as its only
argument becomes ordered, since a tuple is ordered. So the order in the tuple is mapped to
a pre-defined order of variables while returning solutions.
For example:

>>> from sympy import FiniteSet

>>> FiniteSet(1, 2, 3) # Unordered
{1, 2, 3}
>>> FiniteSet((1, 2, 3)) # Ordered
{(1, 2, 3)}

Why not use dicts as output?

Dictionary are easy to deal with programmatically but mathematically they are not
very precise and use of them can quickly lead to inconsistency and a lot of confusion.
For example:
• There are a lot of cases where we don’t know the complete solution and we may
like to output a partial solution, consider the equation f g = 0. The solution of
this equation is the union of the solution of the following two equations: f = 0,
g = 0. Let’s say that we are able to solve f = 0 but solving g = 0 isn’t supported
yet. In this case we cannot represent partial solution of the given equation
f g = 0 using dicts. This problem is solved with sets using a ConditionSet
object:
solf ∪ {x|x R∧g = 0}, where solf is the solution of the equation f = 0.
• Using a dict may lead to surprising results like:
– solve(Eq(x**2, 1), x) != solve(Eq(y**2, 1), y)
Mathematically, this doesn’t make sense. Using FiniteSet here solves the
problem.
• It also cannot represent solutions for equations like |x| < 1, which is a disk
of radius 1 in the Argand Plane. This problem is solved using complex sets
implemented as ComplexRegion.

5.35.4 Input API of solveset

solveset has a cleaner input API, unlike solve. It takes a maximum of three arguments:
solveset(equation, variable=None, domain=S.Complexes)
• Equation(s)
The equation(s) to solve.

1378 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• Variable(s)
The variable(s) for which the equation is to be solved.
• Domain
The domain in which the equation is to be solved.
solveset removes the flags argument of solve, which had made the input API
messy and output API inconsistent.

5.35.5 What is this domain argument about?

Solveset is designed to be independent of the assumptions on the variable being

solved for and instead, uses the domain argument to decide the solver to dispatch
the equation to, namely solveset_real or solveset_complex. It’s unlike the old
solve which considers the assumption on the variable.

>>> from sympy import solveset, S

>>> from sympy.abc import x
>>> solveset(x**2 + 1, x) # domain=S.Complexes is default
{-I, I}
>>> solveset(x**2 + 1, x, domain=S.Reals)
EmptySet()

5.35.6 What are the general methods employed by solveset to solve

an equation?

Solveset uses various methods to solve an equation, here is a brief overview of the
methodology:
• The domain argument is first considered to know the domain in which the user
is interested to get the solution.
• If the given function is a relational (>=, <=, >, <), and the domain is real, then
solve_univariate_inequality and solutions are returned. Solving for com-
plex solutions of inequalities, like x2 < 0 is not yet supported.
• Based on the domain, the equation is dispatched to one of the two functions
solveset_real or solveset_complex, which solves the given equation in the
complex or real domain, respectively.
• If the given expression is a product of two or more functions, like say gh =
0, then the solution to the given equation is the Union of the solution of the
equations g = 0 and h = 0, if and only if both g and h are finite for a finite input.
So, the solution is built up recursively.
• If the function is trigonometric or hyperbolic, the function _solve_real_trig
is called, which solves it by converting it to complex exponential form.
• The function is now checked if there is any instance of a Piecewise expression,
if it is, then it’s converted to explicit expression and set pairs and then solved
recursively.
• The respective solver now tries to invert the equation using the routines in-
vert_real and invert_complex. These routines are based on the concept of
mathematical inverse (though not exactly). It reduces the real/complex valued

5.35. Solveset 1379

SymPy Documentation, Release 1.3

equation f (x) = y to a set of equations: {g(x) = h1 (y), g(x) = h2 (y), ..., g(x) = hn (y)}
where g(x) is a simpler function than f (x). There is some work needed to be
done in this to find invert of more complex expressions.
• After the invert, the equations are checked for radical or Abs (Modulus), then
the method _solve_radical tries to simplify the radical, by removing it using
techniques like squaring, cubing etc, and _solve_abs solves nested Modulus
by considering the positive and negative variants, iteratively.
• If none of the above method is successful, then methods of polynomial is used
as follows:
– The method to solve the rational function, _solve_as_rational, is called.
Based on the domain, the respective poly solver _solve_as_poly_real or
_solve_as_poly_complex is called to solve f as a polynomial.
– The underlying method _solve_as_poly solves the equation using polyno-
mial techniques if it’s already a polynomial equation or, with a change of
variables, can be made so.
• The final solution set returned by solveset is the intersection of the set of
solutions found above and the input domain.

5.35.7 How do we manipulate and return an infinite solution?

• In the real domain, we use our ImageSet class in the sets module to return infinite so-
lutions. ImageSet is an image of a set under a mathematical function. For example, to
represent the solution of the equation sin (x) = 0, we can use the ImageSet as:

>>> from sympy import ImageSet, Lambda, pi, S, Dummy, pprint

>>> n = Dummy('n')
>>> pprint(ImageSet(Lambda(n, 2*pi*n), S.Integers), use_unicode=True)
{2⋅n⋅π | n ∊ ℤ}

Where n is a dummy variable. It is basically the image of the set of integers under the
function 2πn.
• In the complex domain, we use complex sets, which are implemented as the ComplexRe-
gion class in the sets module, to represent infinite solution in the Argand plane. For
example to represent the solution of the equation |z| = 1, which is a unit circle, we can
use the ComplexRegion as:

>>> from sympy import ComplexRegion, FiniteSet, Interval, pi, pprint

>>> pprint(ComplexRegion(FiniteSet(1)*Interval(0, 2*pi), polar=True), use_
,→unicode=True)

{r⋅(i⋅sin(θ) + cos(θ)) | r, θ ∊ {1} × [0, 2⋅π)}

Where the FiniteSet in the ProductSet is the range of the value of r, which is the radius
of the circle and the Interval is the range of θ, the angle from the x axis representing a
unit circle in the Argand plane.
Note: We also have non-polar form notation for representing solution in rectangular
form. For example, to represent first two quadrants in the Argand plane, we can write
the ComplexRegion as:

1380 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import ComplexRegion, Interval, pi, oo, pprint

>>> pprint(ComplexRegion(Interval(-oo, oo)*Interval(0, oo)), use_unicode=True)
{x + y⋅i | x, y ∊ (-∞, ∞) × [0, ∞)}

where the Intervals are the range of x and y for the set of complex numbers x + iy.

5.35.8 How does solveset ensure that it is not returning any wrong
solution?

Solvers in a Computer Algebra System are based on heuristic algorithms, so it’s

usually very hard to ensure 100% percent correctness, in every possible case. How-
ever there are still a lot of cases where we can ensure correctness. Solveset tries
to verify correctness wherever it can. For example:
Consider the equation |x| = n. A naive method to solve this equation would return
{-n, n} as its solution, which is not correct since {-n, n} can be its solution if and
only if n is positive. Solveset returns this information as well to ensure correctness.
>>> from sympy import symbols, S, pprint, solveset
>>> x, n = symbols('x, n')
>>> pprint(solveset(abs(x) - n, x, domain=S.Reals), use_unicode=True)
{x | x ∊ {-n, n} ∧ (n ∈ [0, ∞))}

Though, there still a lot of work needs to be done in this regard.

5.35.9 Search based solver and step-by-step solution

Note: This is under Development.

After the introduction of ConditionSet, the solving of equations can be seen as set
transformations. Here is an abstract view of the things we can do to solve equations.
• Apply various set transformations on the given set.
• Define a metric of the usability of solutions, or a notion of some solutions being
better than others.
• Different transformations would be the nodes of a tree.
• Suitable searching techniques could be applied to get the best solution.
ConditionSet gives us the ability to represent unevaluated equations and inequal-
ities in forms like {x|f (x) = 0; x ∈ S} and {x|f (x) > 0; x ∈ S} but a more powerful thing
about ConditionSet is that it allows us to write the intermediate steps as set to set
transformation. Some of the transformations are:
• Composition: {x|f (g(x)) = 0; x ∈ S} ⇒ {x|g(x) = y; x ∈ S, y ∈ {z|f (z) = 0; z ∈ S}}
• Polynomial Solver: {x|P (x) = 0; x ∈ S} ⇒ {x1 , x2 , ..., xn } ∩ S, where xi are roots
of P (x).
• Invert solver: {x|f (x) = 0; x ∈ S} ⇒ {g(0)| all g such that f (g(x)) = x}
• logcombine: {x| log(f (x)) + log(g(x)); x ∈ S} ⇒ {x| log(f (x).g(x)); x ∈ S} if f (x) >
0 and g(x) > 0 ⇒ {x| log(f (x)) + log(g(x)); x ∈ S} otherwise
• product solve: {x|f (x)g(x) = 0; x ∈ S} ⇒ {x|f (x) = 0; x ∈ S}U {x|g(x) = 0; x ∈ S}
given f (x) and g(x) are bounded. ⇒ {x|f (x)g(x) = 0; x ∈ S}, otherwise

5.35. Solveset 1381

SymPy Documentation, Release 1.3

Since the output type is same as the input type any composition of these transfor-
mations is also a valid transformation. And our aim is to find the right sequence of
compositions (given the atoms) which transforms the given condition set to a set
which is not a condition set i.e., FiniteSet, Interval, Set of Integers and their Union,
Intersection, Complement or ImageSet. We can assign a cost function to each set,
such that, the more desirable that form of set is to us, the less the value of the cost
function. This way our problem is now reduced to finding the path from the initial
ConditionSet to the lowest valued set on a graph where the atomic transformations
forms the edges.

5.35.10 How do we deal with cases where only some of the solutions
are known?

Creating a universal equation solver, which can solve each and every equation we
encounter in mathematics is an ideal case for solvers in a Computer Algebra System.
When cases which are not solved or can only be solved incompletely, a Condition-
Set is used and acts as an unevaluated solveset object.
Note that, mathematically, finding a complete set of solutions for an equation is
undecidable. See Richardson’s theorem.
ConditionSet is basically a Set of elements which satisfy a given condition. For
example, to represent the solutions of the equation in the real domain:

(x2 − 4)(sin(x) + x)

We can represent it as:

{−2, 2}∪{x|x ∈ R∧x + sin(x) = 0}

5.35.11 What will you do with the old solve?

There are still a few things solveset can’t do, which the old solve can, such as
solving non linear multivariate & LambertW type equations. Hence, it’s not yet a
perfect replacement for old solve. The ultimate goal is to:
• Replace solve with solveset once solveset is at least as powerful as solve,
i.e., solveset does everything that solve can do currently, and
• eventually rename solveset to solve.

5.35.12 How are symbolic parameters handled in solveset?

Solveset is in its initial phase of development, so the symbolic parameters aren’t

handled well for all the cases, but some work has been done in this regard to depict
our ideology towards symbolic parameters. As an example, consider the solving of
|x| = n for real x, where n is a symbolic parameter. Solveset returns the value of x
considering the domain of the symbolic parameter n as well:

([0, ∞) ∩ {n}) ∪ ((−∞, 0] ∩ {−n}).

This simply means n is the solution only when it belongs to the Interval [0, ∞) and
−n is the solution only when −n belongs to the Interval (−∞, 0].

1382 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

There are other cases to address too, like solving 2x + (a − 2) for x where a is a
symbolic parameter. As of now, It returns the solution as an intersection with R,
which is trivial, as it doesn’t reveal the domain of a in the solution.
Recently, we have also implemented a function to find the domain of the expression
in a FiniteSet (Intersection with the interval) in which it is not-empty. It is a useful
addition for dealing with symbolic parameters. For example:

>>> from sympy import Symbol, FiniteSet, Interval, not_empty_in, sqrt, oo

>>> from sympy.abc import x
>>> not_empty_in(FiniteSet(x/2).intersect(Interval(0, 1)), x)
Interval(0, 2)
>>> not_empty_in(FiniteSet(x, x**2).intersect(Interval(1, 2)), x)
Union(Interval(-sqrt(2), -1), Interval(1, 2))

5.35.13 References

5.35.14 Solveset Module Reference

Use solveset() (page 1383) to solve equations or expressions (assumed to be equal to 0) for
a single variable. Solving an equation like x2 == 1 can be done as follows:

>>> from sympy import solveset

>>> from sympy import Symbol, Eq
>>> x = Symbol('x')
>>> solveset(Eq(x**2, 1), x)
{-1, 1}

Or one may manually rewrite the equation as an expression equal to 0:

>>> solveset(x**2 - 1, x)
{-1, 1}

The first argument for solveset() (page 1383) is an expression (equal to zero) or an equation
and the second argument is the symbol that we want to solve the equation for.
sympy.solvers.solveset.solveset(f, symbol=None, domain=S.Complexes)
Solves a given inequality or equation with set as output
Parameters f : Expr or a relational.
The target equation or inequality
symbol : Symbol
The variable for which the equation is solved
domain : Set
The domain over which the equation is solved
Returns Set

5.35. Solveset 1383

SymPy Documentation, Release 1.3

A set of values for symbol for which f is True or is equal to zero. An

EmptySet is returned if f is False or nonzero. A ConditionSet is re-
turned as unsolved object if algorithms to evaluate complete solution
are not yet implemented.
solveset claims to be complete in the solution set that it returns.
Raises NotImplementedError
The algorithms to solve inequalities in complex domain are not yet
implemented.
ValueError
The input is not valid.
RuntimeError
It is a bug, please report to the github issue tracker.
See also:

solveset_real (page 1385) solver for real domain

solveset_complex (page 1385) solver for complex domain

Notes

Python interprets 0 and 1 as False and True, respectively, but in this function they refer
to solutions of an expression. So 0 and 1 return the Domain and EmptySet, respectively,
while True and False return the opposite (as they are assumed to be solutions of relational
expressions).

Examples

>>> from sympy import exp, sin, Symbol, pprint, S

>>> from sympy.solvers.solveset import solveset, solveset_real

• The default domain is complex. Not specifying a domain will lead to the solving of
the equation in the complex domain (and this is not affected by the assumptions on
the symbol):

>>> x = Symbol('x')
>>> pprint(solveset(exp(x) - 1, x), use_unicode=False)
{2*n*I*pi | n in Integers}

>>> x = Symbol('x', real=True)

>>> pprint(solveset(exp(x) - 1, x), use_unicode=False)
{2*n*I*pi | n in Integers}

• If you want to use solveset to solve the equation in the real domain, provide a real
domain. (Using solveset_real does this automatically.)

1384 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> R = S.Reals
>>> x = Symbol('x')
>>> solveset(exp(x) - 1, x, R)
{0}
>>> solveset_real(exp(x) - 1, x)
{0}

The solution is mostly unaffected by assumptions on the symbol, but there may be some
slight difference:

>>> pprint(solveset(sin(x)/x,x), use_unicode=False)

({2*n*pi | n in Integers} \ {0}) U ({2*n*pi + pi | n in Integers} \ {0})

>>> p = Symbol('p', positive=True)

>>> pprint(solveset(sin(p)/p, p), use_unicode=False)
{2*n*pi | n in Integers} U {2*n*pi + pi | n in Integers}

• Inequalities can be solved over the real domain only. Use of a complex domain leads
to a NotImplementedError.

>>> solveset(exp(x) > 1, x, R)

Interval.open(0, oo)

sympy.solvers.solveset.solveset_real(f, symbol)
sympy.solvers.solveset.solveset_complex(f, symbol)
sympy.solvers.solveset.invert_real(f_x, y, x, domain=Reals)
Inverts a real-valued function. Same as _invert, but sets the domain to S.Reals before
inverting.
sympy.solvers.solveset.invert_complex(f_x, y, x, domain=S.Complexes)
Reduce the complex valued equation f(x) = y to a set of equations {g(x) = h_1(y),
g(x) = h_2(y), ..., g(x) = h_n(y) } where g(x) is a simpler function than f(x).
The return value is a tuple (g(x), set_h), where g(x) is a function of x and set_h
is the set of function {h_1(y), h_2(y), ..., h_n(y)}. Here, y is not necessarily a
symbol.
The set_h contains the functions, along with the information about the domain in which
they are valid, through set operations. For instance, if y = Abs(x) - n is inverted in
the real domain, then set_h is not simply −n, n as the nature of n is unknown; rather, it
is: Intersection([0, oo)n)U Intersection((−oo, 0], −n)
By default, the complex domain is used which means that inverting even seemingly sim-
ple functions like exp(x) will give very different results from those obtained in the real
domain. (In the case of exp(x), the inversion via log is multi-valued in the complex
domain, having infinitely many branches.)
If you are working with real values only (or you are not sure which function to use) you
should probably set the domain to S.Reals (or use invert_real which does that automati-
cally).
See also:
invert_real (page 1385), invert_complex (page 1385)

5.35. Solveset 1385

SymPy Documentation, Release 1.3

Examples

>>> from sympy.solvers.solveset import invert_complex, invert_real

>>> from sympy.abc import x, y
>>> from sympy import exp, log

When does exp(x) == y?

>>> invert_complex(exp(x), y, x)
(x, ImageSet(Lambda(_n, I*(2*_n*pi + arg(y)) + log(Abs(y))), Integers))
>>> invert_real(exp(x), y, x)
(x, Intersection(Reals, {log(y)}))

When does exp(x) == 1?

>>> invert_complex(exp(x), 1, x)
(x, ImageSet(Lambda(_n, 2*_n*I*pi), Integers))
>>> invert_real(exp(x), 1, x)
(x, {0})

sympy.solvers.solveset.domain_check(f, symbol, p)
Returns False if point p is infinite or any subexpression of f is infinite or becomes so after
replacing symbol with p. If none of these conditions is met then True will be returned.

Examples

>>> from sympy import Mul, oo

>>> from sympy.abc import x
>>> from sympy.solvers.solveset import domain_check
>>> g = 1/(1 + (1/(x + 1))**2)
>>> domain_check(g, x, -1)
False
>>> domain_check(x**2, x, 0)
True
>>> domain_check(1/x, x, oo)
False

• The function relies on the assumption that the original form of the equation has not
been changed by automatic simplification.

>>> domain_check(x/x, x, 0) # x/x is automatically simplified to 1

True

• To deal with automatic evaluations use evaluate=False:

>>> domain_check(Mul(x, 1/x, evaluate=False), x, 0)

False

5.35.15 linear_eq_to_matrix

sympy.solvers.solveset.linear_eq_to_matrix(equations, *symbols)
Converts a given System of Equations into Matrix form. Here equations must be a linear

1386 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

system of equations in symbols. The order of symbols in input symbols will determine the
order of coefficients in the returned Matrix.
The Matrix form corresponds to the augmented matrix form. For example:

4x + 2y + 3z = 1

3x + y + z = −6

2x + 4y + 9z = 2
This system would return A & b as given below:
[ 4 2 3 ] [ 1 ]
A = [ 3 1 1 ] b = [-6 ]
[ 2 4 9 ] [ 2 ]

Examples

>>> from sympy import linear_eq_to_matrix, symbols

>>> x, y, z = symbols('x, y, z')
>>> eqns = [x + 2*y + 3*z - 1, 3*x + y + z + 6, 2*x + 4*y + 9*z - 2]
>>> A, b = linear_eq_to_matrix(eqns, [x, y, z])
>>> A
Matrix([
[1, 2, 3],
[3, 1, 1],
[2, 4, 9]])
>>> b
Matrix([
[ 1],
[-6],
[ 2]])
>>> eqns = [x + z - 1, y + z, x - y]
>>> A, b = linear_eq_to_matrix(eqns, [x, y, z])
>>> A
Matrix([
[1, 0, 1],
[0, 1, 1],
[1, -1, 0]])
>>> b
Matrix([
[1],
[0],
[0]])

• Symbolic coefficients are also supported

>>> a, b, c, d, e, f = symbols('a, b, c, d, e, f')

>>> eqns = [a*x + b*y - c, d*x + e*y - f]
>>> A, B = linear_eq_to_matrix(eqns, x, y)
>>> A
Matrix([
[a, b],
[d, e]])
(continues on next page)

5.35. Solveset 1387

SymPy Documentation, Release 1.3

(continued from previous page)

>>> B
Matrix([
[c],
[f]])

5.35.16 linsolve

sympy.solvers.solveset.linsolve(system, *symbols)
Solve system of N linear equations with M variables, which means both under - and
overdetermined systems are supported. The possible number of solutions is zero, one or
infinite. Zero solutions throws a ValueError, where as infinite solutions are represented
parametrically in terms of given symbols. For unique solution a FiniteSet of ordered
tuple is returned.
All Standard input formats are supported: For the given set of Equations, the respective
input types are given below:

3x + 2y − z = 1

2x − 2y + 4z = −2

2x − y + 2z = 0
• Augmented Matrix Form, system given below:

[3 2 -1 1]
system = [2 -2 4 -2]
[2 -1 2 0]

• List Of Equations Form

system = [3x + 2y − z − 1, 2x − 2y + 4z + 2, 2x − y + 2z]

• Input A & b Matrix Form (from Ax = b) are given as below:

[3 2 -1 ] [ 1 ]
A = [2 -2 4 ] b = [ -2 ]
[2 -1 2 ] [ 0 ]

system = (A, b)
Symbols can always be passed but are actually only needed when 1) a system of equations
is being passed and 2) the system is passed as an underdetermined matrix and one wants
to control the name of the free variables in the result. An error is raised if no symbols are
used for case 1, but if no symbols are provided for case 2, internally generated symbols
will be provided. When providing symbols for case 2, there should be at least as many
symbols are there are columns in matrix A.
The algorithm used here is Gauss-Jordan elimination, which results, after elimination, in
a row echelon form matrix.
Returns A FiniteSet containing an ordered tuple of values for the
unknowns for which the system has a solution. (Wrapping
the tuple in FiniteSet is used to maintain a consistent

1388 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

output format throughout solveset.)

Returns EmptySet(), if the linear system is inconsistent.
Raises ValueError
The input is not valid. The symbols are not given.

Examples

>>> from sympy import Matrix, S, linsolve, symbols

>>> x, y, z = symbols(”x, y, z”)
>>> A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 10]])
>>> b = Matrix([3, 6, 9])
>>> A
Matrix([
[1, 2, 3],
[4, 5, 6],
[7, 8, 10]])
>>> b
Matrix([
[3],
[6],
[9]])
>>> linsolve((A, b), [x, y, z])
{(-1, 2, 0)}

• Parametric Solution: In case the system is underdetermined, the function will return
a parametric solution in terms of the given symbols. Those that are free will be
returned unchanged. e.g. in the system below, z is returned as the solution for
variable z; it can take on any value.

>>> A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

>>> b = Matrix([3, 6, 9])
>>> linsolve((A, b), x, y, z)
{(z - 1, -2*z + 2, z)}

If no symbols are given, internally generated symbols will be used. The tau0 in the 3rd
position indicates (as before) that the 3rd variable – whatever it’s named – can take on
any value:

>>> linsolve((A, b))

{(tau0 - 1, -2*tau0 + 2, tau0)}

• List of Equations as input

>>> Eqns = [3*x + 2*y - z - 1, 2*x - 2*y + 4*z + 2, - x + y/2 - z]

>>> linsolve(Eqns, x, y, z)
{(1, -2, -2)}

• Augmented Matrix as input

5.35. Solveset 1389

SymPy Documentation, Release 1.3

>>> aug = Matrix([[2, 1, 3, 1], [2, 6, 8, 3], [6, 8, 18, 5]])

>>> aug
Matrix([
[2, 1, 3, 1],
[2, 6, 8, 3],
[6, 8, 18, 5]])
>>> linsolve(aug, x, y, z)
{(3/10, 2/5, 0)}

• Solve for symbolic coefficients

>>> a, b, c, d, e, f = symbols('a, b, c, d, e, f')

>>> eqns = [a*x + b*y - c, d*x + e*y - f]
>>> linsolve(eqns, x, y)
{((-b*f + c*e)/(a*e - b*d), (a*f - c*d)/(a*e - b*d))}

• A degenerate system returns solution as set of given symbols.

>>> system = Matrix(([0, 0, 0], [0, 0, 0], [0, 0, 0]))

>>> linsolve(system, x, y)
{(x, y)}

• For an empty system linsolve returns empty set

>>> linsolve([], x)
EmptySet()

5.35.17 nonlinsolve

sympy.solvers.solveset.nonlinsolve(system, *symbols)
Solve system of N non linear equations with M variables, which means both under and
overdetermined systems are supported. Positive dimensional system is also supported
(A system with infinitely many solutions is said to be positive-dimensional). In Positive
dimensional system solution will be dependent on at least one symbol. Returns both real
solution and complex solution(If system have). The possible number of solutions is zero,
one or infinite.
Parameters system : list of equations
The target system of equations
symbols : list of Symbols
symbols should be given as a sequence eg. list
Returns A FiniteSet of ordered tuple of values of symbols for which the system
has solution. Order of values in the tuple is same as symbols present in
the parameter symbols.
Please note that general FiniteSet is unordered, the solution returned
here is not simply a FiniteSet of solutions, rather it is a FiniteSet of
ordered tuple, i.e. the first & only argument to FiniteSet is a tuple of

1390 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

solutions, which is ordered, & hence the returned solution is ordered.

Also note that solution could also have been returned as an ordered tuple,
FiniteSet is just a wrapper around the tuple. It has no other
significance except for the fact it is just used to maintain a consistent
output format throughout the solveset.
For the given set of Equations, the respective input types
are given below:

x∗y−1=0

4 ∗ x ∗ ∗2 + y ∗ ∗2 − 5 = 0
system = [x ∗ y − 1, 4 ∗ x ∗ ∗2 + y ∗ ∗2 − 5]
symbols = [x, y]
Raises ValueError
The input is not valid. The symbols are not given.
AttributeError
The input symbols are not Symbol type.

Examples

>>> from sympy.core.symbol import symbols

>>> from sympy.solvers.solveset import nonlinsolve
>>> x, y, z = symbols('x, y, z', real=True)
>>> nonlinsolve([x*y - 1, 4*x**2 + y**2 - 5], [x, y])
{(-1, -1), (-1/2, -2), (1/2, 2), (1, 1)}

1. Positive dimensional system and complements:

>>> from sympy import pprint

>>> from sympy.polys.polytools import is_zero_dimensional
>>> a, b, c, d = symbols('a, b, c, d', real=True)
>>> eq1 = a + b + c + d
>>> eq2 = a*b + b*c + c*d + d*a
>>> eq3 = a*b*c + b*c*d + c*d*a + d*a*b
>>> eq4 = a*b*c*d - 1
>>> system = [eq1, eq2, eq3, eq4]
>>> is_zero_dimensional(system)
False
>>> pprint(nonlinsolve(system, [a, b, c, d]), use_unicode=False)
-1 1 1 -1
{(---, -d, -, {d} \ {0}), (-, -d, ---, {d} \ {0})}
d d d d
>>> nonlinsolve([(x+y)**2 - 4, x + y - 2], [x, y])
{(-y + 2, y)}

2. If some of the equations are non polynomial equation then nonlinsolve will call
substitution function and returns real and complex solutions, if present.

5.35. Solveset 1391

SymPy Documentation, Release 1.3

>>> from sympy import exp, sin

>>> nonlinsolve([exp(x) - sin(y), y**2 - 4], [x, y])
{(log(sin(2)), 2), (ImageSet(Lambda(_n, I*(2*_n*pi + pi) +
log(sin(2))), Integers), -2), (ImageSet(Lambda(_n, 2*_n*I*pi +
Mod(log(sin(2)), 2*I*pi)), Integers), 2)}

3. If system is Non linear polynomial zero dimensional then it returns both solution (real
and complex solutions, if present using solvep olys ystem):

>>> from sympy import sqrt

>>> nonlinsolve([x**2 - 2*y**2 -2, x*y - 2], [x, y])
{(-2, -1), (2, 1), (-sqrt(2)*I, sqrt(2)*I), (sqrt(2)*I, -sqrt(2)*I)}

4. nonlinsolve can solve some linear(zero or positive dimensional) system (because it is

using groebner function to get the groebner basis and then substitution function basis as
the new system). But it is not recommended to solve linear system using nonlinsolve,
because linsolve is better for all kind of linear system.

>>> nonlinsolve([x + 2*y -z - 3, x - y - 4*z + 9 , y + z - 4], [x, y, z])

{(3*z - 5, -z + 4, z)}

5. System having polynomial equations and only real solution is present (will be solved
using solvep olys ystem):

>>> e1 = sqrt(x**2 + y**2) - 10

>>> e2 = sqrt(y**2 + (-x + 10)**2) - 3
>>> nonlinsolve((e1, e2), (x, y))
{(191/20, -3*sqrt(391)/20), (191/20, 3*sqrt(391)/20)}
>>> nonlinsolve([x**2 + 2/y - 2, x + y - 3], [x, y])
{(1, 2), (1 + sqrt(5), -sqrt(5) + 2), (-sqrt(5) + 1, 2 + sqrt(5))}
>>> nonlinsolve([x**2 + 2/y - 2, x + y - 3], [y, x])
{(2, 1), (2 + sqrt(5), -sqrt(5) + 1), (-sqrt(5) + 2, 1 + sqrt(5))}

6. It is better to use symbols instead of Trigonometric Function or Function (e.g. replace

sin(x) with symbol, replace f (x) with symbol and so on. Get soln from nonlinsolve and then
using solveset get the value of x)

How Nonlinsolve Is Better Than Old Solver s olves ystem :

1. A positive dimensional system solver : nonlinsolve can return solution for positive di-
mensional system. It finds the Groebner Basis of the positive dimensional system(calling
it as basis) then we can start solving equation(having least number of variable first in the
basis) using solveset and substituting that solved solutions into other equation(of basis)
to get solution in terms of minimum variables. Here the important thing is how we are
substituting the known values and in which equations.
2. Real and Complex both solutions : nonlinsolve returns both real and complex solu-
tion. If all the equations in the system are polynomial then using solvep olys ystem both
real and complex solution is returned. If all the equations in the system are not poly-
nomial equation then goes to substitution method with this polynomial and non polyno-
mial equation(s), to solve for unsolved variables. Here to solve for particular variable
solveset_real and solveset_complex is used. For both real and complex solution function
s olveu singk nowv alues is used inside substitution function.(substitution function will be called
when there is any non polynomial equation(s) is present). When solution is valid then
add its general solution in the final result.

1392 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

3. Complement and Intersection will be added if any : nonlinsolve maintains dict for
complements and Intersections. If solveset find complements or/and Intersection with
any Interval or set during the execution of substitution function ,then complement or/and
Intersection for that variable is added before returning final solution.

5.35.18 transolve

sympy.solvers.solveset._transolve(f, symbol, domain)

Function to solve transcendental equations. It is a helper to solveset and should be used
internally. _transolve currently supports the following class of equations:
• Exponential equations
• Logarithmic equations

Parameters f : Any transcendental equation that needs to be solved.

This needs to be an expression, which is assumed to be equal to 0.
symbol : The variable for which the equation is solved.
This needs to be of class Symbol.
domain : A set over which the equation is solved.
This needs to be of class Set.
Returns Set
A set of values for symbol for which f is equal to zero. An EmptySet
is returned if f does not have solutions in respective domain. A
ConditionSet is returned as unsolved object if algorithms to evaluate
complete solution are not yet implemented.

Examples

>>> from sympy.solvers.solveset import _transolve as transolve

>>> from sympy.solvers.solvers import _tsolve as tsolve
>>> from sympy import symbols, S, pprint
>>> x = symbols('x', real=True) # assumption added
>>> transolve(5**(x - 3) - 3**(2*x + 1), x, S.Reals)
{-(log(3) + 3*log(5))/(-log(5) + 2*log(3))}

How To Use _transolve

_transolve should not be used as an independent function, because it assumes that the
equation (f ) and the symbol comes from solveset and might have undergone a few modi-
fication(s). To use _transolve as an independent function the equation (f ) and the symbol
should be passed as they would have been by solveset.

How _transolve Works

_transolve uses two types of helper functions to solve equations of a particular class:

5.35. Solveset 1393

SymPy Documentation, Release 1.3

Identifying helpers: To determine whether a given equation belongs to a certain class of

equation or not. Returns either True or False.
Solving helpers: Once an equation is identified, a corresponding helper either solves the
equation or returns a form of the equation that solveset might better be able to handle.
• Philosophy behind the module
The purpose of _transolve is to take equations which are not already polynomial in their
generator(s) and to either recast them as such through a valid transformation or to solve
them outright. A pair of helper functions for each class of supported transcendental
functions are employed for this purpose. One identifies the transcendental form of an
equation and the other either solves it or recasts it into a tractable form that can be
solved by solveset. For example, an equation in the form a ∗ b ∗ ∗f (x) − c ∗ d ∗ ∗g(x) = 0 can
be transformed to log(a) + f (x) ∗ log(b) − log(c) − g(x) ∗ log(d) = 0 (under certain assumptions)
and this can be solved with solveset if f (x) and g(x) are in polynomial form.

How _transolve Is Better Than _tsolve

1) Better output

_transolve provides expressions in a more simplified form.

Consider a simple exponential equation

>>> f = 3**(2*x) - 2**(x + 3)

>>> pprint(transolve(f, x, S.Reals), use_unicode=False)
-3*log(2)
{------------------}
-2*log(3) + log(2)
>>> pprint(tsolve(f, x), use_unicode=False)
/ 3 \
| --------|
| log(2/9)|
[-log\2 /]

2) Extensible

The API of _transolve is designed such that it is easily extensible, i.e. the code that solves
a given class of equations is encapsulated in a helper and not mixed in with the code of
_transolve itself.
3) Modular
_transolve is designed to be modular i.e, for every class of equation a separate helper for
identification and solving is implemented. This makes it easy to change or modify any
of the method implemented directly in the helpers without interfering with the actual
structure of the API.
4) Faster Computation
Solving equation via _transolve is much faster as compared to _tsolve. In solve, attempts
are made computing every possibility to get the solutions. This series of attempts makes
solving a bit slow. In _transolve, computation begins only after a particular type of equa-
tion is identified.

1394 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

How To Add New Class Of Equations

Adding a new class of equation solver is a three-step procedure:

• Identify the type of the equations
Determine the type of the class of equations to which they belong: it could be of
Add, P ow, etc. types. Separate internal functions are used for each type. Write
identification and solving helpers and use them from within the routine for the given
type of equation (after adding it, if necessary). Something like:

def add_type(lhs, rhs, x):

....
if _is_exponential(lhs, x):
new_eq = _solve_exponential(lhs, rhs, x)
....
rhs, lhs = eq.as_independent(x)
if lhs.is_Add:
result = add_type(lhs, rhs, x)

• Define the identification helper.

• Define the solving helper.
Apart from this, a few other things needs to be taken care while adding an equation
solver:
• Naming conventions: Name of the identification helper should be as _is_class where
class will be the name or abbreviation of the class of equation. The solving helper
will be named as _solve_class. For example: for exponential equations it becomes
_is_exponential and _solve_expo.
• The identif yinghelpers would require an additional domain parameter.
• Be sure to consider corner cases.
• Add tests for each helper.
• Add a docstring to your helper that describes the method implemented. The docu-
mentation of the helpers should identify:
– the purpose of the helper,
– the method used to identify and solve the equation,
– a proof of correctness
– the return values of the helpers
sympy.solvers.solveset._is_exponential(f, symbol)
Return True if one or more terms contain symbol only in exponents, else False.
Parameters f : Expr
The equation to be checked
symbol : Symbol
The variable in which the equation is checked

5.35. Solveset 1395

SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, cos, exp

>>> from sympy.solvers.solveset import _is_exponential as check
>>> x, y = symbols('x y')
>>> check(y, y)
False
>>> check(x**y - 1, y)
True
>>> check(x**y*2**y - 1, y)
True
>>> check(exp(x + 3) + 3**x, x)
True
>>> check(cos(2**x), x)
False

• Philosophy behind the helper

The function extracts each term of the equation and checks if it is of exponential form
w.r.t symbol.
sympy.solvers.solveset._solve_exponential(lhs, rhs, symbol, domain)
Helper function for solving (supported) exponential equations.
Exponential equations are the sum of (currently) at most two terms with one or both of
them having a power with a symbol-dependent exponent.
For example

52x+3 − 53x−1

45−9x − e2−x
Parameters lhs, rhs : Expr
The exponential equation to be solved, lhs = rhs
symbol : Symbol
The variable in which the equation is solved
domain : Set
A set over which the equation is solved.
Returns A set of solutions satisfying the given equation.
A ConditionSet if the equation is unsolvable or
if the assumptions are not properly defined, in that case
a different style of ConditionSet is returned having the
solution(s) of the equation with the desired assumptions.

Examples

1396 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.solvers.solveset import _solve_exponential as solve_expo

>>> from sympy import symbols, S
>>> x = symbols('x', real=True)
>>> a, b = symbols('a b')
>>> solve_expo(2**x + 3**x - 5**x, 0, x, S.Reals) # not solvable
ConditionSet(x, Eq(2**x + 3**x - 5**x, 0), Reals)
>>> solve_expo(a**x - b**x, 0, x, S.Reals) # solvable but incorrect assumptions
ConditionSet(x, (a > 0) & (b > 0), {0})
>>> solve_expo(3**(2*x) - 2**(x + 3), 0, x, S.Reals)
{-3*log(2)/(-2*log(3) + log(2))}
>>> solve_expo(2**x - 4**x, 0, x, S.Reals)
{0}

• Proof of correctness of the method

The logarithm function is the inverse of the exponential function. The defining relation
between exponentiation and logarithm is:
logb x = y if by = x

Therefore if we are given an equation with exponent terms, we can convert every term
to its corresponding log form. This is achieved by taking logarithms and expanding the
equation using log identities so that it can easily be handled by solveset.
For example:
32x = 2x+3
Taking log both sides will reduce the equation to
(2x) ∗ log(3) = (x + 3) ∗ log(2)

This form can be easily handed by solveset.

sympy.solvers.solveset._solve_logarithm(lhs, rhs, symbol, domain)
Helper to solve logarithmic equations which are reducible to a single instance of log.
Logarithmic equations are (currently) the equations that contains log terms which can
be reduced to a single log term or a constant using various logarithmic identities.
For example:
log(x) + log(x − 4)

can be reduced to:

log(x(x − 4))

Parameters lhs, rhs : Expr

The logarithmic equation to be solved, lhs = rhs
symbol : Symbol
The variable in which the equation is solved
domain : Set
A set over which the equation is solved.
Returns A set of solutions satisfying the given equation.
A ConditionSet if the equation is unsolvable.

5.35. Solveset 1397

SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, log, S

>>> from sympy.solvers.solveset import _solve_logarithm as solve_log
>>> x = symbols('x')
>>> f = log(x - 3) + log(x + 3)
>>> solve_log(f, 0, x, S.Reals)
{-sqrt(10), sqrt(10)}

• Proof of correctness

A logarithm is another way to write exponent and is defined by

logb x = y if by = x

When one side of the equation contains a single logarithm, the equation can be solved
by rewriting the equation as an equivalent exponential equation as defined above. But if
one side contains more than one logarithm, we need to use the properties of logarithm
to condense it into a single logarithm.
Take for example

log(2 ∗ x) − 15 = 0

contains single logarithm, therefore we can directly rewrite it to exponential form as

x = exp(15)/2

But if the equation has more than one logarithm as

log(x − 3) + log(x + 3) = 0

we use log identities to convert into a reduced form

Using,

log(a) + log(b) = log(a ∗ b)

therefore the equation becomes,

log((x − 3) ∗ (x + 3))

This equation contains one logarithm and can be solved by rewriting to exponents.
sympy.solvers.solveset._is_logarithmic(f, symbol)
Return True if the equation is in the form a ∗ log(f (x)) + b ∗ log(g(x)) + ... + c else False.
Parameters f : Expr
The equation to be checked
symbol : Symbol
The variable in which the equation is checked
Returns T rue if the equation is logarithmic otherwise F alse.

Examples

1398 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import symbols, tan, log

>>> from sympy.solvers.solveset import _is_logarithmic as check
>>> x, y = symbols('x y')
>>> check(log(x + 2) - log(x + 3), x)
True
>>> check(tan(log(2*x)), x)
False
>>> check(x*log(x), x)
False
>>> check(x + log(x), x)
False
>>> check(y + log(x), x)
True

• Philosophy behind the helper

The function extracts each term and checks whether it is logarithmic w.r.t symbol.

5.35.19 Diophantine Equations (DEs)

See Diophantine (page 1347)

5.35.20 Inequalities

See Inequality Solvers (page 1372)

5.35.21 Ordinary Differential equations (ODEs)

See ODE (page 1262).

5.35.22 Partial Differential Equations (PDEs)

See PDE (page 1319).

5.36 Tensor Module

A module to manipulate symbolic objects with indices including tensors

5.36.1 Contents

N-dim array

N-dim array module for SymPy.

5.36. Tensor Module 1399

SymPy Documentation, Release 1.3

Four classes are provided to handle N-dim arrays, given by the combinations dense/sparse
(i.e. whether to store all elements or only the non-zero ones in memory) and muta-
ble/immutable (immutable classes are SymPy objects, but cannot change after they have been
created).

Examples

The following examples show the usage of Array. This is an abbreviation for Immutable-
DenseNDimArray, that is an immutable and dense N-dim array, the other classes are analo-
gous. For mutable classes it is also possible to change element values after the object has
been constructed.
Array construction can detect the shape of nested lists and tuples:
>>> from sympy import Array
>>> a1 = Array([[1, 2], [3, 4], [5, 6]])
>>> a1
[[1, 2], [3, 4], [5, 6]]
>>> a1.shape
(3, 2)
>>> a1.rank()
2
>>> from sympy.abc import x, y, z
>>> a2 = Array([[[x, y], [z, x*z]], [[1, x*y], [1/x, x/y]]])
>>> a2
[[[x, y], [z, x*z]], [[1, x*y], [1/x, x/y]]]
>>> a2.shape
(2, 2, 2)
>>> a2.rank()
3

Otherwise one could pass a 1-dim array followed by a shape tuple:

>>> m1 = Array(range(12), (3, 4))
>>> m1
[[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11]]
>>> m2 = Array(range(12), (3, 2, 2))
>>> m2
[[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]]
>>> m2[1,1,1]
7
>>> m2.reshape(4, 3)
[[0, 1, 2], [3, 4, 5], [6, 7, 8], [9, 10, 11]]

Slice support:
>>> m2[:, 1, 1]
[3, 7, 11]

Elementwise derivative:
>>> from sympy.abc import x, y, z
>>> m3 = Array([x**3, x*y, z])
>>> m3.diff(x)
[3*x**2, y, 0]
>>> m3.diff(z)
[0, 0, 1]

1400 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Multiplication with other SymPy expressions is applied elementwisely:

>>> (1+x)*m3
[x**3*(x + 1), x*y*(x + 1), z*(x + 1)]

To apply a function to each element of the N-dim array, use applyfunc:

>>> m3.applyfunc(lambda x: x/2)

[x**3/2, x*y/2, z/2]

N-dim arrays can be converted to nested lists by the tolist() method:

>>> m2.tolist()
[[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]]
>>> isinstance(m2.tolist(), list)
True

If the rank is 2, it is possible to convert them to matrices with tomatrix():

>>> m1.tomatrix()
Matrix([
[0, 1, 2, 3],
[4, 5, 6, 7],
[8, 9, 10, 11]])

Products and contractions

Tensor product between arrays Ai1 ,...,in and Bj1 ,...,jm creates the combined array P = A ⊗ B
defined as
Pi1 ,...,in ,j1 ,...,jm := Ai1 ,...,in · Bj1 ,...,jm .
It is available through tensorproduct(...):

>>> from sympy import Array, tensorproduct

>>> from sympy.abc import x,y,z,t
>>> A = Array([x, y, z, t])
>>> B = Array([1, 2, 3, 4])
>>> tensorproduct(A, B)
[[x, 2*x, 3*x, 4*x], [y, 2*y, 3*y, 4*y], [z, 2*z, 3*z, 4*z], [t, 2*t, 3*t, 4*t]]

Tensor product between a rank-1 array and a matrix creates a rank-3 array:

>>> from sympy import eye

>>> p1 = tensorproduct(A, eye(4))
>>> p1
[[[x, 0, 0, 0], [0, x, 0, 0], [0, 0, x, 0], [0, 0, 0, x]], [[y, 0, 0, 0], [0, y, 0,␣
,→0], [0, 0, y, 0], [0, 0, 0, y]], [[z, 0, 0, 0], [0, z, 0, 0], [0, 0, z, 0], [0, 0,␣

,→0, z]], [[t, 0, 0, 0], [0, t, 0, 0], [0, 0, t, 0], [0, 0, 0, t]]]

Now, to get back A0 ⊗ 1 one can access p0,m,n by slicing:

>>> p1[0,:,:]
[[x, 0, 0, 0], [0, x, 0, 0], [0, 0, x, 0], [0, 0, 0, x]]

Tensor contraction sums over the specified axes, for example contracting positions a and b
means

5.36. Tensor Module 1401

SymPy Documentation, Release 1.3

∑
Ai1 ,...,ia ,...,ib ,...,in =⇒ k Ai1 ,...,k,...,k,...,in
Remember that Python indexing is zero starting, to contract the a-th and b-th axes it is there-
fore necessary to specify a − 1 and b − 1

>>> from sympy import tensorcontraction

>>> C = Array([[x, y], [z, t]])

The matrix trace is equivalent to the contraction of a rank-2 array:

∑
Am,n =⇒ k Ak,k

>>> tensorcontraction(C, (0, 1))

t + x

Matrix product is equivalent to a tensor product of two rank-2 arrays, followed by a contrac-
tion of the 2nd and 3rd axes (in Python indexing axes number 1, 2).
∑
Am,n · Bi,j =⇒ k Am,k · Bk,j

>>> D = Array([[2, 1], [0, -1]])

>>> tensorcontraction(tensorproduct(C, D), (1, 2))
[[2*x, x - y], [2*z, -t + z]]

One may verify that the matrix product is equivalent:

>>> from sympy import Matrix

>>> Matrix([[x, y], [z, t]])*Matrix([[2, 1], [0, -1]])
Matrix([
[2*x, x - y],
[2*z, -t + z]])

or equivalently

>>> C.tomatrix()*D.tomatrix()
Matrix([
[2*x, x - y],
[2*z, -t + z]])

Derivatives by array

The usual derivative operation may be extended to support derivation with respect to arrays,
provided that all elements in the that array are symbols or expressions suitable for derivations.
The definition of a derivative by an array is as follows: given the array Ai1 ,...,iN and the array
Xj1 ,...,jM the derivative of arrays will return a new array B defined by
∂Ai1 ,...,iN
Bj1 ,...,jM ,i1 ,...,iN := ∂Xj1 ,...,jM

The function derive_by_array performs such an operation:

>>> from sympy import derive_by_array

>>> from sympy.abc import x, y, z, t
>>> from sympy import sin, exp

With scalars, it behaves exactly as the ordinary derivative:

1402 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> derive_by_array(sin(x*y), x)
y*cos(x*y)

Scalar derived by an array basis:

>>> derive_by_array(sin(x*y), [x, y, z])

[y*cos(x*y), x*cos(x*y), 0]

∂Am
Deriving array by an array basis: B nm := ∂xn

>>> basis = [x, y, z]

>>> ax = derive_by_array([exp(x), sin(y*z), t], basis)
>>> ax
[[exp(x), 0, 0], [0, z*cos(y*z), 0], [0, y*cos(y*z), 0]]
∑ ∂Am
Contraction of the resulting array: m ∂xm

>>> tensorcontraction(ax, (0, 1))

z*cos(y*z) + exp(x)

Classes

class sympy.tensor.array.ImmutableDenseNDimArray
class sympy.tensor.array.ImmutableSparseNDimArray
class sympy.tensor.array.MutableDenseNDimArray
class sympy.tensor.array.MutableSparseNDimArray

Functions

sympy.tensor.array.derive_by_array(expr, dx)
Derivative by arrays. Supports both arrays and scalars.
Given the array Ai1 ,...,iN and the array Xj1 ,...,jM this function will return a new array B
defined by
∂Ai1 ,...,iN
Bj1 ,...,jM ,i1 ,...,iN := ∂Xj1 ,...,jM

Examples

>>> from sympy import derive_by_array

>>> from sympy.abc import x, y, z, t
>>> from sympy import cos
>>> derive_by_array(cos(x*t), x)
-t*sin(t*x)
>>> derive_by_array(cos(x*t), [x, y, z, t])
[-t*sin(t*x), 0, 0, -x*sin(t*x)]
>>> derive_by_array([x, y**2*z], [[x, y], [z, t]])
[[[1, 0], [0, 2*y*z]], [[0, y**2], [0, 0]]]

5.36. Tensor Module 1403

SymPy Documentation, Release 1.3

sympy.tensor.array.permutedims(expr, perm)
Permutes the indices of an array.
Parameter specifies the permutation of the indices.

Examples

>>> from sympy.abc import x, y, z, t

>>> from sympy import sin
>>> from sympy import Array, permutedims
>>> a = Array([[x, y, z], [t, sin(x), 0]])
>>> a
[[x, y, z], [t, sin(x), 0]]
>>> permutedims(a, (1, 0))
[[x, t], [y, sin(x)], [z, 0]]

If the array is of second order, transpose can be used:

>>> from sympy import transpose

>>> transpose(a)
[[x, t], [y, sin(x)], [z, 0]]

Examples on higher dimensions:

>>> b = Array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])

>>> permutedims(b, (2, 1, 0))
[[[1, 5], [3, 7]], [[2, 6], [4, 8]]]
>>> permutedims(b, (1, 2, 0))
[[[1, 5], [2, 6]], [[3, 7], [4, 8]]]

Permutation objects are also allowed:

>>> from sympy.combinatorics import Permutation

>>> permutedims(b, Permutation([1, 2, 0]))
[[[1, 5], [2, 6]], [[3, 7], [4, 8]]]

sympy.tensor.array.tensorcontraction(array, *contraction_axes)
Contraction of an array-like object on the specified axes.

Examples

>>> from sympy import Array, tensorcontraction

>>> from sympy import Matrix, eye
>>> tensorcontraction(eye(3), (0, 1))
3
>>> A = Array(range(18), (3, 2, 3))
>>> A
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]], [[12, 13, 14], [15, 16, 17]]]
>>> tensorcontraction(A, (0, 2))
[21, 30]

Matrix multiplication may be emulated with a proper combination of tensorcontraction

and tensorproduct

1404 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import tensorproduct

>>> from sympy.abc import a,b,c,d,e,f,g,h
>>> m1 = Matrix([[a, b], [c, d]])
>>> m2 = Matrix([[e, f], [g, h]])
>>> p = tensorproduct(m1, m2)
>>> p
[[[[a*e, a*f], [a*g, a*h]], [[b*e, b*f], [b*g, b*h]]], [[[c*e, c*f], [c*g, c*h]],␣
,→[[d*e, d*f], [d*g, d*h]]]]

>>> tensorcontraction(p, (1, 2))

[[a*e + b*g, a*f + b*h], [c*e + d*g, c*f + d*h]]
>>> m1*m2
Matrix([
[a*e + b*g, a*f + b*h],
[c*e + d*g, c*f + d*h]])

sympy.tensor.array.tensorproduct(*args)
Tensor product among scalars or array-like objects.

Examples

>>> from sympy.tensor.array import tensorproduct, Array

>>> from sympy.abc import x, y, z, t
>>> A = Array([[1, 2], [3, 4]])
>>> B = Array([x, y])
>>> tensorproduct(A, B)
[[[x, y], [2*x, 2*y]], [[3*x, 3*y], [4*x, 4*y]]]
>>> tensorproduct(A, x)
[[x, 2*x], [3*x, 4*x]]
>>> tensorproduct(A, B, B)
[[[[x**2, x*y], [x*y, y**2]], [[2*x**2, 2*x*y], [2*x*y, 2*y**2]]], [[[3*x**2,␣
,→3*x*y], [3*x*y, 3*y**2]], [[4*x**2, 4*x*y], [4*x*y, 4*y**2]]]]

Applying this function on two matrices will result in a rank 4 array.

>>> from sympy import Matrix, eye
>>> m = Matrix([[x, y], [z, t]])
>>> p = tensorproduct(eye(3), m)
>>> p
[[[[x, y], [z, t]], [[0, 0], [0, 0]], [[0, 0], [0, 0]]], [[[0, 0], [0, 0]], [[x,␣
,→y], [z, t]], [[0, 0], [0, 0]]], [[[0, 0], [0, 0]], [[0, 0], [0, 0]], [[x, y],␣

,→[z, t]]]]

Indexed Objects

Module that defines indexed objects

The classes IndexedBase, Indexed, and Idx represent a matrix element M[i, j] as in the
following diagram:
1) The Indexed class represents the entire indexed object.
|
___|___
' '
M[i, j]
(continues on next page)

5.36. Tensor Module 1405

SymPy Documentation, Release 1.3

(continued from previous page)

/ \__\______
| |
| |
| 2) The Idx class represents indices; each Idx can
| optionally contain information about its range.
|
3) IndexedBase represents the 'stem' of an indexed object, here `M`.
The stem used by itself is usually taken to represent the entire
array.

There can be any number of indices on an Indexed object. No

transformation properties are implemented in these Base objects, but
implicit contraction of repeated indices is supported.

Note that the support for complicated (i.e. non-atomic) integer

expressions as indices is limited. (This should be improved in
future releases.)

Examples
========

To express the above matrix element example you would write:

>>> from sympy import symbols, IndexedBase, Idx

>>> M = IndexedBase('M')
>>> i, j = symbols('i j', cls=Idx)
>>> M[i, j]
M[i, j]

Repeated indices in a product implies a summation, so to express a

matrix-vector product in terms of Indexed objects:

>>> x = IndexedBase('x')
>>> M[i, j]*x[j]
M[i, j]*x[j]

If the indexed objects will be converted to component based arrays, e.g.

with the code printers or the autowrap framework, you also need to provide
(symbolic or numerical) dimensions. This can be done by passing an
optional shape parameter to IndexedBase upon construction:

>>> dim1, dim2 = symbols('dim1 dim2', integer=True)

>>> A = IndexedBase('A', shape=(dim1, 2*dim1, dim2))
>>> A.shape
(dim1, 2*dim1, dim2)
>>> A[i, j, 3].shape
(dim1, 2*dim1, dim2)

If an IndexedBase object has no shape information, it is assumed that the

array is as large as the ranges of its indices:

>>> n, m = symbols('n m', integer=True)

>>> i = Idx('i', m)
>>> j = Idx('j', n)
>>> M[i, j].shape
(m, n)

(continues on next page)

1406 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> M[i, j].ranges
[(0, m - 1), (0, n - 1)]

The above can be compared with the following:

>>> A[i, 2, j].shape

(dim1, 2*dim1, dim2)
>>> A[i, 2, j].ranges
[(0, m - 1), None, (0, n - 1)]

To analyze the structure of indexed expressions, you can use the methods
get_indices() and get_contraction_structure():

>>> from sympy.tensor import get_indices, get_contraction_structure

>>> get_indices(A[i, j, j])
({i}, {})
>>> get_contraction_structure(A[i, j, j])
{(j,): {A[i, j, j]}}

See the appropriate docstrings for a detailed explanation of the output.

class sympy.tensor.indexed.Idx
Represents an integer index as an Integer or integer expression.
There are a number of ways to create an Idx object. The constructor takes two argu-
ments:
label An integer or a symbol that labels the index.
range Optionally you can specify a range as either
• Symbol or integer: This is interpreted as a dimension. Lower and upper bounds
are set to 0 and range - 1, respectively.
• tuple: The two elements are interpreted as the lower and upper bounds of the
range, respectively.
Note: bounds of the range are assumed to be either integer or infinite (oo and -oo are
allowed to specify an unbounded range). If n is given as a bound, then n.is_integer
must not return false.
For convenience, if the label is given as a string it is automatically converted to an integer
symbol. (Note: this conversion is not done for range or dimension arguments.)

Examples

>>> from sympy import IndexedBase, Idx, symbols, oo

>>> n, i, L, U = symbols('n i L U', integer=True)

If a string is given for the label an integer Symbol is created and the bounds are both
None:

>>> idx = Idx('qwerty'); idx

qwerty
>>> idx.lower, idx.upper
(None, None)

5.36. Tensor Module 1407

SymPy Documentation, Release 1.3

Both upper and lower bounds can be specified:

>>> idx = Idx(i, (L, U)); idx

i
>>> idx.lower, idx.upper
(L, U)

When only a single bound is given it is interpreted as the dimension and the lower bound
defaults to 0:

>>> idx = Idx(i, n); idx.lower, idx.upper

(0, n - 1)
>>> idx = Idx(i, 4); idx.lower, idx.upper
(0, 3)
>>> idx = Idx(i, oo); idx.lower, idx.upper
(0, oo)

label
Returns the label (Integer or integer expression) of the Idx object.

Examples

>>> from sympy import Idx, Symbol

>>> x = Symbol('x', integer=True)
>>> Idx(x).label
x
>>> j = Symbol('j', integer=True)
>>> Idx(j).label
j
>>> Idx(j + 1).label
j + 1

lower
Returns the lower bound of the Idx.

Examples

>>> from sympy import Idx

>>> Idx('j', 2).lower
0
>>> Idx('j', 5).lower
0
>>> Idx('j').lower is None
True

upper
Returns the upper bound of the Idx.

Examples

1408 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import Idx

>>> Idx('j', 2).upper
1
>>> Idx('j', 5).upper
4
>>> Idx('j').upper is None
True

class sympy.tensor.indexed.Indexed
Represents a mathematical object with indices.

>>> from sympy import Indexed, IndexedBase, Idx, symbols

>>> i, j = symbols('i j', cls=Idx)
>>> Indexed('A', i, j)
A[i, j]

It is recommended that Indexed objects be created via IndexedBase:

>>> A = IndexedBase('A')
>>> Indexed('A', i, j) == A[i, j]
True

base
Returns the IndexedBase of the Indexed object.

Examples

>>> from sympy import Indexed, IndexedBase, Idx, symbols

>>> i, j = symbols('i j', cls=Idx)
>>> Indexed('A', i, j).base
A
>>> B = IndexedBase('B')
>>> B == B[i, j].base
True

indices
Returns the indices of the Indexed object.

Examples

>>> from sympy import Indexed, Idx, symbols

>>> i, j = symbols('i j', cls=Idx)
>>> Indexed('A', i, j).indices
(i, j)

ranges
Returns a list of tuples with lower and upper range of each index.
If an index does not define the data members upper and lower, the corresponding
slot in the list contains None instead of a tuple.

5.36. Tensor Module 1409

SymPy Documentation, Release 1.3

Examples

>>> from sympy import Indexed,Idx, symbols

>>> Indexed('A', Idx('i', 2), Idx('j', 4), Idx('k', 8)).ranges
[(0, 1), (0, 3), (0, 7)]
>>> Indexed('A', Idx('i', 3), Idx('j', 3), Idx('k', 3)).ranges
[(0, 2), (0, 2), (0, 2)]
>>> x, y, z = symbols('x y z', integer=True)
>>> Indexed('A', x, y, z).ranges
[None, None, None]

rank
Returns the rank of the Indexed object.

Examples

>>> from sympy import Indexed, Idx, symbols

>>> i, j, k, l, m = symbols('i:m', cls=Idx)
>>> Indexed('A', i, j).rank
2
>>> q = Indexed('A', i, j, k, l, m)
>>> q.rank
5
>>> q.rank == len(q.indices)
True

shape
Returns a list with dimensions of each index.
Dimensions is a property of the array, not of the indices. Still, if the IndexedBase
does not define a shape attribute, it is assumed that the ranges of the indices corre-
spond to the shape of the array.

>>> from sympy import IndexedBase, Idx, symbols

>>> n, m = symbols('n m', integer=True)
>>> i = Idx('i', m)
>>> j = Idx('j', m)
>>> A = IndexedBase('A', shape=(n, n))
>>> B = IndexedBase('B')
>>> A[i, j].shape
(n, n)
>>> B[i, j].shape
(m, m)

class sympy.tensor.indexed.IndexedBase
Represent the base or stem of an indexed object
The IndexedBase class represent an array that contains elements. The main purpose
of this class is to allow the convenient creation of objects of the Indexed class. The
__getitem__ method of IndexedBase returns an instance of Indexed. Alone, without in-
dices, the IndexedBase class can be used as a notation for e.g. matrix equations, re-
sembling what you could do with the Symbol class. But, the IndexedBase class adds
functionality that is not available for Symbol instances:
• An IndexedBase object can optionally store shape information. This can be used in
to check array conformance and conditions for numpy broadcasting. (TODO)

1410 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• An IndexedBase object implements syntactic sugar that allows easy symbolic repre-
sentation of array operations, using implicit summation of repeated indices.
• The IndexedBase object symbolizes a mathematical structure equivalent to arrays,
and is recognized as such for code generation and automatic compilation and wrap-
ping.

>>> from sympy.tensor import IndexedBase, Idx

>>> from sympy import symbols
>>> A = IndexedBase('A'); A
A
>>> type(A)
<class 'sympy.tensor.indexed.IndexedBase'>

When an IndexedBase object receives indices, it returns an array with named axes, rep-
resented by an Indexed object:

>>> i, j = symbols('i j', integer=True)

>>> A[i, j, 2]
A[i, j, 2]
>>> type(A[i, j, 2])
<class 'sympy.tensor.indexed.Indexed'>

The IndexedBase constructor takes an optional shape argument. If given, it overrides

any shape information in the indices. (But not the index ranges!)

>>> m, n, o, p = symbols('m n o p', integer=True)

>>> i = Idx('i', m)
>>> j = Idx('j', n)
>>> A[i, j].shape
(m, n)
>>> B = IndexedBase('B', shape=(o, p))
>>> B[i, j].shape
(o, p)

label
Returns the label of the IndexedBase object.

Examples

>>> from sympy import IndexedBase

>>> from sympy.abc import x, y
>>> IndexedBase('A', shape=(x, y)).label
A

offset
Returns the offset for the IndexedBase object.
This is the value added to the resulting index when the 2D Indexed object is unrolled
to a 1D form. Used in code generation.

Examples

5.36. Tensor Module 1411

SymPy Documentation, Release 1.3

>>> from sympy.printing import ccode

>>> from sympy.tensor import IndexedBase, Idx
>>> from sympy import symbols
>>> l, m, n, o = symbols('l m n o', integer=True)
>>> A = IndexedBase('A', strides=(l, m, n), offset=o)
>>> i, j, k = map(Idx, 'ijk')
>>> ccode(A[i, j, k])
'A[l*i + m*j + n*k + o]'

shape
Returns the shape of the IndexedBase object.

Examples

>>> from sympy import IndexedBase, Idx, Symbol

>>> from sympy.abc import x, y
>>> IndexedBase('A', shape=(x, y)).shape
(x, y)

Note: If the shape of the IndexedBase is specified, it will override any shape infor-
mation given by the indices.

>>> A = IndexedBase('A', shape=(x, y))

>>> B = IndexedBase('B')
>>> i = Idx('i', 2)
>>> j = Idx('j', 1)
>>> A[i, j].shape
(x, y)
>>> B[i, j].shape
(2, 1)

strides
Returns the strided scheme for the IndexedBase object.
Normally this is a tuple denoting the number of steps to take in the respective di-
mension when traversing an array. For code generation purposes strides=’C’ and
strides=’F’ can also be used.
strides=’C’ would mean that code printer would unroll in row-major order and ‘F’
means unroll in column major order.

Methods

Module with functions operating on IndexedBase, Indexed and Idx objects

• Check shape conformance
• Determine indices in resulting expression
etc.
Methods in this module could be implemented by calling methods on Expr objects instead.
When things stabilize this could be a useful refactoring.
sympy.tensor.index_methods.get_contraction_structure(expr)
Determine dummy indices of expr and describe its structure

1412 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

By dummy we mean indices that are summation indices.

The structure of the expression is determined and described as follows:
1) A conforming summation of Indexed objects is described with a dict where the keys
are summation indices and the corresponding values are sets containing all terms
for which the summation applies. All Add objects in the SymPy expression tree are
described like this.
2) For all nodes in the SymPy expression tree that are not of type Add, the following
applies:
If a node discovers contractions in one of its arguments, the node itself will be stored
as a key in the dict. For that key, the corresponding value is a list of dicts, each of
which is the result of a recursive call to get_contraction_structure(). The list contains
only dicts for the non-trivial deeper contractions, omitting dicts with None as the one
and only key.

Note: The presence of expressions among the dictinary keys indicates multiple levels
of index contractions. A nested dict displays nested contractions and may itself con-
tain dicts from a deeper level. In practical calculations the summation in the deepest
nested level must be calculated first so that the outer expression can access the resulting
indexed object.

Examples

>>> from sympy.tensor.index_methods import get_contraction_structure

>>> from sympy import symbols, default_sort_key
>>> from sympy.tensor import IndexedBase, Idx
>>> x, y, A = map(IndexedBase, ['x', 'y', 'A'])
>>> i, j, k, l = map(Idx, ['i', 'j', 'k', 'l'])
>>> get_contraction_structure(x[i]*y[i] + A[j, j])
{(i,): {x[i]*y[i]}, (j,): {A[j, j]}}
>>> get_contraction_structure(x[i]*y[j])
{None: {x[i]*y[j]}}

A multiplication of contracted factors results in nested dicts representing the internal

contractions.

>>> d = get_contraction_structure(x[i, i]*y[j, j])

>>> sorted(d.keys(), key=default_sort_key)
[None, x[i, i]*y[j, j]]

In this case, the product has no contractions:

>>> d[None]
{x[i, i]*y[j, j]}

Factors are contracted “first”:

>>> sorted(d[x[i, i]*y[j, j]], key=default_sort_key)

[{(i,): {x[i, i]}}, {(j,): {y[j, j]}}]

A parenthesized Add object is also returned as a nested dictionary. The term containing
the parenthesis is a Mul with a contraction among the arguments, so it will be found as

5.36. Tensor Module 1413

SymPy Documentation, Release 1.3

a key in the result. It stores the dictionary resulting from a recursive call on the Add
expression.

>>> d = get_contraction_structure(x[i]*(y[i] + A[i, j]*x[j]))

>>> sorted(d.keys(), key=default_sort_key)
[(A[i, j]*x[j] + y[i])*x[i], (i,)]
>>> d[(i,)]
{(A[i, j]*x[j] + y[i])*x[i]}
>>> d[x[i]*(A[i, j]*x[j] + y[i])]
[{None: {y[i]}, (j,): {A[i, j]*x[j]}}]

Powers with contractions in either base or exponent will also be found as keys in the
dictionary, mapping to a list of results from recursive calls:

>>> d = get_contraction_structure(A[j, j]**A[i, i])

>>> d[None]
{A[j, j]**A[i, i]}
>>> nested_contractions = d[A[j, j]**A[i, i]]
>>> nested_contractions[0]
{(j,): {A[j, j]}}
>>> nested_contractions[1]
{(i,): {A[i, i]}}

The description of the contraction structure may appear complicated when represented
with a string in the above examples, but it is easy to iterate over:

>>> from sympy import Expr

>>> for key in d:
... if isinstance(key, Expr):
... continue
... for term in d[key]:
... if term in d:
... # treat deepest contraction first
... pass
... # treat outermost contactions here

sympy.tensor.index_methods.get_indices(expr)
Determine the outer indices of expression expr
By outer we mean indices that are not summation indices. Returns a set and a dict. The
set contains outer indices and the dict contains information about index symmetries.

Examples

>>> from sympy.tensor.index_methods import get_indices

>>> from sympy import symbols
>>> from sympy.tensor import IndexedBase, Idx
>>> x, y, A = map(IndexedBase, ['x', 'y', 'A'])
>>> i, j, a, z = symbols('i j a z', integer=True)

The indices of the total expression is determined, Repeated indices imply a summation,
for instance the trace of a matrix A:

>>> get_indices(A[i, i])

(set(), {})

1414 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

In the case of many terms, the terms are required to have identical outer indices. Else
an IndexConformanceException is raised.

>>> get_indices(x[i] + A[i, j]*y[j])

({i}, {})

Exceptions

An IndexConformanceException means that the terms ar not compatible, e.g.

>>> get_indices(x[i] + y[j]) #doctest: +SKIP

(...)
IndexConformanceException: Indices are not consistent: x(i) + y(j)

Warning: The concept of outer indices applies recursively, starting on the deepest
level. This implies that dummies inside parenthesis are assumed to be summed first,
so that the following expression is handled gracefully:
>>> get_indices((x[i] + A[i, j]*y[j])*x[j])
({i, j}, {})

This is correct and may appear convenient, but you need to be careful with this as
SymPy will happily .expand() the product, if requested. The resulting expression
would mix the outer j with the dummies inside the parenthesis, which makes it a
different expression. To be on the safe side, it is best to avoid such ambiguities by
using unique indices for all contractions that should be held separate.

Tensor

class sympy.tensor.tensor._TensorManager
Class to manage tensor properties.

Notes

Tensors belong to tensor commutation groups; each group has a label comm; there are
predefined labels:
0 tensors commuting with any other tensor
1 tensors anticommuting among themselves
2 tensors not commuting, apart with those with comm=0
Other groups can be defined using set_comm; tensors in those groups commute with
those with comm=0; by default they do not commute with any other group.
clear()
Clear the TensorManager.
comm_i2symbol(i)
Returns the symbol corresponding to the commutation group number.
comm_symbols2i(i)
get the commutation group number corresponding to i

5.36. Tensor Module 1415

SymPy Documentation, Release 1.3

i can be a symbol or a number or a string

If i is not already defined its commutation group number is set.
get_comm(i, j)
Return the commutation parameter for commutation group numbers i, j
see _TensorManager.set_comm
set_comm(i, j, c)
set the commutation parameter c for commutation groups i, j
Parameters i, j : symbols representing commutation groups
c : group commutation number

Notes

i, j can be symbols, strings or numbers, apart from 0, 1 and 2 which are reserved
respectively for commuting, anticommuting tensors and tensors not commuting with
any other group apart with the commuting tensors. For the remaining cases, use
this method to set the commutation rules; by default c=None.
The group commutation number c is assigned in correspondence to the group com-
mutation symbols; it can be
0 commuting
1 anticommuting
None no commutation property

Examples

G and GH do not commute with themselves and commute with each other; A is com-
muting.

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead, TensorManager

>>> Lorentz = TensorIndexType('Lorentz')

>>> i0,i1,i2,i3,i4 = tensor_indices('i0:5', Lorentz)
>>> A = tensorhead('A', [Lorentz], [[1]])
>>> G = tensorhead('G', [Lorentz], [[1]], 'Gcomm')
>>> GH = tensorhead('GH', [Lorentz], [[1]], 'GHcomm')
>>> TensorManager.set_comm('Gcomm', 'GHcomm', 0)
>>> (GH(i1)*G(i0)).canon_bp()
G(i0)*GH(i1)
>>> (G(i1)*G(i0)).canon_bp()
G(i1)*G(i0)
>>> (G(i1)*A(i0)).canon_bp()
A(i0)*G(i1)

set_comms(*args)
set the commutation group numbers c for symbols i, j
Parameters args : sequence of (i, j, c)
class sympy.tensor.tensor.TensorIndexType
A TensorIndexType is characterized by its name and its metric.

1416 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters name : name of the tensor type

metric : metric symmetry or metric object or None
dim : dimension, it can be a symbol or an integer or None
eps_dim : dimension of the epsilon tensor
dummy_fmt : name of the head of dummy indices

Notes

The metric parameter can be: metric = False symmetric metric (in Riemannian ge-
ometry)
metric = True antisymmetric metric (for spinor calculus)
metric = None there is no metric
metric can be an object having name and antisym attributes.
If there is a metric the metric is used to raise and lower indices.
In the case of antisymmetric metric, the following raising and lowering conventions will
be adopted:
psi(a) = g(a, b)*psi(-b); chi(-a) = chi(b)*g(-b, -a)
g(-a, b) = delta(-a, b); g(b, -a) = -delta(a, -b)
where delta(-a, b) = delta(b, -a) is the Kronecker delta (see TensorIndex for the
conventions on indices).
If there is no metric it is not possible to raise or lower indices; e.g. the index of the
defining representation of SU(N) is ‘covariant’ and the conjugate representation is ‘con-
travariant’; for N > 2 they are linearly independent.
eps_dim is by default equal to dim, if the latter is an integer; else it can be assigned (for
use in naive dimensional regularization); if eps_dim is not an integer epsilon is None.

Examples

>>> from sympy.tensor.tensor import TensorIndexType

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> Lorentz.metric
metric(Lorentz,Lorentz)

Examples with metric components data added, this means it is working on a fixed basis:

>>> Lorentz.data = [1, -1, -1, -1]

>>> Lorentz
TensorIndexType(Lorentz, 0)
>>> Lorentz.data
[[1, 0, 0, 0], [0, -1, 0, 0], [0, 0, -1, 0], [0, 0, 0, -1]]

5.36. Tensor Module 1417

SymPy Documentation, Release 1.3

Attributes

name
metric_name (it is ‘metric’ or metric.name)
metric_antisym
metric (the metric tensor)
delta (Kronecker delta)
epsilon (the Levi-Civita epsilon tensor)
dim
eps_dim
dummy_fmt
data (a property to add ndarray values, to work in a specified basis.)

class sympy.tensor.tensor.TensorIndex
Represents an abstract tensor index.
Parameters name : name of the index, or True if you want it to be automati-
cally assigned
tensortype : TensorIndexType of the index
is_up : flag for contravariant index

Notes

Tensor indices are contracted with the Einstein summation convention.

An index can be in contravariant or in covariant form; in the latter case it is represented
prepending a - to the index name.
Dummy indices have a name with head given by tensortype._dummy_fmt

Examples

>>> from sympy.tensor.tensor import TensorIndexType, TensorIndex, TensorSymmetry,␣

,→TensorType, get_symmetric_group_sgs

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> i = TensorIndex('i', Lorentz); i
i
>>> sym1 = TensorSymmetry(*get_symmetric_group_sgs(1))
>>> S1 = TensorType([Lorentz], sym1)
>>> A, B = S1('A,B')
>>> A(i)*B(-i)
A(L_0)*B(-L_0)

If you want the index name to be automatically assigned, just put True in the name field,
it will be generated using the reserved character _ in front of its name, in order to avoid
conflicts with possible existing indices:

>>> i0 = TensorIndex(True, Lorentz)

>>> i0
_i0
>>> i1 = TensorIndex(True, Lorentz)
(continues on next page)

1418 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> i1
_i1
>>> A(i0)*B(-i1)
A(_i0)*B(-_i1)
>>> A(i0)*B(-i0)
A(L_0)*B(-L_0)

Attributes

name
tensortype
is_up

sympy.tensor.tensor.tensor_indices(s, typ)
Returns list of tensor indices given their names and their types
Parameters s : string of comma separated names of indices
typ : TensorIndexType of the indices

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> a, b, c, d = tensor_indices('a,b,c,d', Lorentz)

class sympy.tensor.tensor.TensorSymmetry
Monoterm symmetry of a tensor
Parameters bsgs : tuple (base, sgs) BSGS of the symmetry of the tensor
See also:
sympy.combinatorics.tensor_can.get_symmetric_group_sgs (page 300)

Notes

A tensor can have an arbitrary monoterm symmetry provided by its BSGS. Multiterm
symmetries, like the cyclic symmetry of the Riemann tensor, are not covered.

Examples

Define a symmetric tensor

>>> from sympy.tensor.tensor import TensorIndexType, TensorSymmetry, TensorType,␣

,→get_symmetric_group_sgs

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> sym2 = TensorSymmetry(get_symmetric_group_sgs(2))
>>> S2 = TensorType([Lorentz]*2, sym2)
>>> V = S2('V')

5.36. Tensor Module 1419

SymPy Documentation, Release 1.3

Attributes

base (base of the BSGS)

generators (generators of the BSGS)
rank (rank of the tensor)

sympy.tensor.tensor.tensorsymmetry(*args)
Return a TensorSymmetry object.
One can represent a tensor with any monoterm slot symmetry group using a BSGS.
args can be a BSGS args[0] base args[1] sgs
Usually tensors are in (direct products of) representations of the symmetric group; args
can be a list of lists representing the shapes of Young tableaux

Notes

For instance: [[1]] vector [[1]*n] symmetric tensor of rank n [[n]] antisymmetric
tensor of rank n [[2, 2]] monoterm slot symmetry of the Riemann tensor [[1],[1]]
vector*vector [[2],[1],[1] (antisymmetric tensor)*vector*vector
Notice that with the shape [2, 2] we associate only the monoterm symmetries of the
Riemann tensor; this is an abuse of notation, since the shape [2, 2] corresponds usually
to the irreducible representation characterized by the monoterm symmetries and by the
cyclic symmetry.

Examples

Symmetric tensor using a Young tableau

>>> from sympy.tensor.tensor import TensorIndexType, TensorType, tensorsymmetry

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> sym2 = tensorsymmetry([1, 1])
>>> S2 = TensorType([Lorentz]*2, sym2)
>>> V = S2('V')

Symmetric tensor using a BSGS (base, strong generator set)

>>> from sympy.tensor.tensor import get_symmetric_group_sgs

>>> sym2 = tensorsymmetry(*get_symmetric_group_sgs(2))
>>> S2 = TensorType([Lorentz]*2, sym2)
>>> V = S2('V')

class sympy.tensor.tensor.TensorType
Class of tensor types.
Parameters index_types : list of TensorIndexType of the tensor indices
symmetry : TensorSymmetry of the tensor

1420 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Define a symmetric tensor

>>> from sympy.tensor.tensor import TensorIndexType, tensorsymmetry, TensorType

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> sym2 = tensorsymmetry([1, 1])
>>> S2 = TensorType([Lorentz]*2, sym2)
>>> V = S2('V')

Attributes

index_types
symmetry
types (list of TensorIndexType without repetitions)

class sympy.tensor.tensor.TensorHead
Tensor head of the tensor
Parameters name : name of the tensor
typ : list of TensorIndexType
comm : commutation group number

Notes

A TensorHead belongs to a commutation group, defined by a symbol on number comm

(see _TensorManager.set_comm); tensors in a commutation group have the same com-
mutation properties; by default comm is 0, the group of the commuting tensors.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensorhead, TensorType

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> A = tensorhead('A', [Lorentz, Lorentz], [[1],[1]])

Examples with ndarray values, the components data assigned to the TensorHead object
are assumed to be in a fully-contravariant representation. In case it is necessary to
assign components data which represents the values of a non-fully covariant tensor, see
the other examples.

>>> from sympy.tensor.tensor import tensor_indices, tensorhead

>>> Lorentz.data = [1, -1, -1, -1]
>>> i0, i1 = tensor_indices('i0:2', Lorentz)
>>> A.data = [[j+2*i for j in range(4)] for i in range(4)]

in order to retrieve data, it is also necessary to specify abstract indices enclosed by round
brackets, then numerical indices inside square brackets.

5.36. Tensor Module 1421

SymPy Documentation, Release 1.3

>>> A(i0, i1)[0, 0]

0
>>> A(i0, i1)[2, 3] == 3+2*2
True

Notice that square brackets create a valued tensor expression instance:

>>> A(i0, i1)

A(i0, i1)

To view the data, just type:

>>> A.data
[[0, 1, 2, 3], [2, 3, 4, 5], [4, 5, 6, 7], [6, 7, 8, 9]]

Turning to a tensor expression, covariant indices get the corresponding components data
corrected by the metric:

>>> A(i0, -i1).data

[[0, -1, -2, -3], [2, -3, -4, -5], [4, -5, -6, -7], [6, -7, -8, -9]]

>>> A(-i0, -i1).data

[[0, -1, -2, -3], [-2, 3, 4, 5], [-4, 5, 6, 7], [-6, 7, 8, 9]]

while if all indices are contravariant, the ndarray remains the same

>>> A(i0, i1).data

[[0, 1, 2, 3], [2, 3, 4, 5], [4, 5, 6, 7], [6, 7, 8, 9]]

When all indices are contracted and components data are added to the tensor, accessing
the data will return a scalar, no array object. In fact, arrays are dropped to scalars if
they contain only one element.

>>> A(i0, -i0)

A(L_0, -L_0)
>>> A(i0, -i0).data
-18

It is also possible to assign components data to an indexed tensor, i.e. a tensor with
specified covariant and contravariant components. In this example, the covariant com-
ponents data of the Electromagnetic tensor are injected into A:

>>> from sympy import symbols

>>> Ex, Ey, Ez, Bx, By, Bz = symbols('E_x E_y E_z B_x B_y B_z')
>>> c = symbols('c', positive=True)

Let’s define F , an antisymmetric tensor, we have to assign an antisymmetric matrix to

it, because [[2]] stands for the Young tableau representation of an antisymmetric set of
two elements:

>>> F = tensorhead('A', [Lorentz, Lorentz], [[2]])

>>> F(-i0, -i1).data = [
... [0, Ex/c, Ey/c, Ez/c],
... [-Ex/c, 0, -Bz, By],
... [-Ey/c, Bz, 0, -Bx],
... [-Ez/c, -By, Bx, 0]]

1422 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Now it is possible to retrieve the contravariant form of the Electromagnetic tensor:

>>> F(i0, i1).data

[[0, -E_x/c, -E_y/c, -E_z/c], [E_x/c, 0, -B_z, B_y], [E_y/c, B_z, 0, -B_x], [E_z/
,→c, -B_y, B_x, 0]]

and the mixed contravariant-covariant form:

>>> F(i0, -i1).data

[[0, E_x/c, E_y/c, E_z/c], [E_x/c, 0, B_z, -B_y], [E_y/c, -B_z, 0, B_x], [E_z/c,␣
,→B_y, -B_x, 0]]

To convert the darray to a SymPy matrix, just cast:

>>> F.data.tomatrix()
Matrix([
[ 0, -E_x/c, -E_y/c, -E_z/c],
[E_x/c, 0, -B_z, B_y],
[E_y/c, B_z, 0, -B_x],
[E_z/c, -B_y, B_x, 0]])

Still notice, in this last example, that accessing components data from a tensor without
specifying the indices is equivalent to assume that all indices are contravariant.
It is also possible to store symbolic components data inside a tensor, for example, define
a four-momentum-like tensor:

>>> from sympy import symbols

>>> P = tensorhead('P', [Lorentz], [[1]])
>>> E, px, py, pz = symbols('E p_x p_y p_z', positive=True)
>>> P.data = [E, px, py, pz]

The contravariant and covariant components are, respectively:

>>> P(i0).data
[E, p_x, p_y, p_z]
>>> P(-i0).data
[E, -p_x, -p_y, -p_z]

The contraction of a 1-index tensor by itself is usually indicated by a power by two:

>>> P(i0)**2
E**2 - p_x**2 - p_y**2 - p_z**2

As the power by two is clearly identical to Pµ P µ , it is possible to simply contract the

TensorHead object, without specifying the indices

>>> P**2
E**2 - p_x**2 - p_y**2 - p_z**2

5.36. Tensor Module 1423

SymPy Documentation, Release 1.3

Attributes

name
index_types
rank
types ( equal to typ.types)
symmetry (equal to typ.symmetry)
comm (commutation group)

commutes_with(other)
Returns 0 if self and other commute, 1 if they anticommute.
Returns None if self and other neither commute nor anticommute.
class sympy.tensor.tensor.TensExpr
Abstract base class for tensor expressions

Notes

A tensor expression is an expression formed by tensors; currently the sums of tensors

are distributed.
A TensExpr can be a TensAdd or a TensMul.
TensAdd objects are put in canonical form using the Butler-Portugal algorithm for canon-
icalization under monoterm symmetries.
TensMul objects are formed by products of component tensors, and include a coefficient,
which is a SymPy expression.
In the internal representation contracted indices are represented by (ipos1, ipos2,
icomp1, icomp2), where icomp1 is the position of the component tensor with contravari-
ant index, ipos1 is the slot which the index occupies in that component tensor.
Contracted indices are therefore nameless in the internal representation.
fun_eval(*index_tuples)
Return a tensor with free indices substituted according to index_tuples
index_types list of tuples (old_index, new_index)

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> i, j, k, l = tensor_indices('i,j,k,l', Lorentz)
>>> A, B = tensorhead('A,B', [Lorentz]*2, [[1]*2])
>>> t = A(i, k)*B(-k, -j); t
A(i, L_0)*B(-L_0, -j)
>>> t.fun_eval((i, k),(-j, l))
A(k, L_0)*B(-L_0, l)

get_matrix()
Returns ndarray components data as a matrix, if components data are available and
ndarray dimension does not exceed 2.

1424 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensorsymmetry,␣

,→TensorType

>>> from sympy import ones

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> sym2 = tensorsymmetry([1]*2)
>>> S2 = TensorType([Lorentz]*2, sym2)
>>> A = S2('A')

The tensor A is symmetric in its indices, as can be deduced by the [1, 1] Young
tableau when constructing sym2. One has to be careful to assign symmetric compo-
nent data to A, as the symmetry properties of data are currently not checked to be
compatible with the defined tensor symmetry.

>>> from sympy.tensor.tensor import tensor_indices, tensorhead

>>> Lorentz.data = [1, -1, -1, -1]
>>> i0, i1 = tensor_indices('i0:2', Lorentz)
>>> A.data = [[j+i for j in range(4)] for i in range(4)]
>>> A(i0, i1).get_matrix()
Matrix([
[0, 1, 2, 3],
[1, 2, 3, 4],
[2, 3, 4, 5],
[3, 4, 5, 6]])

It is possible to perform usual operation on matrices, such as the matrix multiplica-

tion:

>>> A(i0, i1).get_matrix()*ones(4, 1)

Matrix([
[ 6],
[10],
[14],
[18]])

class sympy.tensor.tensor.TensAdd
Sum of tensors
Parameters free_args : list of the free indices

Notes

Sum of more than one tensor are put automatically in canonical form.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensorhead, tensor_indices

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')
>>> a, b = tensor_indices('a,b', Lorentz)
>>> p, q = tensorhead('p,q', [Lorentz], [[1]])
>>> t = p(a) + q(a); t
p(a) + q(a)
(continues on next page)

5.36. Tensor Module 1425

SymPy Documentation, Release 1.3

(continued from previous page)

>>> t(b)
p(b) + q(b)

Examples with components data added to the tensor expression:

>>> Lorentz.data = [1, -1, -1, -1]

>>> a, b = tensor_indices('a, b', Lorentz)
>>> p.data = [2, 3, -2, 7]
>>> q.data = [2, 3, -2, 7]
>>> t = p(a) + q(a); t
p(a) + q(a)
>>> t(b)
p(b) + q(b)

The following are: 2**2 - 3**2 - 2**2 - 7**2 ==> -58

>>> (p(a)*p(-a)).data
-58
>>> p(a)**2
-58

Attributes

args (tuple of addends)

rank (rank of the tensor)
free_args (list of the free indices in sorted order)

canon_bp()
canonicalize using the Butler-Portugal algorithm for canonicalization under
monoterm symmetries.
contract_metric(g)
Raise or lower indices with the metric g
Parameters g : metric
contract_all : if True, eliminate all g which are contracted

Notes

see the TensorIndexType docstring for the contraction conventions

fun_eval(*index_tuples)
Return a tensor with free indices substituted according to index_tuples
Parameters index_types : list of tuples (old_index, new_index)

Examples

1426 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> i, j, k, l = tensor_indices('i,j,k,l', Lorentz)
>>> A, B = tensorhead('A,B', [Lorentz]*2, [[1]*2])
>>> t = A(i, k)*B(-k, -j) + A(i, -j)
>>> t.fun_eval((i, k),(-j, l))
A(k, L_0)*B(l, -L_0) + A(k, l)

substitute_indices(*index_tuples)
Return a tensor with free indices substituted according to index_tuples
Parameters index_types : list of tuples (old_index, new_index)

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> i, j, k, l = tensor_indices('i,j,k,l', Lorentz)
>>> A, B = tensorhead('A,B', [Lorentz]*2, [[1]*2])
>>> t = A(i, k)*B(-k, -j); t
A(i, L_0)*B(-L_0, -j)
>>> t.substitute_indices((i,j), (j, k))
A(j, L_0)*B(-L_0, -k)

class sympy.tensor.tensor.TensMul
Product of tensors
Parameters coeff : SymPy coefficient of the tensor
args

Notes

args[0] list of TensorHead of the component tensors.

args[1] list of (ind, ipos, icomp) where ind is a free index, ipos is the slot position
of ind in the icomp-th component tensor.
args[2] list of tuples representing dummy indices. (ipos1, ipos2, icomp1, icomp2)
indicates that the contravariant dummy index is the ipos1-th slot position in the icomp1-
th component tensor; the corresponding covariant index is in the ipos2 slot position in
the icomp2-th component tensor.

5.36. Tensor Module 1427

SymPy Documentation, Release 1.3

Attributes

components (list of TensorHead of the component tensors)

types (list of nonrepeated TensorIndexType)
free (list of (ind, ipos, icomp), see Notes)
dum (list of (ipos1, ipos2, icomp1, icomp2), see Notes)
ext_rank (rank of the tensor counting the dummy indices)
rank (rank of the tensor)
coeff (SymPy coefficient of the tensor)
free_args (list of the free indices in sorted order)
is_canon_bp (True if the tensor in in canonical form)

canon_bp()
Canonicalize using the Butler-Portugal algorithm for canonicalization under
monoterm symmetries.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> m0, m1, m2 = tensor_indices('m0,m1,m2', Lorentz)
>>> A = tensorhead('A', [Lorentz]*2, [[2]])
>>> t = A(m0,-m1)*A(m1,-m0)
>>> t.canon_bp()
-A(L_0, L_1)*A(-L_0, -L_1)
>>> t = A(m0,-m1)*A(m1,-m2)*A(m2,-m0)
>>> t.canon_bp()
0

contract_metric(g)
Raise or lower indices with the metric g
Parameters g : metric

Notes

see the TensorIndexType docstring for the contraction conventions

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> m0, m1, m2 = tensor_indices('m0,m1,m2', Lorentz)
>>> g = Lorentz.metric
>>> p, q = tensorhead('p,q', [Lorentz], [[1]])
>>> t = p(m0)*q(m1)*g(-m0, -m1)
>>> t.canon_bp()
metric(L_0, L_1)*p(-L_0)*q(-L_1)
(continues on next page)

1428 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> t.contract_metric(g).canon_bp()
p(L_0)*q(-L_0)

get_free_indices()
Returns the list of free indices of the tensor
The indices are listed in the order in which they appear in the component tensors.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> m0, m1, m2 = tensor_indices('m0,m1,m2', Lorentz)
>>> g = Lorentz.metric
>>> p, q = tensorhead('p,q', [Lorentz], [[1]])
>>> t = p(m1)*g(m0,m2)
>>> t.get_free_indices()
[m1, m0, m2]
>>> t2 = p(m1)*g(-m1, m2)
>>> t2.get_free_indices()
[m2]

get_indices()
Returns the list of indices of the tensor
The indices are listed in the order in which they appear in the component tensors.
The dummy indices are given a name which does not collide with the names of the
free indices.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> m0, m1, m2 = tensor_indices('m0,m1,m2', Lorentz)
>>> g = Lorentz.metric
>>> p, q = tensorhead('p,q', [Lorentz], [[1]])
>>> t = p(m1)*g(m0,m2)
>>> t.get_indices()
[m1, m0, m2]
>>> t2 = p(m1)*g(-m1, m2)
>>> t2.get_indices()
[L_0, -L_0, m2]

perm2tensor(g, is_canon_bp=False)
Returns the tensor corresponding to the permutation g
For further details, see the method in TIDS with the same name.
sorted_components()
Returns a tensor product with sorted components.
split()
Returns a list of tensors, whose product is self

5.36. Tensor Module 1429

SymPy Documentation, Release 1.3

Dummy indices contracted among different tensor components become free indices
with the same name as the one used to represent the dummy indices.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices,␣

,→tensorhead

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> a, b, c, d = tensor_indices('a,b,c,d', Lorentz)
>>> A, B = tensorhead('A,B', [Lorentz]*2, [[1]*2])
>>> t = A(a,b)*B(-b,c)
>>> t
A(a, L_0)*B(-L_0, c)
>>> t.split()
[A(a, L_0), B(-L_0, c)]

sympy.tensor.tensor.canon_bp(p)
Butler-Portugal canonicalization
sympy.tensor.tensor.tensor_mul(*a)
product of tensors
sympy.tensor.tensor.riemann_cyclic_replace(t_r)
replace Riemann tensor with an equivalent expression
R(m,n,p,q) -> 2/3*R(m,n,p,q) - 1/3*R(m,q,n,p) + 1/3*R(m,p,n,q)
sympy.tensor.tensor.riemann_cyclic(t2)
replace each Riemann tensor with an equivalent expression satisfying the cyclic identity.
This trick is discussed in the reference guide to Cadabra.

Examples

>>> from sympy.tensor.tensor import TensorIndexType, tensor_indices, tensorhead,␣

,→riemann_cyclic

>>> Lorentz = TensorIndexType('Lorentz', dummy_fmt='L')

>>> i, j, k, l = tensor_indices('i,j,k,l', Lorentz)
>>> R = tensorhead('R', [Lorentz]*4, [[2, 2]])
>>> t = R(i,j,k,l)*(R(-i,-j,-k,-l) - 2*R(-i,-k,-j,-l))
>>> riemann_cyclic(t)
0

5.37 Utilities

This module contains some general purpose utilities that are used across SymPy.
Contents:

1430 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.37.1 Autowrap Module

The autowrap module works very well in tandem with the Indexed classes of the Tensor Mod-
ule (page 1399). Here is a simple example that shows how to setup a binary routine that
calculates a matrix-vector product.

>>> from sympy.utilities.autowrap import autowrap

>>> from sympy import symbols, IndexedBase, Idx, Eq
>>> A, x, y = map(IndexedBase, ['A', 'x', 'y'])
>>> m, n = symbols('m n', integer=True)
>>> i = Idx('i', m)
>>> j = Idx('j', n)
>>> instruction = Eq(y[i], A[i, j]*x[j]); instruction
Eq(y[i], A[i, j]*x[j])

Because the code printers treat Indexed objects with repeated indices as a summation, the
above equality instance will be translated to low-level code for a matrix vector product. This
is how you tell SymPy to generate the code, compile it and wrap it as a python function:

>>> matvec = autowrap(instruction) # doctest: +SKIP

That’s it. Now let’s test it with some numpy arrays. The default wrapper backend is f2py. The
wrapper function it provides is set up to accept python lists, which it will silently convert to
numpy arrays. So we can test the matrix vector product like this:

>>> M = [[0, 1],

... [1, 0]]
>>> matvec(M, [2, 3]) # doctest: +SKIP
[ 3. 2.]

Implementation details

The autowrap module is implemented with a backend consisting of CodeWrapper objects.

The base class CodeWrapper takes care of details about module name, filenames and options.
It also contains the driver routine, which runs through all steps in the correct order, and also
takes care of setting up and removing the temporary working directory.
The actual compilation and wrapping is done by external resources, such as the system in-
stalled f2py command. The Cython backend runs a distutils setup script in a subprocess.
Subclasses of CodeWrapper takes care of these backend-dependent details.

API Reference

Module for compiling codegen output, and wrap the binary for use in python.

Note: To use the autowrap module it must first be imported

>>> from sympy.utilities.autowrap import autowrap

This module provides a common interface for different external backends, such as f2py, fwrap,
Cython, SWIG(?) etc. (Currently only f2py and Cython are implemented) The goal is to provide
access to compiled binaries of acceptable performance with a one-button user interface, i.e.

5.37. Utilities 1431

SymPy Documentation, Release 1.3

>>> from sympy.abc import x,y

>>> expr = ((x - y)**(25)).expand()
>>> binary_callable = autowrap(expr)
>>> binary_callable(1, 2)
-1.0

The callable returned from autowrap() is a binary python function, not a SymPy object. If
it is desired to use the compiled function in symbolic expressions, it is better to use bi-
nary_function() which returns a SymPy Function object. The binary callable is attached as the
_imp_ attribute and invoked when a numerical evaluation is requested with evalf(), or with
lambdify().

>>> from sympy.utilities.autowrap import binary_function

>>> f = binary_function('f', expr)
>>> 2*f(x, y) + y
y + 2*f(x, y)
>>> (2*f(x, y) + y).evalf(2, subs={x: 1, y:2})
0.e-110

The idea is that a SymPy user will primarily be interested in working with mathematical
expressions, and should not have to learn details about wrapping tools in order to evaluate
expressions numerically, even if they are computationally expensive.
When is this useful?
1) For computations on large arrays, Python iterations may be too slow, and depending on
the mathematical expression, it may be difficult to exploit the advanced index operations
provided by NumPy.
2) For really long expressions that will be called repeatedly, the compiled binary should be
significantly faster than SymPy’s .evalf()
3) If you are generating code with the codegen utility in order to use it in another project,
the automatic python wrappers let you test the binaries immediately from within SymPy.
4) To create customized ufuncs for use with numpy arrays. See ufuncify.
When is this module NOT the best approach?
1) If you are really concerned about speed or memory optimizations, you will probably
get better results by working directly with the wrapper tools and the low level code.
However, the files generated by this utility may provide a useful starting point and
reference code. Temporary files will be left intact if you supply the keyword tem-
pdir=”path/to/files/”.
2) If the array computation can be handled easily by numpy, and you don’t need the binaries
for another project.
class sympy.utilities.autowrap.CodeWrapper(generator, filepath=None, flags=[],
verbose=False)
Base Class for code wrappers
class sympy.utilities.autowrap.CythonCodeWrapper(*args, **kwargs)
Wrapper that uses Cython
dump_pyx(routines, f, prefix)
Write a Cython file with python wrappers
This file contains all the definitions of the routines in c code and refers to the header
file.

1432 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Arguments

routines List of Routine instances

f File-like object to write the file to
prefix The filename prefix, used to refer to the proper header file. Only the base-
name of the prefix is used.

class sympy.utilities.autowrap.DummyWrapper(generator, filepath=None, flags=[],

verbose=False)
Class used for testing independent of backends
class sympy.utilities.autowrap.F2PyCodeWrapper(*args, **kwargs)
Wrapper that uses f2py
class sympy.utilities.autowrap.UfuncifyCodeWrapper(*args, **kwargs)
Wrapper for Ufuncify
dump_c(routines, f, prefix, funcname=None)
Write a C file with python wrappers
This file contains all the definitions of the routines in c code.

Arguments

routines List of Routine instances

f File-like object to write the file to
prefix The filename prefix, used to name the imported module.
funcname Name of the main function to be returned.

sympy.utilities.autowrap.autowrap(expr, language=None, backend=’f2py’, tem-

pdir=None, args=None, flags=None, ver-
bose=False, helpers=None, code_gen=None,
**kwargs)
Generates python callable binaries based on the math expression.
Parameters expr
The SymPy expression that should be wrapped as a binary routine.
language : string, optional
If supplied, (options: ‘C’ or ‘F95’), specifies the language of the gen-
erated code. If None [default], the language is inferred based upon
the specified backend.
backend : string, optional
Backend used to wrap the generated code. Either ‘f2py’ [default], or
‘cython’.
tempdir : string, optional
Path to directory for temporary files. If this argument is supplied,
the generated code and the wrapper input files are left intact in the
specified path.
args : iterable, optional

5.37. Utilities 1433

SymPy Documentation, Release 1.3

An ordered iterable of symbols. Specifies the argument sequence for

the function.
flags : iterable, optional
Additional option flags that will be passed to the backend.
verbose : bool, optional
If True, autowrap will not mute the command line backends. This can
be helpful for debugging.
helpers : iterable, optional
Used to define auxiliary expressions needed for the main expr. If the
main expression needs to call a specialized function it should be put in
the helpers iterable. Autowrap will then make sure that the compiled
main expression can link to the helper routine. Items should be tuples
with (<funtion_name>, <sympy_expression>, <arguments>). It is
mandatory to supply an argument sequence to helper routines.
code_gen : CodeGen instance
An instance of a CodeGen subclass. Overrides language.
include_dirs : [string]
A list of directories to search for C/C++ header files (in Unix form for
portability).
library_dirs : [string]
A list of directories to search for C/C++ libraries at link time.
libraries : [string]
A list of library names (not filenames or paths) to link against.
extra_compile_args : [string]
Any extra platform- and compiler-specific information to use when
compiling the source files in ‘sources’. For platforms and compil-
ers where “command line” makes sense, this is typically a list of
command-line arguments, but for other platforms it could be any-
thing.
extra_link_args : [string]
Any extra platform- and compiler-specific information to use when
linking object files together to create the extension (or to create
a new static Python interpreter). Similar interpretation as for ‘ex-
tra_compile_args’.

Examples

>>> from sympy.abc import x, y, z

>>> from sympy.utilities.autowrap import autowrap
>>> expr = ((x - y + z)**(13)).expand()
>>> binary_func = autowrap(expr)
>>> binary_func(1, 4, 2)
-1.0

1434 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.utilities.autowrap.binary_function(symfunc, expr, **kwargs)

Returns a sympy function with expr as binary implementation
This is a convenience function that automates the steps needed to autowrap the SymPy
expression and attaching it to a Function object with implemented_function().
Parameters symfunc : sympy Function
The function to bind the callable to.
expr : sympy Expression
The expression used to generate the function.
kwargs : dict
Any kwargs accepted by autowrap.

Examples

>>> from sympy.abc import x, y

>>> from sympy.utilities.autowrap import binary_function
>>> expr = ((x - y)**(25)).expand()
>>> f = binary_function('f', expr)
>>> type(f)
<class 'sympy.core.function.UndefinedFunction'>
>>> 2*f(x, y)
2*f(x, y)
>>> f(x, y).evalf(2, subs={x: 1, y: 2})
-1.0

sympy.utilities.autowrap.ufuncify(args, expr, language=None, backend=’numpy’,

tempdir=None, flags=None, verbose=False,
helpers=None, **kwargs)
Generates a binary function that supports broadcasting on numpy arrays.
Parameters args : iterable
Either a Symbol or an iterable of symbols. Specifies the argument
sequence for the function.
expr
A SymPy expression that defines the element wise operation.
language : string, optional
If supplied, (options: ‘C’ or ‘F95’), specifies the language of the gen-
erated code. If None [default], the language is inferred based upon
the specified backend.
backend : string, optional
Backend used to wrap the generated code. Either ‘numpy’ [default],
‘cython’, or ‘f2py’.
tempdir : string, optional
Path to directory for temporary files. If this argument is supplied,
the generated code and the wrapper input files are left intact in the
specified path.

5.37. Utilities 1435

SymPy Documentation, Release 1.3

flags : iterable, optional

Additional option flags that will be passed to the backend.
verbose : bool, optional
If True, autowrap will not mute the command line backends. This can
be helpful for debugging.
helpers : iterable, optional
Used to define auxiliary expressions needed for the main expr. If the
main expression needs to call a specialized function it should be put in
the helpers iterable. Autowrap will then make sure that the compiled
main expression can link to the helper routine. Items should be tuples
with (<funtion_name>, <sympy_expression>, <arguments>). It is
mandatory to supply an argument sequence to helper routines.
kwargs : dict
These kwargs will be passed to autowrap if the f 2py or cython backend
is used and ignored if the numpy backend is used.

References

[1] http://docs.scipy.org/doc/numpy/reference/ufuncs.html

Examples

>>> from sympy.utilities.autowrap import ufuncify

>>> from sympy.abc import x, y
>>> import numpy as np
>>> f = ufuncify((x, y), y + x**2)
>>> type(f)
<class 'numpy.ufunc'>
>>> f([1, 2, 3], 2)
array([ 3., 6., 11.])
>>> f(np.arange(5), 3)
array([ 3., 4., 7., 12., 19.])

For the ‘f2py’ and ‘cython’ backends, inputs are required to be equal length 1-
dimensional arrays. The ‘f2py’ backend will perform type conversion, but the Cython
backend will error if the inputs are not of the expected type.

>>> f_fortran = ufuncify((x, y), y + x**2, backend='f2py')

>>> f_fortran(1, 2)
array([ 3.])
>>> f_fortran(np.array([1, 2, 3]), np.array([1.0, 2.0, 3.0]))
array([ 2., 6., 12.])
>>> f_cython = ufuncify((x, y), y + x**2, backend='Cython')
>>> f_cython(1, 2) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
TypeError: Argument '_x' has incorrect type (expected numpy.ndarray, got int)
>>> f_cython(np.array([1.0]), np.array([2.0]))
array([ 3.])

1436 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Note

The default backend (‘numpy’) will create actual instances of numpy.ufunc. These sup-
port ndimensional broadcasting, and implicit type conversion. Use of the other backends
will result in a “ufunc-like” function, which requires equal length 1-dimensional arrays
for all arguments, and will not perform any type conversions.

5.37.2 Codegen

This module provides functionality to generate directly compilable code from SymPy expres-
sions. The codegen function is the user interface to the code generation functionality in
SymPy. Some details of the implementation is given below for advanced users that may want
to use the framework directly.

Note: The codegen callable is not in the sympy namespace automatically, to use it you must
first execute

>>> from sympy.utilities.codegen import codegen

Implementation Details

Here we present the most important pieces of the internal structure, as advanced users may
want to use it directly, for instance by subclassing a code generator for a specialized applica-
tion. It is very likely that you would prefer to use the codegen() function documented
above.
Basic assumptions:
• A generic Routine data structure describes the routine that must be translated into
C/Fortran/… code. This data structure covers all features present in one or more of
the supported languages.
• Descendants from the CodeGen class transform multiple Routine instances into compil-
able code. Each derived class translates into a specific language.
• In many cases, one wants a simple workflow. The friendly functions in the last part are
a simple api on top of the Routine/CodeGen stuff. They are easier to use, but are less
powerful.

Routine

The Routine class is a very important piece of the codegen module. Viewing the codegen
utility as a translator of mathematical expressions into a set of statements in a programming
language, the Routine instances are responsible for extracting and storing information about
how the math can be encapsulated in a function call. Thus, it is the Routine constructor that
decides what arguments the routine will need and if there should be a return value.

5.37. Utilities 1437

SymPy Documentation, Release 1.3

API Reference

module for generating C, C++, Fortran77, Fortran90, Julia, Rust and Octave/Matlab routines
that evaluate sympy expressions. This module is work in progress. Only the milestones with
a ‘+’ character in the list below have been completed.
— How is sympy.utilities.codegen different from sympy.printing.ccode? —
We considered the idea to extend the printing routines for sympy functions in such a way that
it prints complete compilable code, but this leads to a few unsurmountable issues that can
only be tackled with dedicated code generator:
• For C, one needs both a code and a header file, while the printing routines generate just
one string. This code generator can be extended to support .pyf files for f2py.
• SymPy functions are not concerned with programming-technical issues, such as input,
output and input-output arguments. Other examples are contiguous or non-contiguous
arrays, including headers of other libraries such as gsl or others.
• It is highly interesting to evaluate several sympy functions in one C routine, eventually
sharing common intermediate results with the help of the cse routine. This is more than
just printing.
• From the programming perspective, expressions with constants should be evaluated in
the code generator as much as possible. This is different for printing.
— Basic assumptions —
• A generic Routine data structure describes the routine that must be translated into
C/Fortran/… code. This data structure covers all features present in one or more of
the supported languages.
• Descendants from the CodeGen class transform multiple Routine instances into compil-
able code. Each derived class translates into a specific language.
• In many cases, one wants a simple workflow. The friendly functions in the last part are
a simple api on top of the Routine/CodeGen stuff. They are easier to use, but are less
powerful.
— Milestones —
• First working version with scalar input arguments, generating C code, tests
• Friendly functions that are easier to use than the rigorous Routine/CodeGen workflow.
• Integer and Real numbers as input and output
• Output arguments
• InputOutput arguments
• Sort input/output arguments properly
• Contiguous array arguments (numpy matrices)
• Also generate .pyf code for f2py (in autowrap module)
• Isolate constants and evaluate them beforehand in double precision
• Fortran 90
• Octave/Matlab
• Common Subexpression Elimination
• User defined comments in the generated code

1438 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• Optional extra include lines for libraries/objects that can eval special functions
• Test other C compilers and libraries: gcc, tcc, libtcc, gcc+gsl, …
• Contiguous array arguments (sympy matrices)
• Non-contiguous array arguments (sympy matrices)
• ccode must raise an error when it encounters something that can not be translated into
c. ccode(integrate(sin(x)/x, x)) does not make sense.
• Complex numbers as input and output
• A default complex datatype
• Include extra information in the header: date, user, hostname, sha1 hash, …
• Fortran 77
• C++
• Python
• Julia
• Rust
• …
class sympy.utilities.codegen.Routine(name, arguments, results, local_vars,
global_vars)
Generic description of evaluation routine for set of expressions.
A CodeGen class can translate instances of this class into code in a particular language.
The routine specification covers all the features present in these languages. The Code-
Gen part must raise an exception when certain features are not present in the target
language. For example, multiple return values are possible in Python, but not in C or
Fortran. Another example: Fortran and Python support complex numbers, while C does
not.
result_variables
Returns a list of OutputArgument, InOutArgument and Result.
If return values are present, they are at the end ot the list.
variables
Returns a set of all variables possibly used in the routine.
For routines with unnamed return values, the dummies that may or may not be used
will be included in the set.
class sympy.utilities.codegen.DataType(cname, fname, pyname, jlname, octname,
rsname)
Holds strings for a certain datatype in different languages.
sympy.utilities.codegen.get_default_datatype(expr)
Derives an appropriate datatype based on the expression.
class sympy.utilities.codegen.Argument(name, datatype=None, dimen-
sions=None, precision=None)
An abstract Argument data structure: a name and a data type.
This structure is refined in the descendants below.

5.37. Utilities 1439

SymPy Documentation, Release 1.3

class sympy.utilities.codegen.OutputArgument(name, result_var, expr,

datatype=None, dimen-
sions=None, precision=None)
OutputArgument are always initialized in the routine.
class sympy.utilities.codegen.Result(expr, name=None, result_var=None,
datatype=None, dimensions=None, preci-
sion=None)
An expression for a return value.
The name result is used to avoid conflicts with the reserved word “return” in the python
language. It is also shorter than ReturnValue.
These may or may not need a name in the destination (e.g., “return(x*y)” might return
a value without ever naming it).
class sympy.utilities.codegen.CodeGen(project=’project’, cse=False)
Abstract class for the code generators.

Attributes

printer

dump_code(routines, f, prefix, header=True, empty=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
routine(name, expr, argument_sequence=None, global_vars=None)
Creates an Routine object that is appropriate for this language.
This implementation is appropriate for at least C/Fortran. Subclasses can override
this if necessary.
Here, we assume at most one return value (the l-value) which must be scalar. Ad-
ditional outputs are OutputArguments (e.g., pointers on right-hand-side or pass-
by-reference). Matrices are always returned via OutputArguments. If argu-

1440 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ment_sequence is None, arguments will be ordered alphabetically, but with all In-
putArguments first, and then OutputArgument and InOutArguments.
write(routines, prefix, to_files=False, header=True, empty=True)
Writes all the source code files for the given routines.
The generated source is returned as a list of (filename, contents) tuples, or is written
to files (see below). Each filename consists of the given prefix, appended with an
appropriate extension.
Parameters routines : list
A list of Routine instances to be written
prefix : string
The prefix for the output files
to_files : bool, optional
When True, the output is written to files. Otherwise, a list of (file-
name, contents) tuples is returned. [default: False]
header : bool, optional
When True, a header comment is included on top of each source file.
[default: True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default: True]
class sympy.utilities.codegen.CCodeGen(project=’project’, printer=None, prepro-
cessor_statements=None, cse=False)
Generator for C code.
The .write() method inherited from CodeGen will output a code file and an interface file,
<prefix>.c and <prefix>.h respectively.

Attributes

printer

dump_c(routines, f, prefix, header=True, empty=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.

5.37. Utilities 1441

SymPy Documentation, Release 1.3

header : bool, optional

When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
dump_h(routines, f, prefix, header=True, empty=True)
Writes the C header file.
This file contains all the function declarations.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix, used to construct the include guards. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
get_prototype(routine)
Returns a string for the function prototype of the routine.
If the routine has multiple result objects, an CodeGenError is raised.
See: http://en.wikipedia.org/wiki/Function_prototype
class sympy.utilities.codegen.FCodeGen(project=’project’, printer=None)
Generator for Fortran 95 code
The .write() method inherited from CodeGen will output a code file and an interface file,
<prefix>.f90 and <prefix>.h respectively.

Attributes

printer

dump_f95(routines, f, prefix, header=True, empty=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list

1442 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

A list of Routine instances.

f : file-like
Where to write the file.
prefix : string
The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
dump_h(routines, f, prefix, header=True, empty=True)
Writes the interface to a header file.
This file contains all the function declarations.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
get_interface(routine)
Returns a string for the function interface.
The routine should have a single result object, which can be None. If the routine
has multiple result objects, a CodeGenError is raised.
See: http://en.wikipedia.org/wiki/Function_prototype
class sympy.utilities.codegen.JuliaCodeGen(project=’project’, printer=None)
Generator for Julia code.
The .write() method inherited from CodeGen will output a code file <prefix>.jl.

Attributes

printer

5.37. Utilities 1443

SymPy Documentation, Release 1.3

dump_jl(routines, f, prefix, header=True, empty=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
routine(name, expr, argument_sequence, global_vars)
Specialized Routine creation for Julia.
class sympy.utilities.codegen.OctaveCodeGen(project=’project’, printer=None)
Generator for Octave code.
The .write() method inherited from CodeGen will output a code file <prefix>.m.
Octave .m files usually contain one function. That function name should match the file-
name (prefix). If you pass multiple name_expr pairs, the latter ones are presumed to
be private functions accessed by the primary function.
You should only pass inputs to argument_sequence: outputs are ordered according to
their order in name_expr.

Attributes

printer

dump_m(routines, f, prefix, header=True, empty=True, inline=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string

1444 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
routine(name, expr, argument_sequence, global_vars)
Specialized Routine creation for Octave.
class sympy.utilities.codegen.RustCodeGen(project=’project’, printer=None)
Generator for Rust code.
The .write() method inherited from CodeGen will output a code file <prefix>.rs

Attributes

printer

dump_rs(routines, f, prefix, header=True, empty=True)

Write the code by calling language specific methods.
The generated file contains all the definitions of the routines in low-level code and
refers to the header file if appropriate.
Parameters routines : list
A list of Routine instances.
f : file-like
Where to write the file.
prefix : string
The filename prefix, used to refer to the proper header file. Only the
basename of the prefix is used.
header : bool, optional
When True, a header comment is included on top of each source file.
[default : True]
empty : bool, optional
When True, empty lines are included to structure the source files.
[default : True]
get_prototype(routine)
Returns a string for the function prototype of the routine.
If the routine has multiple result objects, an CodeGenError is raised.
See: http://en.wikipedia.org/wiki/Function_prototype
routine(name, expr, argument_sequence, global_vars)
Specialized Routine creation for Rust.

5.37. Utilities 1445

SymPy Documentation, Release 1.3

sympy.utilities.codegen.codegen(name_expr, language=None, prefix=None,

project=’project’, to_files=False, header=True,
empty=True, argument_sequence=None,
global_vars=None, standard=None,
code_gen=None, printer=None)
Generate source code for expressions in a given language.
Parameters name_expr : tuple, or list of tuples
A single (name, expression) tuple or a list of (name, expression) tu-
ples. Each tuple corresponds to a routine. If the expression is an
equality (an instance of class Equality) the left hand side is considered
an output argument. If expression is an iterable, then the routine will
have multiple outputs.
language : string,
A string that indicates the source code language. This is case in-
sensitive. Currently, ‘C’, ‘F95’ and ‘Octave’ are supported. ‘Octave’
generates code compatible with both Octave and Matlab.
prefix : string, optional
A prefix for the names of the files that contain the source code.
Language-dependent suffixes will be appended. If omitted, the name
of the first name_expr tuple is used.
project : string, optional
A project name, used for making unique preprocessor instructions.
[default: “project”]
to_files : bool, optional
When True, the code will be written to one or more files with the
given prefix, otherwise strings with the names and contents of these
files are returned. [default: False]
header : bool, optional
When True, a header is written on top of each source file. [default:
True]
empty : bool, optional
When True, empty lines are used to structure the code. [default:
True]
argument_sequence : iterable, optional
Sequence of arguments for the routine in a preferred order. A Code-
GenError is raised if required arguments are missing. Redundant
arguments are used without warning. If omitted, arguments will be
ordered alphabetically, but with all input arguments first, and then
output or in-out arguments.
global_vars : iterable, optional
Sequence of global variables used by the routine. Variables listed
here will not show up as function arguments.
standard : string
code_gen : CodeGen instance

1446 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

An instance of a CodeGen subclass. Overrides language.

Examples

>>> from sympy.utilities.codegen import codegen

>>> from sympy.abc import x, y, z
>>> [(c_name, c_code), (h_name, c_header)] = codegen(
... (”f”, x+y*z), ”C89”, ”test”, header=False, empty=False)
>>> print(c_name)
test.c
>>> print(c_code)
#include ”test.h”
#include <math.h>
double f(double x, double y, double z) {
double f_result;
f_result = x + y*z;
return f_result;
}
<BLANKLINE>
>>> print(h_name)
test.h
>>> print(c_header)
#ifndef PROJECT__TEST__H
#define PROJECT__TEST__H
double f(double x, double y, double z);
#endif
<BLANKLINE>

Another example using Equality objects to give named outputs. Here the filename (pre-
fix) is taken from the first (name, expr) pair.

>>> from sympy.abc import f, g

>>> from sympy import Eq
>>> [(c_name, c_code), (h_name, c_header)] = codegen(
... [(”myfcn”, x + y), (”fcn2”, [Eq(f, 2*x), Eq(g, y)])],
... ”C99”, header=False, empty=False)
>>> print(c_name)
myfcn.c
>>> print(c_code)
#include ”myfcn.h”
#include <math.h>
double myfcn(double x, double y) {
double myfcn_result;
myfcn_result = x + y;
return myfcn_result;
}
void fcn2(double x, double y, double *f, double *g) {
(*f) = 2*x;
(*g) = y;
}
<BLANKLINE>

If the generated function(s) will be part of a larger project where various global variables
have been defined, the ‘global_vars’ option can be used to remove the specified variables
from the function signature

5.37. Utilities 1447

SymPy Documentation, Release 1.3

>>> from sympy.utilities.codegen import codegen

>>> from sympy.abc import x, y, z
>>> [(f_name, f_code), header] = codegen(
... (”f”, x+y*z), ”F95”, header=False, empty=False,
... argument_sequence=(x, y), global_vars=(z,))
>>> print(f_code)
REAL*8 function f(x, y)
implicit none
REAL*8, intent(in) :: x
REAL*8, intent(in) :: y
f = x + y*z
end function
<BLANKLINE>

sympy.utilities.codegen.make_routine(name, expr, argument_sequence=None,

global_vars=None, language=’F95’)
A factory that makes an appropriate Routine from an expression.
Parameters name : string
The name of this routine in the generated code.
expr : expression or list/tuple of expressions
A SymPy expression that the Routine instance will represent. If given
a list or tuple of expressions, the routine will be considered to have
multiple return values and/or output arguments.
argument_sequence : list or tuple, optional
List arguments for the routine in a preferred order. If omitted, the
results are language dependent, for example, alphabetical order or
in the same order as the given expressions.
global_vars : iterable, optional
Sequence of global variables used by the routine. Variables listed
here will not show up as function arguments.
language : string, optional
Specify a target language. The Routine itself should be language-
agnostic but the precise way one is created, error checking, etc de-
pend on the language. [default: “F95”].
A decision about whether to use output arguments or return values
is made
depending on both the language and the particular mathematical
expressions.
For an expression of type Equality, the left hand side is typically made
into an OutputArgument (or perhaps an InOutArgument if appropri-
ate).
Otherwise, typically, the calculated expression is made a return val-
ues of
the routine.

1448 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.codegen import make_routine

>>> from sympy.abc import x, y, f, g
>>> from sympy import Eq
>>> r = make_routine('test', [Eq(f, 2*x), Eq(g, x + y)])
>>> [arg.result_var for arg in r.results]
[]
>>> [arg.name for arg in r.arguments]
[x, y, f, g]
>>> [arg.name for arg in r.result_variables]
[f, g]
>>> r.local_vars
set()

Another more complicated example with a mixture of specified and automatically-

assigned names. Also has Matrix output.

>>> from sympy import Matrix

>>> r = make_routine('fcn', [x*y, Eq(f, 1), Eq(g, x + g), Matrix([[x, 2]])])
>>> [arg.result_var for arg in r.results] # doctest: +SKIP
[result_5397460570204848505]
>>> [arg.expr for arg in r.results]
[x*y]
>>> [arg.name for arg in r.arguments] # doctest: +SKIP
[x, y, f, g, out_8598435338387848786]

We can examine the various arguments more closely:

>>> from sympy.utilities.codegen import (InputArgument, OutputArgument,

... InOutArgument)
>>> [a.name for a in r.arguments if isinstance(a, InputArgument)]
[x, y]

>>> [a.name for a in r.arguments if isinstance(a, OutputArgument)] # doctest:␣

,→+SKIP

[f, out_8598435338387848786]
>>> [a.expr for a in r.arguments if isinstance(a, OutputArgument)]
[1, Matrix([[x, 2]])]

>>> [a.name for a in r.arguments if isinstance(a, InOutArgument)]

[g]
>>> [a.expr for a in r.arguments if isinstance(a, InOutArgument)]
[g + x]

5.37.3 Decorator

Useful utility decorators.

sympy.utilities.decorator.conserve_mpmath_dps(func)
After the function finishes, resets the value of mpmath.mp.dps to the value it had before
the function was run.
sympy.utilities.decorator.doctest_depends_on(exe=None, modules=None, dis-
able_viewers=None)

5.37. Utilities 1449

SymPy Documentation, Release 1.3

Adds metadata about the dependencies which need to be met for doctesting the doc-
strings of the decorated objects.
sympy.utilities.decorator.memoize_property(storage)
Create a property, where the lookup is stored in storage
class sympy.utilities.decorator.no_attrs_in_subclass(cls, f)
Don’t ‘inherit’ certain attributes from a base class
>>> from sympy.utilities.decorator import no_attrs_in_subclass

>>> class A(object):

... x = 'test'

>>> A.x = no_attrs_in_subclass(A, A.x)

>>> class B(A):

... pass

>>> hasattr(A, 'x')

True
>>> hasattr(B, 'x')
False

sympy.utilities.decorator.public(obj)
Append obj’s name to global __all__ variable (call site).
By using this decorator on functions or classes you achieve the same goal as by fill-
ing __all__ variables manually, you just don’t have to repeat yourself (object’s name).
You also know if object is public at definition site, not at some random location (where
__all__ was set).
Note that in multiple decorator setup (in almost all cases) @public decorator must be
applied before any other decorators, because it relies on the pointer to object’s global
namespace. If you apply other decorators first, @public may end up modifying the wrong
namespace.

Examples

>>> from sympy.utilities.decorator import public

>>> __all__
Traceback (most recent call last):
...
NameError: name '__all__' is not defined

>>> @public
... def some_function():
... pass

>>> __all__
['some_function']

sympy.utilities.decorator.threaded(func)
Apply func to sub–elements of an object, including Add.

1450 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

This decorator is intended to make it uniformly possible to apply a function to all elements
of composite objects, e.g. matrices, lists, tuples and other iterable containers, or just
expressions.
This version of threaded() (page 1450) decorator allows threading over elements of Add
class. If this behavior is not desirable use xthreaded() (page 1451) decorator.
Functions using this decorator must have the following signature:

@threaded
def function(expr, *args, **kwargs):

sympy.utilities.decorator.threaded_factory(func, use_add)
A factory for threaded decorators.
sympy.utilities.decorator.xthreaded(func)
Apply func to sub–elements of an object, excluding Add.
This decorator is intended to make it uniformly possible to apply a function to all elements
of composite objects, e.g. matrices, lists, tuples and other iterable containers, or just
expressions.
This version of threaded() (page 1450) decorator disallows threading over elements of
Add class. If this behavior is not desirable use threaded() (page 1450) decorator.
Functions using this decorator must have the following signature:

@xthreaded
def function(expr, *args, **kwargs):

5.37.4 Enumerative

This module includes functions and classes for enumerating and counting multiset partitions.

sympy.utilities.enumerative.multiset_partitions_taocp(multiplicities)
Enumerates partitions of a multiset.
Parameters multiplicities
list of integer multiplicities of the components of the multiset.
Yields state
Internal data structure which encodes a particular partition. This out-
put is then usually processed by a vistor function which combines the
information from this data structure with the components themselves
to produce an actual partition.
Unless they wish to create their own visitor function, users will have
little need to look inside this data structure. But, for reference, it is
a 3-element list with components:
f is a frame array, which is used to divide pstack into parts.
lpart points to the base of the topmost part.
pstack is an array of PartComponent objects.

5.37. Utilities 1451

SymPy Documentation, Release 1.3

The state output offers a peek into the internal data structures of
the enumeration function. The client should treat this as read-only;
any modification of the data structure will cause unpredictable (and
almost certainly incorrect) results. Also, the components of state
are modified in place at each iteration. Hence, the visitor must be
called at each loop iteration. Accumulating the state instances and
processing them later will not work.
See also:

sympy.utilities.iterables.multiset_partitions (page 1466) Takes a multiset as

input and directly yields multiset partitions. It dispatches to a number of functions,
including this one, for implementation. Most users will find it more convenient to
use than multiset_partitions_taocp.

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import multiset_partitions_taocp
>>> # variables components and multiplicities represent the multiset 'abb'
>>> components = 'ab'
>>> multiplicities = [1, 2]
>>> states = multiset_partitions_taocp(multiplicities)
>>> list(list_visitor(state, components) for state in states)
[[['a', 'b', 'b']],
[['a', 'b'], ['b']],
[['a'], ['b', 'b']],
[['a'], ['b'], ['b']]]

sympy.utilities.enumerative.factoring_visitor(state, primes)
Use with multiset_partitions_taocp to enumerate the ways a number can be expressed
as a product of factors. For this usage, the exponents of the prime factors of a number
are arguments to the partition enumerator, while the corresponding prime factors are
input here.

Examples

To enumerate the factorings of a number we can think of the elements of the partition
as being the prime factors and the multiplicities as being their exponents.

>>> from sympy.utilities.enumerative import factoring_visitor

>>> from sympy.utilities.enumerative import multiset_partitions_taocp
>>> from sympy import factorint
>>> primes, multiplicities = zip(*factorint(24).items())
>>> primes
(2, 3)
>>> multiplicities
(3, 1)
>>> states = multiset_partitions_taocp(multiplicities)
>>> list(factoring_visitor(state, primes) for state in states)
[[24], [8, 3], [12, 2], [4, 6], [4, 2, 3], [6, 2, 2], [2, 2, 2, 3]]

sympy.utilities.enumerative.list_visitor(state, components)
Return a list of lists to represent the partition.

1452 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import multiset_partitions_taocp
>>> states = multiset_partitions_taocp([1, 2, 1])
>>> s = next(states)
>>> list_visitor(s, 'abc') # for multiset 'a b b c'
[['a', 'b', 'b', 'c']]
>>> s = next(states)
>>> list_visitor(s, [1, 2, 3]) # for multiset '1 2 2 3
[[1, 2, 2], [3]]

The approach of the function multiset_partitions_taocp is extended and generalized by

the class MultisetPartitionTraverser.
class sympy.utilities.enumerative.MultisetPartitionTraverser
Has methods to enumerate and count the partitions of a multiset.
This implements a refactored and extended version of Knuth’s algorithm 7.1.2.5M
[AOCP].”
The enumeration methods of this class are generators and return data structures
which can be interpreted by the same visitor functions used for the output of multi-
set_partitions_taocp.
See also:
multiset_partitions_taocp (page 1451), sympy.utilities.iterables.
multiset_partititions

References

[AOCP], [Factorisatio], [Yorgey]

Examples

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser

>>> m = MultisetPartitionTraverser()
>>> m.count_partitions([4,4,4,2])
127750
>>> m.count_partitions([3,3,3])
686

count_partitions(multiplicities)
Returns the number of partitions of a multiset whose components have the multi-
plicities given in multiplicities.
For larger counts, this method is much faster than calling one of the enumerators
and counting the result. Uses dynamic programming to cut down on the number of
nodes actually explored. The dictionary used in order to accelerate the counting pro-
cess is stored in the MultisetPartitionTraverser object and persists across calls.
If the user does not expect to call count_partitions for any additional multisets, the
object should be cleared to save memory. On the other hand, the cache built up from
one count run can significantly speed up subsequent calls to count_partitions, so
it may be advantageous not to clear the object.

5.37. Utilities 1453

SymPy Documentation, Release 1.3

Notes

If one looks at the workings of Knuth’s algorithm M [AOCP], it can be viewed as a

traversal of a binary tree of parts. A part has (up to) two children, the left child
resulting from the spread operation, and the right child from the decrement opera-
tion. The ordinary enumeration of multiset partitions is an in-order traversal of this
tree, and with the partitions corresponding to paths from the root to the leaves. The
mapping from paths to partitions is a little complicated, since the partition would
contain only those parts which are leaves or the parents of a spread link, not those
which are parents of a decrement link.
For counting purposes, it is sufficient to count leaves, and this can be done with a
recursive in-order traversal. The number of leaves of a subtree rooted at a particular
part is a function only of that part itself, so memoizing has the potential to speed up
the counting dramatically.
This method follows a computational approach which is similar to the hypothetical
memoized recursive function, but with two differences:
1) This method is iterative, borrowing its structure from the other enumerations
and maintaining an explicit stack of parts which are in the process of being
counted. (There may be multisets which can be counted reasonably quickly by
this implementation, but which would overflow the default Python recursion limit
with a recursive implementation.)
2) Instead of using the part data structure directly, a more compact key is con-
structed. This saves space, but more importantly coalesces some parts which
would remain separate with physical keys.
Unlike the enumeration functions, there is currently no _range version of
count_partitions. If someone wants to stretch their brain, it should be possible to
construct one by memoizing with a histogram of counts rather than a single count,
and combining the histograms.

Examples

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser

>>> m = MultisetPartitionTraverser()
>>> m.count_partitions([9,8,2])
288716
>>> m.count_partitions([2,2])
9
>>> del m

enum_all(multiplicities)
Enumerate the partitions of a multiset.
See also:

multiset_partitions_taocp (page 1451) which provides the same result as this

method, but is about twice as fast. Hence, enum_all is primarily useful for test-
ing. Also see the function for a discussion of states and visitors.

1454 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser
>>> m = MultisetPartitionTraverser()
>>> states = m.enum_all([2,2])
>>> list(list_visitor(state, 'ab') for state in states)
[[['a', 'a', 'b', 'b']],
[['a', 'a', 'b'], ['b']],
[['a', 'a'], ['b', 'b']],
[['a', 'a'], ['b'], ['b']],
[['a', 'b', 'b'], ['a']],
[['a', 'b'], ['a', 'b']],
[['a', 'b'], ['a'], ['b']],
[['a'], ['a'], ['b', 'b']],
[['a'], ['a'], ['b'], ['b']]]

enum_large(multiplicities, lb)
Enumerate the partitions of a multiset with lb < num(parts)
Equivalent to enum_range(multiplicities, lb, sum(multiplicities))
Parameters multiplicities
list of multiplicities of the components of the multiset.
lb
Number of parts in the partition must be greater than this lower
bound.
See also:
enum_all (page 1454), enum_small (page 1456), enum_range (page 1455)

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser
>>> m = MultisetPartitionTraverser()
>>> states = m.enum_large([2,2], 2)
>>> list(list_visitor(state, 'ab') for state in states)
[[['a', 'a'], ['b'], ['b']],
[['a', 'b'], ['a'], ['b']],
[['a'], ['a'], ['b', 'b']],
[['a'], ['a'], ['b'], ['b']]]

enum_range(multiplicities, lb, ub)

Enumerate the partitions of a multiset with lb < num(parts) <= ub.
In particular, if partitions with exactly k parts are desired, call with
(multiplicities, k - 1, k). This method generalizes enum_all, enum_small,
and enum_large.

5.37. Utilities 1455

SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser
>>> m = MultisetPartitionTraverser()
>>> states = m.enum_range([2,2], 1, 2)
>>> list(list_visitor(state, 'ab') for state in states)
[[['a', 'a', 'b'], ['b']],
[['a', 'a'], ['b', 'b']],
[['a', 'b', 'b'], ['a']],
[['a', 'b'], ['a', 'b']]]

enum_small(multiplicities, ub)
Enumerate multiset partitions with no more than ub parts.
Equivalent to enum_range(multiplicities, 0, ub)
Parameters multiplicities
list of multiplicities of the components of the multiset.
ub
Maximum number of parts
See also:
enum_all (page 1454), enum_large (page 1455), enum_range (page 1455)

Examples

>>> from sympy.utilities.enumerative import list_visitor

>>> from sympy.utilities.enumerative import MultisetPartitionTraverser
>>> m = MultisetPartitionTraverser()
>>> states = m.enum_small([2,2], 2)
>>> list(list_visitor(state, 'ab') for state in states)
[[['a', 'a', 'b', 'b']],
[['a', 'a', 'b'], ['b']],
[['a', 'a'], ['b', 'b']],
[['a', 'b', 'b'], ['a']],
[['a', 'b'], ['a', 'b']]]

The implementation is based, in part, on the answer given to exercise 69, in Knuth
[AOCP].

5.37.5 Iterables

cartes

Returns the cartesian product of sequences as a generator.

Examples::

>>> from sympy.utilities.iterables import cartes

>>> list(cartes([1,2,3], 'ab'))
[(1, 'a'), (1, 'b'), (2, 'a'), (2, 'b'), (3, 'a'), (3, 'b')]

1456 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

variations

variations(seq, n) Returns all the variations of the list of size n.

Has an optional third argument. Must be a boolean value and makes the method return the
variations with repetition if set to True, or the variations without repetition if set to False.
Examples::

>>> from sympy.utilities.iterables import variations

>>> list(variations([1,2,3], 2))
[(1, 2), (1, 3), (2, 1), (2, 3), (3, 1), (3, 2)]
>>> list(variations([1,2,3], 2, True))
[(1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (2, 3), (3, 1), (3, 2), (3, 3)]

partitions

Although the combinatorics module contains Partition and IntegerPartition classes for inves-
tigation and manipulation of partitions, there are a few functions to generate partitions that
can be used as low-level tools for routines: partitions and multiset_partitions. The for-
mer gives integer partitions, and the latter gives enumerated partitions of elements. There
is also a routine kbins that will give a variety of permutations of partions.
partitions:

>>> from sympy.utilities.iterables import partitions

>>> [p.copy() for s, p in partitions(7, m=2, size=True) if s == 2]
[{1: 1, 6: 1}, {2: 1, 5: 1}, {3: 1, 4: 1}]

multiset_partitions:

>>> from sympy.utilities.iterables import multiset_partitions

>>> [p for p in multiset_partitions(3, 2)]
[[[0, 1], [2]], [[0, 2], [1]], [[0], [1, 2]]]
>>> [p for p in multiset_partitions([1, 1, 1, 2], 2)]
[[[1, 1, 1], [2]], [[1, 1, 2], [1]], [[1, 1], [1, 2]]]

kbins:

>>> from sympy.utilities.iterables import kbins

>>> def show(k):
... rv = []
... for p in k:
... rv.append(','.join([''.join(j) for j in p]))
... return sorted(rv)
...
>>> show(kbins(”ABCD”, 2))
['A,BCD', 'AB,CD', 'ABC,D']
>>> show(kbins(”ABC”, 2))
['A,BC', 'AB,C']
>>> show(kbins(”ABC”, 2, ordered=0)) # same as multiset_partitions
['A,BC', 'AB,C', 'AC,B']
>>> show(kbins(”ABC”, 2, ordered=1))
['A,BC', 'A,CB',
'B,AC', 'B,CA',
'C,AB', 'C,BA']
(continues on next page)

5.37. Utilities 1457

SymPy Documentation, Release 1.3

(continued from previous page)

>>> show(kbins(”ABC”, 2, ordered=10))
['A,BC', 'AB,C', 'AC,B',
'B,AC', 'BC,A',
'C,AB']
>>> show(kbins(”ABC”, 2, ordered=11))
['A,BC', 'A,CB', 'AB,C', 'AC,B',
'B,AC', 'B,CA', 'BA,C', 'BC,A',
'C,AB', 'C,BA', 'CA,B', 'CB,A']

Docstring

sympy.utilities.iterables.binary_partitions(n)
Generates the binary partition of n.
A binary partition consists only of numbers that are powers of two. Each step reduces a
2**(k+1) to 2**k and 2**k. Thus 16 is converted to 8 and 8.
Reference: TAOCP 4, section 7.2.1.5, problem 64

Examples

>>> from sympy.utilities.iterables import binary_partitions

>>> for i in binary_partitions(5):
... print(i)
...
[4, 1]
[2, 2, 1]
[2, 1, 1, 1]
[1, 1, 1, 1, 1]

sympy.utilities.iterables.bracelets(n, k)
Wrapper to necklaces to return a free (unrestricted) necklace.
sympy.utilities.iterables.capture(func)
Return the printed output of func().
f unc should be a function without arguments that produces output with print statements.

>>> from sympy.utilities.iterables import capture

>>> from sympy import pprint
>>> from sympy.abc import x
>>> def foo():
... print('hello world!')
...
>>> 'hello' in capture(foo) # foo, not foo()
True
>>> capture(lambda: pprint(2/x))
'2\n-\nx\n'

sympy.utilities.iterables.common_prefix(*seqs)
Return the subsequence that is a common start of sequences in seqs.

1458 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.utilities.iterables import common_prefix

>>> common_prefix(list(range(3)))
[0, 1, 2]
>>> common_prefix(list(range(3)), list(range(4)))
[0, 1, 2]
>>> common_prefix([1, 2, 3], [1, 2, 5])
[1, 2]
>>> common_prefix([1, 2, 3], [1, 3, 5])
[1]

sympy.utilities.iterables.common_suffix(*seqs)
Return the subsequence that is a common ending of sequences in seqs.

>>> from sympy.utilities.iterables import common_suffix

>>> common_suffix(list(range(3)))
[0, 1, 2]
>>> common_suffix(list(range(3)), list(range(4)))
[]
>>> common_suffix([1, 2, 3], [9, 2, 3])
[2, 3]
>>> common_suffix([1, 2, 3], [9, 7, 3])
[3]

sympy.utilities.iterables.dict_merge(*dicts)
Merge dictionaries into a single dictionary.
sympy.utilities.iterables.filter_symbols(iterator, exclude)
Only yield elements from iterator that do not occur in exclude.
Parameters iterator : iterable
iterator to take elements from
exclude : iterable
elements to exclude
Returns iterator : iterator
filtered iterator
sympy.utilities.iterables.flatten(iterable, levels=None, cls=None)
Recursively denest iterable containers.

>>> from sympy.utilities.iterables import flatten

>>> flatten([1, 2, 3])

[1, 2, 3]
>>> flatten([1, 2, [3]])
[1, 2, 3]
>>> flatten([1, [2, 3], [4, 5]])
[1, 2, 3, 4, 5]
>>> flatten([1.0, 2, (1, None)])
[1.0, 2, 1, None]

If you want to denest only a specified number of levels of nested containers, then set
levels flag to the desired number of levels:

>>> ls = [[(-2, -1), (1, 2)], [(0, 0)]]

5.37. Utilities 1459

SymPy Documentation, Release 1.3

>>> flatten(ls, levels=1)

[(-2, -1), (1, 2), (0, 0)]

If cls argument is specified, it will only flatten instances of that class, for example:

>>> from sympy.core import Basic

>>> class MyOp(Basic):
... pass
...
>>> flatten([MyOp(1, MyOp(2, 3))], cls=MyOp)
[1, 2, 3]

adapted from http://kogs-www.informatik.uni-hamburg.de/~meine/python_tricks

sympy.utilities.iterables.generate_bell(n)
Return permutations of [0, 1, …, n - 1] such that each permutation differs from the last
by the exchange of a single pair of neighbors. The n! permutations are returned as an
iterator. In order to obtain the next permutation from a random starting permutation,
use the next_trotterjohnson method of the Permutation class (which generates the
same sequence in a different manner).
See also:
sympy.combinatorics.Permutation.next_trotterjohnson

References

• http://en.wikipedia.org/wiki/Method_ringing
• http://stackoverflow.com/questions/4856615/recursive-permutation/4857018
• http://programminggeeks.com/bell-algorithm-for-permutation/
• http://en.wikipedia.org/wiki/Steinhaus%E2%80%93Johnson%E2%80%93Trotter_
algorithm
• Generating involutions, derangements, and relatives by ECO Vincent Vajnovszki,
DMTCS vol 1 issue 12, 2010

Examples

>>> from itertools import permutations

>>> from sympy.utilities.iterables import generate_bell
>>> from sympy import zeros, Matrix

This is the sort of permutation used in the ringing of physical bells, and does not produce
permutations in lexicographical order. Rather, the permutations differ from each other
by exactly one inversion, and the position at which the swapping occurs varies period-
ically in a simple fashion. Consider the first few permutations of 4 elements generated
by permutations and generate_bell:

>>> list(permutations(range(4)))[:5]
[(0, 1, 2, 3), (0, 1, 3, 2), (0, 2, 1, 3), (0, 2, 3, 1), (0, 3, 1, 2)]
>>> list(generate_bell(4))[:5]
[(0, 1, 2, 3), (0, 1, 3, 2), (0, 3, 1, 2), (3, 0, 1, 2), (3, 0, 2, 1)]

1460 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notice how the 2nd and 3rd lexicographical permutations have 3 elements out of place
whereas each “bell” permutation always has only two elements out of place relative to
the previous permutation (and so the signature (+/-1) of a permutation is opposite of the
signature of the previous permutation).
How the position of inversion varies across the elements can be seen by tracing out
where the largest number appears in the permutations:

>>> m = zeros(4, 24)

>>> for i, p in enumerate(generate_bell(4)):
... m[:, i] = Matrix([j - 3 for j in list(p)]) # make largest zero
>>> m.print_nonzero('X')
[XXX XXXXXX XXXXXX XXX]
[XX XX XXXX XX XXXX XX XX]
[X XXXX XX XXXX XX XXXX X]
[ XXXXXX XXXXXX XXXXXX ]

sympy.utilities.iterables.generate_derangements(perm)
Routine to generate unique derangements.
TODO: This will be rewritten to use the ECO operator approach once the permutations
branch is in master.
See also:
sympy.functions.combinatorial.factorials.subfactorial (page 486)

Examples

>>> from sympy.utilities.iterables import generate_derangements

>>> list(generate_derangements([0, 1, 2]))
[[1, 2, 0], [2, 0, 1]]
>>> list(generate_derangements([0, 1, 2, 3]))
[[1, 0, 3, 2], [1, 2, 3, 0], [1, 3, 0, 2], [2, 0, 3, 1], [2, 3, 0, 1], [2, 3,␣
,→1, 0], [3, 0, 1, 2], [3, 2, 0, 1], [3, 2, 1, 0]]
>>> list(generate_derangements([0, 1, 1]))
[]

sympy.utilities.iterables.generate_involutions(n)
Generates involutions.
An involution is a permutation that when multiplied by itself equals the identity permu-
tation. In this implementation the involutions are generated using Fixed Points.
Alternatively, an involution can be considered as a permutation that does not contain any
cycles with a length that is greater than two.
Reference: http://mathworld.wolfram.com/PermutationInvolution.html

Examples

>>> from sympy.utilities.iterables import generate_involutions

>>> list(generate_involutions(3))
[(0, 1, 2), (0, 2, 1), (1, 0, 2), (2, 1, 0)]
>>> len(list(generate_involutions(4)))
10

5.37. Utilities 1461

SymPy Documentation, Release 1.3

sympy.utilities.iterables.generate_oriented_forest(n)
This algorithm generates oriented forests.
An oriented graph is a directed graph having no symmetric pair of directed edges. A
forest is an acyclic graph, i.e., it has no cycles. A forest can also be described as a
disjoint union of trees, which are graphs in which any two vertices are connected by
exactly one simple path.
Reference: [1] T. Beyer and S.M. Hedetniemi: constant time generation of rooted
trees, SIAM J. Computing Vol. 9, No. 4, November 1980 [2] http://stackoverflow.com/
questions/1633833/oriented-forest-taocp-algorithm-in-python

Examples

>>> from sympy.utilities.iterables import generate_oriented_forest

>>> list(generate_oriented_forest(4))
[[0, 1, 2, 3], [0, 1, 2, 2], [0, 1, 2, 1], [0, 1, 2, 0], [0, 1, 1, 1], [0, 1,␣
,→1, 0], [0, 1, 0, 1], [0, 1, 0, 0], [0, 0, 0, 0]]

sympy.utilities.iterables.group(seq, multiple=True)
Splits a sequence into a list of lists of equal, adjacent elements.
See also:
multiset (page 1465)

Examples

>>> from sympy.utilities.iterables import group

>>> group([1, 1, 1, 2, 2, 3])

[[1, 1, 1], [2, 2], [3]]
>>> group([1, 1, 1, 2, 2, 3], multiple=False)
[(1, 3), (2, 2), (3, 1)]
>>> group([1, 1, 3, 2, 2, 1], multiple=False)
[(1, 2), (3, 1), (2, 2), (1, 1)]

sympy.utilities.iterables.has_dups(seq)
Return True if there are any duplicate elements in seq.

Examples

>>> from sympy.utilities.iterables import has_dups

>>> from sympy import Dict, Set

>>> has_dups((1, 2, 1))

True
>>> has_dups(range(3))
False
>>> all(has_dups(c) is False for c in (set(), Set(), dict(), Dict()))
True

1462 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.utilities.iterables.has_variety(seq)
Return True if there are any different elements in seq.

Examples

>>> from sympy.utilities.iterables import has_variety

>>> has_variety((1, 2, 1))

True
>>> has_variety((1, 1, 1))
False

sympy.utilities.iterables.ibin(n, bits=0, str=False)

Return a list of length bits corresponding to the binary value of n with small bits to the
right (last). If bits is omitted, the length will be the number required to represent n. If
the bits are desired in reversed order, use the [::-1] slice of the returned list.
If a sequence of all bits-length lists starting from [0, 0,…, 0] through [1, 1, …, 1] are
desired, pass a non-integer for bits, e.g. ‘all’.
If the bit string is desired pass str=True.

Examples

>>> from sympy.utilities.iterables import ibin

>>> ibin(2)
[1, 0]
>>> ibin(2, 4)
[0, 0, 1, 0]
>>> ibin(2, 4)[::-1]
[0, 1, 0, 0]

If all lists corresponding to 0 to 2**n - 1, pass a non-integer for bits:

>>> bits = 2
>>> for i in ibin(2, 'all'):
... print(i)
(0, 0)
(0, 1)
(1, 0)
(1, 1)

If a bit string is desired of a given length, use str=True:

>>> n = 123
>>> bits = 10
>>> ibin(n, bits, str=True)
'0001111011'
>>> ibin(n, bits, str=True)[::-1] # small bits left
'1101111000'
>>> list(ibin(3, 'all', str=True))
['000', '001', '010', '011', '100', '101', '110', '111']

sympy.utilities.iterables.interactive_traversal(expr)
Traverse a tree asking a user which branch to choose.

5.37. Utilities 1463

SymPy Documentation, Release 1.3

sympy.utilities.iterables.kbins(l, k, ordered=None)
Return sequence l partitioned into k bins.
See also:
partitions (page 1470), multiset_partitions (page 1466)

Examples

>>> from sympy.utilities.iterables import kbins

The default is to give the items in the same order, but grouped into k partitions without
any reordering:
>>> from __future__ import print_function
>>> for p in kbins(list(range(5)), 2):
... print(p)
...
[[0], [1, 2, 3, 4]]
[[0, 1], [2, 3, 4]]
[[0, 1, 2], [3, 4]]
[[0, 1, 2, 3], [4]]

The ordered flag is either None (to give the simple partition of the elements) or is a 2
digit integer indicating whether the order of the bins and the order of the items in the
bins matters. Given:
A = [[0], [1, 2]]
B = [[1, 2], [0]]
C = [[2, 1], [0]]
D = [[0], [2, 1]]

the following values for ordered have the shown meanings:

00 means A == B == C == D
01 means A == B
10 means A == D
11 means A == A

>>> for ordered in [None, 0, 1, 10, 11]:

... print('ordered = %s' % ordered)
... for p in kbins(list(range(3)), 2, ordered=ordered):
... print(' %s' % p)
...
ordered = None
[[0], [1, 2]]
[[0, 1], [2]]
ordered = 0
[[0, 1], [2]]
[[0, 2], [1]]
[[0], [1, 2]]
ordered = 1
[[0], [1, 2]]
[[0], [2, 1]]
[[1], [0, 2]]
[[1], [2, 0]]
(continues on next page)

1464 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[[2], [0, 1]]
[[2], [1, 0]]
ordered = 10
[[0, 1], [2]]
[[2], [0, 1]]
[[0, 2], [1]]
[[1], [0, 2]]
[[0], [1, 2]]
[[1, 2], [0]]
ordered = 11
[[0], [1, 2]]
[[0, 1], [2]]
[[0], [2, 1]]
[[0, 2], [1]]
[[1], [0, 2]]
[[1, 0], [2]]
[[1], [2, 0]]
[[1, 2], [0]]
[[2], [0, 1]]
[[2, 0], [1]]
[[2], [1, 0]]
[[2, 1], [0]]

sympy.utilities.iterables.minlex(seq, directed=True, is_set=False, small=None)

Return a tuple where the smallest element appears first; if directed is True (default)
then the order is preserved, otherwise the sequence will be reversed if that gives a
smaller ordering.
If every element appears only once then is_set can be set to True for more efficient
processing.
If the smallest element is known at the time of calling, it can be passed and the calculation
of the smallest element will be omitted.

Examples

>>> from sympy.combinatorics.polyhedron import minlex

>>> minlex((1, 2, 0))
(0, 1, 2)
>>> minlex((1, 0, 2))
(0, 2, 1)
>>> minlex((1, 0, 2), directed=False)
(0, 1, 2)

>>> minlex('11010011000', directed=True)

'00011010011'
>>> minlex('11010011000', directed=False)
'00011001011'

sympy.utilities.iterables.multiset(seq)
Return the hashable sequence in multiset form with values being the multiplicity of the
item in the sequence.
See also:
group (page 1462)

5.37. Utilities 1465

SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.iterables import multiset

>>> multiset('mississippi')
{'i': 4, 'm': 1, 'p': 2, 's': 4}

sympy.utilities.iterables.multiset_combinations(m, n, g=None)
Return the unique combinations of size n from multiset m.

Examples

>>> from sympy.utilities.iterables import multiset_combinations

>>> from itertools import combinations
>>> [''.join(i) for i in multiset_combinations('baby', 3)]
['abb', 'aby', 'bby']

>>> def count(f, s): return len(list(f(s, 3)))

The number of combinations depends on the number of letters; the number of unique
combinations depends on how the letters are repeated.
>>> s1 = 'abracadabra'
>>> s2 = 'banana tree'
>>> count(combinations, s1), count(multiset_combinations, s1)
(165, 23)
>>> count(combinations, s2), count(multiset_combinations, s2)
(165, 54)

sympy.utilities.iterables.multiset_partitions(multiset, m=None)
Return unique partitions of the given multiset (in list form). If m is None, all multisets
will be returned, otherwise only partitions with m parts will be returned.
If multiset is an integer, a range [0, 1, …, multiset - 1] will be supplied.
See also:
partitions (page 1470), sympy.combinatorics.partitions.Partition (page 208),
sympy.combinatorics.partitions.IntegerPartition (page 210), sympy.functions.
combinatorial.numbers.nT

Notes

When all the elements are the same in the multiset, the order of the returned partitions
is determined by the partitions routine. If one is counting partitions then it is better
to use the nT function.

Examples

>>> from sympy.utilities.iterables import multiset_partitions

>>> list(multiset_partitions([1, 2, 3, 4], 2))
[[[1, 2, 3], [4]], [[1, 2, 4], [3]], [[1, 2], [3, 4]],
[[1, 3, 4], [2]], [[1, 3], [2, 4]], [[1, 4], [2, 3]],
(continues on next page)

1466 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[[1], [2, 3, 4]]]
>>> list(multiset_partitions([1, 2, 3, 4], 1))
[[[1, 2, 3, 4]]]

Only unique partitions are returned and these will be returned in a canonical order re-
gardless of the order of the input:

>>> a = [1, 2, 2, 1]
>>> ans = list(multiset_partitions(a, 2))
>>> a.sort()
>>> list(multiset_partitions(a, 2)) == ans
True
>>> a = range(3, 1, -1)
>>> (list(multiset_partitions(a)) ==
... list(multiset_partitions(sorted(a))))
True

If m is omitted then all partitions will be returned:

>>> list(multiset_partitions([1, 1, 2]))

[[[1, 1, 2]], [[1, 1], [2]], [[1, 2], [1]], [[1], [1], [2]]]
>>> list(multiset_partitions([1]*3))
[[[1, 1, 1]], [[1], [1, 1]], [[1], [1], [1]]]

Counting

The number of partitions of a set is given by the bell number:

>>> from sympy import bell

>>> len(list(multiset_partitions(5))) == bell(5) == 52
True

The number of partitions of length k from a set of size n is given by the Stirling Number
of the 2nd kind:

>>> def S2(n, k):

... from sympy import Dummy, binomial, factorial, Sum
... if k > n:
... return 0
... j = Dummy()
... arg = (-1)**(k-j)*j**n*binomial(k,j)
... return 1/factorial(k)*Sum(arg,(j,0,k)).doit()
...
>>> S2(5, 2) == len(list(multiset_partitions(5, 2))) == 15
True

These comments on counting apply to sets, not multisets.

sympy.utilities.iterables.multiset_permutations(m, size=None, g=None)
Return the unique permutations of multiset m.

5.37. Utilities 1467

SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.iterables import multiset_permutations

>>> from sympy import factorial
>>> [''.join(i) for i in multiset_permutations('aab')]
['aab', 'aba', 'baa']
>>> factorial(len('banana'))
720
>>> len(list(multiset_permutations('banana')))
60

sympy.utilities.iterables.necklaces(n, k, free=False)
A routine to generate necklaces that may (free=True) or may not (free=False) be turned
over to be viewed. The “necklaces” returned are comprised of n integers (beads) with k
different values (colors). Only unique necklaces are returned.

References

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

Examples

>>> from sympy.utilities.iterables import necklaces, bracelets

>>> def show(s, i):
... return ''.join(s[j] for j in i)

The “unrestricted necklace” is sometimes also referred to as a “bracelet” (an object that
can be turned over, a sequence that can be reversed) and the term “necklace” is used to
imply a sequence that cannot be reversed. So ACB == ABC for a bracelet (rotate and
reverse) while the two are different for a necklace since rotation alone cannot make the
two sequences the same.
(mnemonic: Bracelets can be viewed Backwards, but Not Necklaces.)

>>> B = [show('ABC', i) for i in bracelets(3, 3)]

>>> N = [show('ABC', i) for i in necklaces(3, 3)]
>>> set(N) - set(B)
{'ACB'}

>>> list(necklaces(4, 2))

[(0, 0, 0, 0), (0, 0, 0, 1), (0, 0, 1, 1),
(0, 1, 0, 1), (0, 1, 1, 1), (1, 1, 1, 1)]

>>> [show('.o', i) for i in bracelets(4, 2)]

['....', '...o', '..oo', '.o.o', '.ooo', 'oooo']

sympy.utilities.iterables.numbered_symbols(prefix=’x’, cls=None, start=0, ex-

clude=[], *args, **assumptions)
Generate an infinite stream of Symbols consisting of a prefix and increasing subscripts
provided that they do not occur in exclude.
Parameters prefix : str, optional

1468 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The prefix to use. By default, this function will generate symbols of

the form “x0”, “x1”, etc.
cls : class, optional
The class to use. By default, it uses Symbol, but you can also use Wild
or Dummy.
start : int, optional
The start number. By default, it is 0.
Returns sym : Symbol
The subscripted symbols.
sympy.utilities.iterables.ordered_partitions(n, m=None, sort=True)
Generates ordered partitions of integer n.
Parameters ‘‘m‘‘ : integer (default gives partitions of all sizes) else only
those with size m. In addition, if m is not None then partitions are
generated in place (see examples).
‘‘sort‘‘ : bool (default True) controls whether partitions are
returned in sorted order when m is not None; when False, the parti-
tions are returned as fast as possible with elements sorted, but when
m|n the partitions will not be in ascending lexicographical order.

References

[R597], [R598]

Examples

>>> from sympy.utilities.iterables import ordered_partitions

All partitions of 5 in ascending lexicographical:

>>> for p in ordered_partitions(5):

... print(p)
[1, 1, 1, 1, 1]
[1, 1, 1, 2]
[1, 1, 3]
[1, 2, 2]
[1, 4]
[2, 3]
[5]

Only partitions of 5 with two parts:

>>> for p in ordered_partitions(5, 2):

... print(p)
[1, 4]
[2, 3]

When m is given, a given list objects will be used more than once for speed reasons so
you will not see the correct partitions unless you make a copy of each as it is generated:

5.37. Utilities 1469

SymPy Documentation, Release 1.3

>>> [p for p in ordered_partitions(7, 3)]

[[1, 1, 1], [1, 1, 1], [1, 1, 1], [2, 2, 2]]
>>> [list(p) for p in ordered_partitions(7, 3)]
[[1, 1, 5], [1, 2, 4], [1, 3, 3], [2, 2, 3]]

When n is a multiple of m, the elements are still sorted but the partitions themselves will
be unordered if sort is False; the default is to return them in ascending lexicographical
order.
>>> for p in ordered_partitions(6, 2):
... print(p)
[1, 5]
[2, 4]
[3, 3]

But if speed is more important than ordering, sort can be set to False:
>>> for p in ordered_partitions(6, 2, sort=False):
... print(p)
[1, 5]
[3, 3]
[2, 4]

sympy.utilities.iterables.partitions(n, m=None, k=None, size=False)

Generate all partitions of positive integer, n.
Parameters ‘‘m‘‘ : integer (default gives partitions of all sizes)
limits number of parts in partition (mnemonic: m, maximum parts)
‘‘k‘‘ : integer (default gives partitions number from 1 through n)
limits the numbers that are kept in the partition (mnemonic: k, keys)
‘‘size‘‘ : bool (default False, only partition is returned)
when True then (M, P) is returned where M is the sum of the multi-
plicities and P is the generated partition.
Each partition is represented as a dictionary, mapping an integer
to the number of copies of that integer in the partition. For example,
the first partition of 4 returned is {4: 1}, “4: one of them”.
See also:
sympy.combinatorics.partitions.Partition (page 208), sympy.combinatorics.
partitions.IntegerPartition (page 210)

Examples

>>> from sympy.utilities.iterables import partitions

The numbers appearing in the partition (the key of the returned dict) are limited with k:
>>> for p in partitions(6, k=2): # doctest: +SKIP
... print(p)
{2: 3}
(continues on next page)

1470 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

{1: 2, 2: 2}
{1: 4, 2: 1}
{1: 6}

The maximum number of parts in the partition (the sum of the values in the returned
dict) are limited with m (default value, None, gives partitions from 1 through n):

>>> for p in partitions(6, m=2): # doctest: +SKIP

... print(p)
...
{6: 1}
{1: 1, 5: 1}
{2: 1, 4: 1}
{3: 2}

Note that the _same_ dictionary object is returned each time. This is for speed: gener-
ating each partition goes quickly, taking constant time, independent of n.

>>> [p for p in partitions(6, k=2)]

[{1: 6}, {1: 6}, {1: 6}, {1: 6}]

If you want to build a list of the returned dictionaries then make a copy of them:

>>> [p.copy() for p in partitions(6, k=2)] # doctest: +SKIP

[{2: 3}, {1: 2, 2: 2}, {1: 4, 2: 1}, {1: 6}]
>>> [(M, p.copy()) for M, p in partitions(6, k=2, size=True)] # doctest: +SKIP
[(3, {2: 3}), (4, {1: 2, 2: 2}), (5, {1: 4, 2: 1}), (6, {1: 6})]

Reference: modified from Tim Peter’s version to allow for k and m values:
code.activestate.com/recipes/218332-generator-for-integer-partitions/

sympy.utilities.iterables.permute_signs(t)
Return iterator in which the signs of non-zero elements of t are permuted.

Examples

>>> from sympy.utilities.iterables import permute_signs

>>> list(permute_signs((0, 1, 2)))
[(0, 1, 2), (0, -1, 2), (0, 1, -2), (0, -1, -2)]

sympy.utilities.iterables.postfixes(seq)
Generate all postfixes of a sequence.

Examples

>>> from sympy.utilities.iterables import postfixes

>>> list(postfixes([1,2,3,4]))
[[4], [3, 4], [2, 3, 4], [1, 2, 3, 4]]

5.37. Utilities 1471

SymPy Documentation, Release 1.3

sympy.utilities.iterables.postorder_traversal(node, keys=None)
Do a postorder traversal of a tree.
This generator recursively yields nodes that it has visited in a postorder fashion. That
is, it descends through the tree depth-first to yield all of a node’s children’s postorder
traversal before yielding the node itself.
Parameters node : sympy expression
The expression to traverse.
keys : (default None) sort key(s)
The key(s) used to sort args of Basic objects. When None, args of
Basic objects are processed in arbitrary order. If key is defined, it
will be passed along to ordered() as the only key(s) to use to sort the
arguments; if key is simply True then the default keys of ordered will
be used (node count and default_sort_key).
Yields subtree : sympy expression
All of the subtrees in the tree.

Examples

>>> from sympy.utilities.iterables import postorder_traversal

>>> from sympy.abc import w, x, y, z

The nodes are returned in the order that they are encountered unless key is given; simply
passing key=True will guarantee that the traversal is unique.

>>> list(postorder_traversal(w + (x + y)*z)) # doctest: +SKIP

[z, y, x, x + y, z*(x + y), w, w + z*(x + y)]
>>> list(postorder_traversal(w + (x + y)*z, keys=True))
[w, z, x, y, x + y, z*(x + y), w + z*(x + y)]

sympy.utilities.iterables.prefixes(seq)
Generate all prefixes of a sequence.

Examples

>>> from sympy.utilities.iterables import prefixes

>>> list(prefixes([1,2,3,4]))
[[1], [1, 2], [1, 2, 3], [1, 2, 3, 4]]

sympy.utilities.iterables.reshape(seq, how)
Reshape the sequence according to the template in how.

Examples

>>> from sympy.utilities import reshape

>>> seq = list(range(1, 9))

1472 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> reshape(seq, [4]) # lists of 4

[[1, 2, 3, 4], [5, 6, 7, 8]]

>>> reshape(seq, (4,)) # tuples of 4

[(1, 2, 3, 4), (5, 6, 7, 8)]

>>> reshape(seq, (2, 2)) # tuples of 4

[(1, 2, 3, 4), (5, 6, 7, 8)]

>>> reshape(seq, (2, [2])) # (i, i, [i, i])

[(1, 2, [3, 4]), (5, 6, [7, 8])]

>>> reshape(seq, ((2,), [2])) # etc....

[((1, 2), [3, 4]), ((5, 6), [7, 8])]

>>> reshape(seq, (1, [2], 1))

[(1, [2, 3], 4), (5, [6, 7], 8)]

>>> reshape(tuple(seq), ([[1], 1, (2,)],))

(([[1], 2, (3, 4)],), ([[5], 6, (7, 8)],))

>>> reshape(tuple(seq), ([1], 1, (2,)))

(([1], 2, (3, 4)), ([5], 6, (7, 8)))

>>> reshape(list(range(12)), [2, [3], {2}, (1, (3,), 1)])

[[0, 1, [2, 3, 4], {5, 6}, (7, (8, 9, 10), 11)]]

sympy.utilities.iterables.rotate_left(x, y)
Left rotates a list x by the number of steps specified in y.

Examples

>>> from sympy.utilities.iterables import rotate_left

>>> a = [0, 1, 2]
>>> rotate_left(a, 1)
[1, 2, 0]

sympy.utilities.iterables.rotate_right(x, y)
Right rotates a list x by the number of steps specified in y.

Examples

>>> from sympy.utilities.iterables import rotate_right

>>> a = [0, 1, 2]
>>> rotate_right(a, 1)
[2, 0, 1]

sympy.utilities.iterables.runs(seq, op=<built-in function gt>)

Group the sequence into lists in which successive elements all compare the same with
the comparison operator, op: op(seq[i + 1], seq[i]) is True from all elements in a run.

5.37. Utilities 1473

SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.iterables import runs

>>> from operator import ge
>>> runs([0, 1, 2, 2, 1, 4, 3, 2, 2])
[[0, 1, 2], [2], [1, 4], [3], [2], [2]]
>>> runs([0, 1, 2, 2, 1, 4, 3, 2, 2], op=ge)
[[0, 1, 2, 2], [1, 4], [3], [2, 2]]

sympy.utilities.iterables.sift(seq, keyfunc, binary=False)

Sift the sequence, seq according to keyfunc.
OUTPUT: When binary is False (default), the output is a dictionary where elements of
seq are stored in a list keyed to the value of keyfunc for that element. If binary is True
then a tuple with lists T and F are returned where T is a list containing elements of seq
for which keyfunc was True and F containing those elements for which keyfunc was
False; a ValueError is raised if the keyfunc is not binary.
See also:
ordered

Examples

>>> from sympy.utilities import sift

>>> from sympy.abc import x, y
>>> from sympy import sqrt, exp, pi, Tuple

>>> sift(range(5), lambda x: x % 2)

{0: [0, 2, 4], 1: [1, 3]}

sift() returns a defaultdict() object, so any key that has no matches will give [].

>>> sift([x], lambda x: x.is_commutative)

{True: [x]}
>>> _[False]
[]

Sometimes you won’t know how many keys you will get:

>>> sift([sqrt(x), exp(x), (y**x)**2],

... lambda x: x.as_base_exp()[0])
{E: [exp(x)], x: [sqrt(x)], y: [y**(2*x)]}

Sometimes you expect the results to be binary; the results can be unpacked by setting
binary to True:

>>> sift(range(4), lambda x: x % 2, binary=True)

([1, 3], [0, 2])
>>> sift(Tuple(1, pi), lambda x: x.is_rational, binary=True)
([1], [pi])

A ValueError is raised if the predicate was not actually binary (which is a good test for
the logic where sifting is used and binary results were expected):

1474 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> unknown = exp(1) - pi # the rationality of this is unknown

>>> args = Tuple(1, pi, unknown)
>>> sift(args, lambda x: x.is_rational, binary=True)
Traceback (most recent call last):
...
ValueError: keyfunc gave non-binary output

The non-binary sifting shows that there were 3 keys generated:

>>> set(sift(args, lambda x: x.is_rational).keys())

{None, False, True}

If you need to sort the sifted items it might be better to use ordered which can econom-
ically apply multiple sort keys to a squence while sorting.
sympy.utilities.iterables.signed_permutations(t)
Return iterator in which the signs of non-zero elements of t and the order of the elements
are permuted.

Examples

>>> from sympy.utilities.iterables import signed_permutations

>>> list(signed_permutations((0, 1, 2)))
[(0, 1, 2), (0, -1, 2), (0, 1, -2), (0, -1, -2), (0, 2, 1),
(0, -2, 1), (0, 2, -1), (0, -2, -1), (1, 0, 2), (-1, 0, 2),
(1, 0, -2), (-1, 0, -2), (1, 2, 0), (-1, 2, 0), (1, -2, 0),
(-1, -2, 0), (2, 0, 1), (-2, 0, 1), (2, 0, -1), (-2, 0, -1),
(2, 1, 0), (-2, 1, 0), (2, -1, 0), (-2, -1, 0)]

sympy.utilities.iterables.subsets(seq, k=None, repetition=False)

Generates all k-subsets (combinations) from an n-element set, seq.
A k-subset of an n-element set is any subset of length exactly k. The number of k-subsets
of an n-element set is given by binomial(n, k), whereas there are 2**n subsets all together.
If k is None then all 2**n subsets will be returned from shortest to longest.

Examples

>>> from sympy.utilities.iterables import subsets

subsets(seq, k) will return the n!/k!/(n - k)! k-subsets (combinations) without repetition,
i.e. once an item has been removed, it can no longer be “taken”:

>>> list(subsets([1, 2], 2))

[(1, 2)]
>>> list(subsets([1, 2]))
[(), (1,), (2,), (1, 2)]
>>> list(subsets([1, 2, 3], 2))
[(1, 2), (1, 3), (2, 3)]

subsets(seq, k, repetition=True) will return the (n - 1 + k)!/k!/(n - 1)! combinations with

repetition:

5.37. Utilities 1475

SymPy Documentation, Release 1.3

>>> list(subsets([1, 2], 2, repetition=True))

[(1, 1), (1, 2), (2, 2)]

If you ask for more items than are in the set you get the empty set unless you allow
repetitions:

>>> list(subsets([0, 1], 3, repetition=False))

[]
>>> list(subsets([0, 1], 3, repetition=True))
[(0, 0, 0), (0, 0, 1), (0, 1, 1), (1, 1, 1)]

sympy.utilities.iterables.take(iter, n)
Return n items from iter iterator.
sympy.utilities.iterables.topological_sort(graph, key=None)
Topological sort of graph’s vertices.
Parameters ‘‘graph‘‘ : tuple[list, list[tuple[T, T]]
A tuple consisting of a list of vertices and a list of edges of a graph to
be sorted topologically.
‘‘key‘‘ : callable[T] (optional)
Ordering key for vertices on the same level. By default the natural
(e.g. lexicographic) ordering is used (in this case the base type must
implement ordering relations).

Examples

Consider a graph:

+---+ +---+ +---+

| 7 |\ | 5 | | 3 |
+---+ \ +---+ +---+
| _\___/ ____ _/ |
| / \___/ \ / |
V V V V |
+----+ +---+ |
| 11 | | 8 | |
+----+ +---+ |
| | \____ ___/ _ |
| \ \ / / \ |
V \ V V / V V
+---+ \ +---+ | +----+
| 2 | | | 9 | | | 10 |
+---+ | +---+ | +----+
\________/

where vertices are integers. This graph can be encoded using elementary Python’s data
structures as follows:

>>> V = [2, 3, 5, 7, 8, 9, 10, 11]

>>> E = [(7, 11), (7, 8), (5, 11), (3, 8), (3, 10),
... (11, 2), (11, 9), (11, 10), (8, 9)]

To compute a topological sort for graph (V, E) issue:

1476 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.utilities.iterables import topological_sort

>>> topological_sort((V, E))

[3, 5, 7, 8, 11, 2, 9, 10]

If specific tie breaking approach is needed, use key parameter:

>>> topological_sort((V, E), key=lambda v: -v)
[7, 5, 11, 3, 10, 8, 9, 2]

Only acyclic graphs can be sorted. If the input graph has a cycle, then ValueError will
be raised:
>>> topological_sort((V, E + [(10, 7)]))
Traceback (most recent call last):
...
ValueError: cycle detected

See also:
http://en.wikipedia.org/wiki/Topological_sorting
sympy.utilities.iterables.unflatten(iter, n=2)
Group iter into tuples of length n. Raise an error if the length of iter is not a multiple
of n.
sympy.utilities.iterables.uniq(seq, result=None)
Yield unique elements from seq as an iterator. The second parameter result is used
internally; it is not necessary to pass anything for this.

Examples

>>> from sympy.utilities.iterables import uniq

>>> dat = [1, 4, 1, 5, 4, 2, 1, 2]
>>> type(uniq(dat)) in (list, tuple)
False

>>> list(uniq(dat))
[1, 4, 5, 2]
>>> list(uniq(x for x in dat))
[1, 4, 5, 2]
>>> list(uniq([[1], [2, 1], [1]]))
[[1], [2, 1]]

sympy.utilities.iterables.variations(seq, n, repetition=False)
Returns a generator of the n-sized variations of seq (size N). repetition controls
whether items in seq can appear more than once;
See also:
sympy.core.compatibility.permutations, sympy.core.compatibility.product

Examples

variations(seq, n) will return N! / (N - n)! permutations without repetition of seq’s ele-

ments:

5.37. Utilities 1477

SymPy Documentation, Release 1.3

>>> from sympy.utilities.iterables import variations

>>> list(variations([1, 2], 2))
[(1, 2), (2, 1)]

variations(seq, n, True) will return the N**n permutations obtained by allowing repeti-
tion of elements:

>>> list(variations([1, 2], 2, repetition=True))

[(1, 1), (1, 2), (2, 1), (2, 2)]

If you ask for more items than are in the set you get the empty set unless you allow
repetitions:

>>> list(variations([0, 1], 3, repetition=False))

[]
>>> list(variations([0, 1], 3, repetition=True))[:4]
[(0, 0, 0), (0, 0, 1), (0, 1, 0), (0, 1, 1)]

5.37.6 Lambdify

This module provides convenient functions to transform sympy expressions to lambda func-
tions which can be used to calculate numerical values very fast.
sympy.utilities.lambdify.implemented_function(symfunc, implementation)
Add numerical implementation to function symfunc.
symfunc can be an UndefinedFunction instance, or a name string. In the latter case we
create an UndefinedFunction instance with that name.
Be aware that this is a quick workaround, not a general method to create special symbolic
functions. If you want to create a symbolic function to be used by all the machinery of
SymPy you should subclass the Function class.
Parameters symfunc : str or UndefinedFunction instance
If str, then create new UndefinedFunction with this as name. If
symf unc is an Undefined function, create a new function with the
same name and the implemented function attached.
implementation : callable
numerical implementation to be called by evalf() or lambdify
Returns afunc : sympy.FunctionClass instance
function with attached implementation

Examples

>>> from sympy.abc import x

>>> from sympy.utilities.lambdify import lambdify, implemented_function
>>> from sympy import Function
>>> f = implemented_function('f', lambda x: x+1)
>>> lam_f = lambdify(x, f(x))
>>> lam_f(4)
5

1478 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.utilities.lambdify.lambdastr(args, expr, printer=None, dummify=False)

Returns a string that can be evaluated to a lambda function.

Examples

>>> from sympy.abc import x, y, z

>>> from sympy.utilities.lambdify import lambdastr
>>> lambdastr(x, x**2)
'lambda x: (x**2)'
>>> lambdastr((x,y,z), [z,y,x])
'lambda x,y,z: ([z, y, x])'

Although tuples may not appear as arguments to lambda in Python 3, lambdastr will cre-
ate a lambda function that will unpack the original arguments so that nested arguments
can be handled:

>>> lambdastr((x, (y, z)), x + y)

'lambda _0,_1: (lambda x,y,z: (x + y))(_0,_1[0],_1[1])'

sympy.utilities.lambdify.lambdify(args, expr, modules=None, printer=None,

use_imps=True, dummify=False)
Returns an anonymous function for fast calculation of numerical values.
If not specified differently by the user, modules defaults to [”numpy”] if NumPy is in-
stalled, and [”math”, ”mpmath”, ”sympy”] if it isn’t, that is, SymPy functions are re-
placed as far as possible by either numpy functions if available, and Python’s standard
library math, or mpmath functions otherwise. To change this behavior, the “modules”
argument can be used. It accepts:
• the strings “math”, “mpmath”, “numpy”, “numexpr”, “sympy”, “tensorflow”
• any modules (e.g. math)
• dictionaries that map names of sympy functions to arbitrary functions
• lists that contain a mix of the arguments above, with higher priority given to entries
appearing first.

Warning: Note that this function uses eval, and thus shouldn’t be used on unsani-
tized input.

Arguments in the provided expression that are not valid Python identifiers are substitued
with dummy symbols. This allows for applied functions (e.g. f(t)) to be supplied as
arguments. Call the function with dummify=True to replace all arguments with dummy
symbols (if args is not a string) - for example, to ensure that the arguments do not redefine
any built-in names.
For functions involving large array calculations, numexpr can provide a significant
speedup over numpy. Please note that the available functions for numexpr are more
limited than numpy but can be expanded with implemented_function and user defined
subclasses of Function. If specified, numexpr may be the only option in modules. The
official list of numexpr functions can be found at: https://github.com/pydata/numexpr#
supported-functions

5.37. Utilities 1479

SymPy Documentation, Release 1.3

In previous releases lambdify replaced Matrix with numpy.matrix by default. As of

release 1.0 numpy.array is the default. To get the old default behavior you must pass in
[{'ImmutableDenseMatrix': numpy.matrix}, 'numpy'] to the modules kwarg.

>>> from sympy import lambdify, Matrix

>>> from sympy.abc import x, y
>>> import numpy
>>> array2mat = [{'ImmutableDenseMatrix': numpy.matrix}, 'numpy']
>>> f = lambdify((x, y), Matrix([x, y]), modules=array2mat)
>>> f(1, 2)
matrix([[1],
[2]])

Examples

>>> from sympy.utilities.lambdify import implemented_function

>>> from sympy import sqrt, sin, Matrix
>>> from sympy import Function
>>> from sympy.abc import w, x, y, z

>>> f = lambdify(x, x**2)

>>> f(2)
4
>>> f = lambdify((x, y, z), [z, y, x])
>>> f(1,2,3)
[3, 2, 1]
>>> f = lambdify(x, sqrt(x))
>>> f(4)
2.0
>>> f = lambdify((x, y), sin(x*y)**2)
>>> f(0, 5)
0.0
>>> row = lambdify((x, y), Matrix((x, x + y)).T, modules='sympy')
>>> row(1, 2)
Matrix([[1, 3]])

Tuple arguments are handled and the lambdified function should be called with the same
type of arguments as were used to create the function.:

>>> f = lambdify((x, (y, z)), x + y)

>>> f(1, (2, 4))
3

A more robust way of handling this is to always work with flattened arguments:

>>> from sympy.utilities.iterables import flatten

>>> args = w, (x, (y, z))
>>> vals = 1, (2, (3, 4))
>>> f = lambdify(flatten(args), w + x + y + z)
>>> f(*flatten(vals))
10

Functions present in expr can also carry their own numerical implementations, in a
callable attached to the _imp_ attribute. Usually you attach this using the imple-
mented_function factory:

1480 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> f = implemented_function(Function('f'), lambda x: x+1)

>>> func = lambdify(x, f(x))
>>> func(4)
5

lambdify always prefers _imp_ implementations to implementations in other names-

paces, unless the use_imps input parameter is False.
Usage with Tensorflow module:

>>> import tensorflow as tf

>>> f = Max(x, sin(x))
>>> func = lambdify(x, f, 'tensorflow')
>>> result = func(tf.constant(1.0))
>>> result # a tf.Tensor representing the result of the calculation
<tf.Tensor 'Maximum:0' shape=() dtype=float32>
>>> sess = tf.Session()
>>> sess.run(result) # compute result
1.0
>>> var = tf.Variable(1.0)
>>> sess.run(tf.global_variables_initializer())
>>> sess.run(func(var)) # also works for tf.Variable and tf.Placeholder
1.0
>>> tensor = tf.constant([[1.0, 2.0], [3.0, 4.0]]) # works with any shape tensor
>>> sess.run(func(tensor))
array([[ 1., 2.],
[ 3., 4.]], dtype=float32)

Usage

(1) Use one of the provided modules:

>>> from sympy import sin, tan, gamma

>>> from sympy.abc import x, y
>>> f = lambdify(x, sin(x), ”math”)

Attention: Functions that are not in the math module will throw a name
error when the function definition is evaluated! So this would be better:

>>> f = lambdify(x, sin(x)*gamma(x), (”math”, ”mpmath”, ”sympy”))

(2) Use some other module:

>>> import numpy

>>> f = lambdify((x,y), tan(x*y), numpy)

Attention: There are naming differences between numpy and sympy. So if

you simply take the numpy module, e.g. sympy.atan will not be translated to
numpy.arctan. Use the modified module instead by passing the string “numpy”:

>>> f = lambdify((x,y), tan(x*y), ”numpy”)

>>> f(1, 2)
-2.18503986326
(continues on next page)

5.37. Utilities 1481

SymPy Documentation, Release 1.3

(continued from previous page)

>>> from numpy import array
>>> f(array([1, 2, 3]), array([2, 3, 5]))
[-2.18503986 -0.29100619 -0.8559934 ]

In the above examples, the generated functions can accept scalar values or numpy
arrays as arguments. However, in some cases the generated function relies on the
input being a numpy array:

>>> from sympy import Piecewise

>>> f = lambdify(x, Piecewise((x, x <= 1), (1/x, x > 1)), ”numpy”)
>>> f(array([-1, 0, 1, 2]))
[-1. 0. 1. 0.5]
>>> f(0)
Traceback (most recent call last):
...
ZeroDivisionError: division by zero

In such cases, the input should be wrapped in a numpy array: >>>

float(f(array([0]))) 0.0
Or if numpy functionality is not required another module can be used: >>> f =
lambdify(x, Piecewise((x, x <= 1), (1/x, x > 1)), “math”) >>> f(0) 0
(3) Use a dictionary defining custom functions:

>>> def my_cool_function(x): return 'sin(%s) is cool' % x

>>> myfuncs = {”sin” : my_cool_function}
>>> f = lambdify(x, sin(x), myfuncs); f(1)
'sin(1) is cool'

5.37.7 Memoization

sympy.utilities.memoization.assoc_recurrence_memo(base_seq)
Memo decorator for associated sequences defined by recurrence starting from base
base_seq(n) – callable to get base sequence elements
XXX works only for Pn0 = base_seq(0) cases XXX works only for m <= n cases
sympy.utilities.memoization.recurrence_memo(initial)
Memo decorator for sequences defined by recurrence
See usage examples e.g. in the specfun/combinatorial module

5.37.8 Miscellaneous

Miscellaneous stuff that doesn’t really fit anywhere else.

sympy.utilities.misc.debug(*args)
Print *args if SYMPY_DEBUG is True, else do nothing.
sympy.utilities.misc.debug_decorator(func)
If SYMPY_DEBUG is True, it will print a nice execution tree with arguments and results
of all decorated functions, else do nothing.

1482 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.utilities.misc.filldedent(s, w=70)
Strips leading and trailing empty lines from a copy of s, then dedents, fills and returns
it.
Empty line stripping serves to deal with docstrings like this one that start with a newline
after the initial triple quote, inserting an empty line at the beginning of the string.
sympy.utilities.misc.find_executable(executable, path=None)
Try to find ‘executable’ in the directories listed in ‘path’ (a string listing directories sep-
arated by ‘os.pathsep’; defaults to os.environ[‘PATH’]). Returns the complete filename
or None if not found
sympy.utilities.misc.func_name(x, short=False)
Return function name of x (if defined) else the type(x). If short is True and there is a
shorter alias for the result, return the alias.
See also:
sympy.core.compatibility (page 204)

Examples

>>> from sympy.utilities.misc import func_name

>>> from sympy.abc import x
>>> func_name(x < 1)
'StrictLessThan'
>>> func_name(x < 1, short=True)
'Lt'

sympy.utilities.misc.rawlines(s)
Return a cut-and-pastable string that, when printed, is equivalent to the input. The
string returned is formatted so it can be indented nicely within tests; in some cases it is
wrapped in the dedent function which has to be imported from textwrap.

Examples

Note: because there are characters in the examples below that need to be escaped be-
cause they are themselves within a triple quoted docstring, expressions below look more
complicated than they would be if they were printed in an interpreter window.

>>> from sympy.utilities.misc import rawlines

>>> from sympy import TableForm
>>> s = str(TableForm([[1, 10]], headings=(None, ['a', 'bee'])))
>>> print(rawlines(s))
(
'a bee\n'
'-----\n'
'1 10 '
)
>>> print(rawlines('''this
... that'''))
dedent('''\
this
that''')

5.37. Utilities 1483

SymPy Documentation, Release 1.3

>>> print(rawlines('''this
... that
... '''))
dedent('''\
this
that
''')

>>> s = ”””this
... is a triple '''
... ”””
>>> print(rawlines(s))
dedent(”””\
this
is a triple '''
”””)

>>> print(rawlines('''this
... that
... '''))
(
'this\n'
'that\n'
' '
)

sympy.utilities.misc.replace(string, *reps)
Return string with all keys in reps replaced with their corresponding values, longer
strings first, irrespective of the order they are given. reps may be passed as tuples or a
single mapping.

References

[R599]

Examples

>>> from sympy.utilities.misc import replace

>>> replace('foo', {'oo': 'ar', 'f': 'b'})
'bar'
>>> replace(”spamham sha”, (”spam”, ”eggs”), (”sha”,”md5”))
'eggsham md5'

There is no guarantee that a unique answer will be obtained if keys in a mapping overlap
(i.e. are the same length and have some identical sequence at the beginning/end):
>>> reps = [
... ('ab', 'x'),
... ('bc', 'y')]
>>> replace('abc', *reps) in ('xc', 'ay')
True

sympy.utilities.misc.translate(s, a, b=None, c=None)

Return s where characters have been replaced or deleted.

1484 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.utilities.misc import translate

>>> from sympy.core.compatibility import unichr
>>> abc = 'abc'
>>> translate(abc, None, 'a')
'bc'
>>> translate(abc, {'a': 'x'}, 'c')
'xb'
>>> translate(abc, {'abc': 'x', 'a': 'y'})
'x'

>>> translate('abcd', 'ac', 'AC', 'd')

'AbC'

There is no guarantee that a unique answer will be obtained if keys in a mapping overlap
are the same length and have some identical sequences at the beginning/end:

>>> translate(abc, {'ab': 'x', 'bc': 'y'}) in ('xc', 'ay')

True

Syntax

translate(s, None, deletechars): all characters in deletechars are deleted

translate(s, map [,deletechars]): all characters in deletechars (if provided) are
deleted then the replacements defined by map are made; if the keys of map are
strings then the longer ones are handled first. Multicharacter deletions should have
a value of ‘’.
translate(s, oldchars, newchars, deletechars) all characters in deletechars are
deleted then each character in oldchars is replaced with the corresponding char-
acter in newchars

5.37.9 PKGDATA

pkgdata is a simple, extensible way for a package to acquire data file resources.
The getResource function is equivalent to the standard idioms, such as the following minimal
implementation:

import sys, os

def getResource(identifier, pkgname=__name__):

pkgpath = os.path.dirname(sys.modules[pkgname].__file__)
path = os.path.join(pkgpath, identifier)
return open(os.path.normpath(path), mode='rb')

When a __loader__ is present on the module given by __name__, it will defer getResource to
its get_data implementation and return it as a file-like object (such as StringIO).
sympy.utilities.pkgdata.get_resource(identifier, pkgname=’sympy.utilities.pkgdata’)
Acquire a readable object for a given package name and identifier. An IOError will be
raised if the resource can not be found.

5.37. Utilities 1485

SymPy Documentation, Release 1.3

For example:

mydata = get_resource('mypkgdata.jpg').read()

Note that the package name must be fully qualified, if given, such that it would be found
in sys.modules.
In some cases, getResource will return a real file object. In that case, it may be useful to
use its name attribute to get the path rather than use it as a file-like object. For example,
you may be handing data off to a C API.

5.37.10 pytest

py.test hacks to support XFAIL/XPASS

sympy.utilities.pytest.SKIP(reason)
Similar to skip(), but this is a decorator.
sympy.utilities.pytest.raises(expectedException, code=None)
Tests that code raises the exception expectedException.
code may be a callable, such as a lambda expression or function name.
If code is not given or None, raises will return a context manager for use in with state-
ments; the code to execute then comes from the scope of the with.
raises() does nothing if the callable raises the expected exception, otherwise it raises
an AssertionError.

Examples

>>> from sympy.utilities.pytest import raises

>>> raises(ZeroDivisionError, lambda: 1/0)

>>> raises(ZeroDivisionError, lambda: 1/2)
Traceback (most recent call last):
...
AssertionError: DID NOT RAISE

>>> with raises(ZeroDivisionError):

... n = 1/0
>>> with raises(ZeroDivisionError):
... n = 1/2
Traceback (most recent call last):
...
AssertionError: DID NOT RAISE

Note that you cannot test multiple statements via with raises:

>>> with raises(ZeroDivisionError):

... n = 1/0 # will execute and raise, aborting the ``with``
... n = 9999/0 # never executed

This is just what with is supposed to do: abort the contained statement sequence at the
first exception and let the context manager deal with the exception.

1486 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

To test multiple statements, you’ll need a separate with for each:

>>> with raises(ZeroDivisionError):

... n = 1/0 # will execute and raise
>>> with raises(ZeroDivisionError):
... n = 9999/0 # will also execute and raise

5.37.11 Randomised Testing

Helpers for randomized testing

sympy.utilities.randtest.random_complex_number(a=2, b=-1, c=3, d=1, ratio-
nal=False, tolerance=None)
Return a random complex number.
To reduce chance of hitting branch cuts or anything, we guarantee b <= Im z <= d, a
<= Re z <= c
When rational is True, a rational approximation to a random number is obtained within
specified tolerance, if any.
sympy.utilities.randtest.test_derivative_numerically(f, z, tol=1e-06, a=2, b=-
1, c=3, d=1)
Test numerically that the symbolically computed derivative of f with respect to z is cor-
rect.
This routine does not test whether there are Floats present with precision higher than
15 digits so if there are, your results may not be what you expect due to round-off errors.

Examples

>>> from sympy import sin

>>> from sympy.abc import x
>>> from sympy.utilities.randtest import test_derivative_numerically as td
>>> td(sin(x), x)
True

sympy.utilities.randtest.verify_numerically(f, g, z=None, tol=1e-06, a=2, b=-1,

c=3, d=1)
Test numerically that f and g agree when evaluated in the argument z.
If z is None, all symbols will be tested. This routine does not test whether there are
Floats present with precision higher than 15 digits so if there are, your results may not
be what you expect due to round- off errors.

Examples

>>> from sympy import sin, cos

>>> from sympy.abc import x
>>> from sympy.utilities.randtest import verify_numerically as tn
>>> tn(sin(x)**2 + cos(x)**2, 1, x)
True

5.37. Utilities 1487

SymPy Documentation, Release 1.3

5.37.12 Run Tests

This is our testing framework.

Goals:
• it should be compatible with py.test and operate very similarly (or identically)
• doesn’t require any external dependencies
• preferably all the functionality should be in this file only
• no magic, just import the test file and execute the test functions, that’s it
• portable
class sympy.utilities.runtests.PyTestReporter(verbose=False, tb=’short’, col-
ors=True, force_colors=False,
split=None)
Py.test like reporter. Should produce output identical to py.test.
write(text, color=”, align=’left’, width=None, force_colors=False)
Prints a text on the screen.
It uses sys.stdout.write(), so no readline library is necessary.
Parameters color : choose from the colors below, “” means default color
align : “left”/”right”, “left” is a normal print, “right” is aligned on
the right-hand side of the screen, filled with spaces if necessary
width : the screen width
class sympy.utilities.runtests.Reporter
Parent class for all reporters.
class sympy.utilities.runtests.SymPyDocTestFinder(verbose=False,
parser=<doctest.DocTestParser
object>, recurse=True, ex-
clude_empty=True)
A class used to extract the DocTests that are relevant to a given object, from its doc-
string and the docstrings of its contained objects. Doctests can currently be extracted
from the following object types: modules, functions, classes, methods, staticmethods,
classmethods, and properties.
Modified from doctest’s version to look harder for code that appears comes from a dif-
ferent module. For example, the @vectorize decorator makes it look like functions come
from multidimensional.py even though their code exists elsewhere.
class sympy.utilities.runtests.SymPyDocTestRunner(checker=None, ver-
bose=None, optionflags=0)
A class used to run DocTest test cases, and accumulate statistics. The run method is
used to process a single DocTest case. It returns a tuple (f, t), where t is the number
of test cases tried, and f is the number of test cases that failed.
Modified from the doctest version to not reset the sys.displayhook (see issue 5140).
See the docstring of the original DocTestRunner for more information.
run(test, compileflags=None, out=None, clear_globs=True)
Run the examples in test, and display the results using the writer function out.
The examples are run in the namespace test.globs. If clear_globs is true (the
default), then this namespace will be cleared after the test runs, to help with garbage

1488 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

collection. If you would like to examine the namespace after the test completes, then
use clear_globs=False.
compileflags gives the set of flags that should be used by the Python compiler when
running the examples. If not specified, then it will default to the set of future-import
flags that apply to globs.
The output of each example is checked using SymPyDocTestRunner.check_output,
and the results are formatted by the SymPyDocTestRunner.report_* methods.
class sympy.utilities.runtests.SymPyOutputChecker
Compared to the OutputChecker from the stdlib our OutputChecker class supports nu-
merical comparison of floats occurring in the output of the doctest examples
check_output(want, got, optionflags)
Return True iff the actual output from an example (got) matches the expected out-
put (want). These strings are always considered to match if they are identical; but
depending on what option flags the test runner is using, several non-exact match
types are also possible. See the documentation for T estRunner for more information
about option flags.
sympy.utilities.runtests.SymPyTestResults
alias of sympy.utilities.runtests.TestResults
sympy.utilities.runtests.convert_to_native_paths(lst)
Converts a list of ‘/’ separated paths into a list of native (os.sep separated) paths and
converts to lowercase if the system is case insensitive.
sympy.utilities.runtests.doctest(*paths, **kwargs)
Runs doctests in all *.py files in the sympy directory which match any of the given strings
in paths or all tests if paths=[].
Notes:
• Paths can be entered in native system format or in unix, forward-slash format.
• Files that are on the blacklist can be tested by providing their path; they are only
excluded if no paths are given.

Examples

>>> import sympy

Run all tests:

>>> sympy.doctest() # doctest: +SKIP

Run one file:

>>> sympy.doctest(”sympy/core/basic.py”) # doctest: +SKIP

>>> sympy.doctest(”polynomial.rst”) # doctest: +SKIP

Run all tests in sympy/functions/ and some particular file:

>>> sympy.doctest(”/functions”, ”basic.py”) # doctest: +SKIP

Run any file having polynomial in its name, doc/src/modules/polynomial.rst,

sympy/functions/special/polynomials.py, and sympy/polys/polynomial.py:

5.37. Utilities 1489

SymPy Documentation, Release 1.3

>>> sympy.doctest(”polynomial”) # doctest: +SKIP

The split option can be passed to split the test run into parts. The split currently only
splits the test files, though this may change in the future. split should be a string of
the form ‘a/b’, which will run part a of b. Note that the regular doctests and the Sphinx
doctests are split independently. For instance, to run the first half of the test suite:

>>> sympy.doctest(split='1/2') # doctest: +SKIP

The subprocess and verbose options are the same as with the function test(). See the
docstring of that function for more information.
sympy.utilities.runtests.get_sympy_dir()
Returns the root sympy directory and set the global value indicating whether the system
is case sensitive or not.
sympy.utilities.runtests.run_all_tests(test_args=(), test_kwargs=None,
doctest_args=(), doctest_kwargs=None,
examples_args=(), exam-
ples_kwargs=None)
Run all tests.
Right now, this runs the regular tests (bin/test), the doctests (bin/doctest), the examples
(examples/all.py), and the sage tests (see sympy/external/tests/test_sage.py).
This is what setup.py test uses.
You can pass arguments and keyword arguments to the test functions that support them
(for now, test, doctest, and the examples). See the docstrings of those functions for a
description of the available options.
For example, to run the solvers tests with colors turned off:

>>> from sympy.utilities.runtests import run_all_tests

>>> run_all_tests(test_args=(”solvers”,),
... test_kwargs={”colors:False”}) # doctest: +SKIP

sympy.utilities.runtests.run_in_subprocess_with_hash_randomization(function,
func-
tion_args=(),
func-
tion_kwargs=None,
command=’/opt/conda/envs
release-
docs/bin/python’,
mod-
ule=’sympy.utilities.runtest
force=False)
Run a function in a Python subprocess with hash randomization enabled.
If hash randomization is not supported by the version of Python given, it returns False.
Otherwise, it returns the exit value of the command. The function is passed to sys.exit(),
so the return value of the function will be the return value.
The environment variable PYTHONHASHSEED is used to seed Python’s hash random-
ization. If it is set, this function will return False, because starting a new subprocess
is unnecessary in that case. If it is not set, one is set at random, and the tests are run.
Note that if this environment variable is set when Python starts, hash randomization is

1490 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

automatically enabled. To force a subprocess to be created even if PYTHONHASHSEED

is set, pass force=True. This flag will not force a subprocess in Python versions that do
not support hash randomization (see below), because those versions of Python do not
support the -R flag.
function should be a string name of a function that is importable from the module mod-
ule, like “_test”. The default for module is “sympy.utilities.runtests”. function_args
and function_kwargs should be a repr-able tuple and dict, respectively. The default
Python command is sys.executable, which is the currently running Python command.
This function is necessary because the seed for hash randomization must be set by the
environment variable before Python starts. Hence, in order to use a predetermined seed
for tests, we must start Python in a separate subprocess.
Hash randomization was added in the minor Python versions 2.6.8, 2.7.3, 3.1.5, and
3.2.3, and is enabled by default in all Python versions after and including 3.3.0.

Examples

>>> from sympy.utilities.runtests import (

... run_in_subprocess_with_hash_randomization)
>>> # run the core tests in verbose mode
>>> run_in_subprocess_with_hash_randomization(”_test”,
... function_args=(”core”,),
... function_kwargs={'verbose': True}) # doctest: +SKIP
# Will return 0 if sys.executable supports hash randomization and tests
# pass, 1 if they fail, and False if it does not support hash
# randomization.

sympy.utilities.runtests.split_list(l, split, density=None)

Splits a list into part a of b
split should be a string of the form ‘a/b’. For instance, ‘1/3’ would give the split one of
three.
If the length of the list is not divisible by the number of splits, the last split will have
more items.
density may be specified as a list. If specified, tests will be balanced so that each split
has as equal-as-possible amount of mass according to density.

>>> from sympy.utilities.runtests import split_list

>>> a = list(range(10))
>>> split_list(a, '1/3')
[0, 1, 2]
>>> split_list(a, '2/3')
[3, 4, 5]
>>> split_list(a, '3/3')
[6, 7, 8, 9]

sympy.utilities.runtests.sympytestfile(filename, module_relative=True,
name=None, package=None,
globs=None, verbose=None, re-
port=True, optionflags=0, extra-
globs=None, raise_on_error=False,
parser=<doctest.DocTestParser object>,
encoding=None)

5.37. Utilities 1491

SymPy Documentation, Release 1.3

Test examples in the given file. Return (#failures, #tests).

Optional keyword arg module_relative specifies how filenames should be interpreted:
• If module_relative is True (the default), then filename specifies a module-relative
path. By default, this path is relative to the calling module’s directory; but if the
package argument is specified, then it is relative to that package. To ensure os-
independence, filename should use “/” characters to separate path segments, and
should not be an absolute path (i.e., it may not begin with “/”).
• If module_relative is False, then filename specifies an os-specific path. The path
may be absolute or relative (to the current working directory).
Optional keyword arg name gives the name of the test; by default use the file’s basename.
Optional keyword argument package is a Python package or the name of a Python pack-
age whose directory should be used as the base directory for a module relative filename.
If no package is specified, then the calling module’s directory is used as the base direc-
tory for module relative filenames. It is an error to specify package if module_relative
is False.
Optional keyword arg globs gives a dict to be used as the globals when executing exam-
ples; by default, use {}. A copy of this dict is actually used for each docstring, so that
each docstring’s examples start with a clean slate.
Optional keyword arg extraglobs gives a dictionary that should be merged into the
globals that are used to execute examples. By default, no extra globals are used.
Optional keyword arg verbose prints lots of stuff if true, prints only failures if false; by
default, it’s true iff “-v” is in sys.argv.
Optional keyword arg report prints a summary at the end when true, else prints nothing
at the end. In verbose mode, the summary is detailed, else very brief (in fact, empty if
all tests passed).
Optional keyword arg optionflags or’s together module constants, and defaults to 0.
Possible values (see the docs for details):
• DONT_ACCEPT_TRUE_FOR_1
• DONT_ACCEPT_BLANKLINE
• NORMALIZE_WHITESPACE
• ELLIPSIS
• SKIP
• IGNORE_EXCEPTION_DETAIL
• REPORT_UDIFF
• REPORT_CDIFF
• REPORT_NDIFF
• REPORT_ONLY_FIRST_FAILURE
Optional keyword arg raise_on_error raises an exception on the first unexpected ex-
ception or failure. This allows failures to be post-mortem debugged.
Optional keyword arg parser specifies a DocTestParser (or subclass) that should be used
to extract tests from the files.

1492 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Optional keyword arg encoding specifies an encoding that should be used to convert the
file to unicode.
Advanced tomfoolery: testmod runs methods of a local instance of class doctest.Tester,
then merges the results into (or creates) global Tester instance doctest.master. Methods
of doctest.master can be called directly too, if you want to do something unusual. Passing
report=0 to testmod is especially useful then, to delay displaying a summary. Invoke
doctest.master.summarize(verbose) when you’re done fiddling.
sympy.utilities.runtests.test(*paths, **kwargs)
Run tests in the specified test_*.py files.
Tests in a particular test_*.py file are run if any of the given strings in paths matches a
part of the test file’s path. If paths=[], tests in all test_*.py files are run.
Notes:
• If sort=False, tests are run in random order (not default).
• Paths can be entered in native system format or in unix, forward-slash format.
• Files that are on the blacklist can be tested by providing their path; they are only
excluded if no paths are given.
Explanation of test results

Out- Meaning
put
. passed
F failed
X XPassed (expected to fail but passed)
f XFAILed (expected to fail and indeed failed)
s skipped
w slow
T timeout (e.g., when --timeout is used)
K KeyboardInterrupt (when running the slow tests with --slow, you can interrupt
one of them without killing the test runner)

Colors have no additional meaning and are used just to facilitate interpreting the output.

Examples

>>> import sympy

Run all tests:

>>> sympy.test() # doctest: +SKIP

Run one file:

>>> sympy.test(”sympy/core/tests/test_basic.py”) # doctest: +SKIP
>>> sympy.test(”_basic”) # doctest: +SKIP

Run all tests in sympy/functions/ and some particular file:

>>> sympy.test(”sympy/core/tests/test_basic.py”,
... ”sympy/functions”) # doctest: +SKIP

5.37. Utilities 1493

SymPy Documentation, Release 1.3

Run all tests in sympy/core and sympy/utilities:

>>> sympy.test(”/core”, ”/util”) # doctest: +SKIP

Run specific test from a file:

>>> sympy.test(”sympy/core/tests/test_basic.py”,
... kw=”test_equality”) # doctest: +SKIP

Run specific test from any file:

>>> sympy.test(kw=”subs”) # doctest: +SKIP

Run the tests with verbose mode on:

>>> sympy.test(verbose=True) # doctest: +SKIP

Don’t sort the test output:

>>> sympy.test(sort=False) # doctest: +SKIP

Turn on post-mortem pdb:

>>> sympy.test(pdb=True) # doctest: +SKIP

Turn off colors:

>>> sympy.test(colors=False) # doctest: +SKIP

Force colors, even when the output is not to a terminal (this is useful, e.g., if you are
piping to less -r and you still want colors)

>>> sympy.test(force_colors=False) # doctest: +SKIP

The traceback verboseness can be set to “short” or “no” (default is “short”)

>>> sympy.test(tb='no') # doctest: +SKIP

The split option can be passed to split the test run into parts. The split currently only
splits the test files, though this may change in the future. split should be a string of the
form ‘a/b’, which will run part a of b. For instance, to run the first half of the test suite:

>>> sympy.test(split='1/2') # doctest: +SKIP

The time_balance option can be passed in conjunction with split. If

time_balance=True (the default for sympy.test), sympy will attempt to split the
tests such that each split takes equal time. This heuristic for balancing is based on
pre-recorded test data.

>>> sympy.test(split='1/2', time_balance=True) # doctest: +SKIP

You can disable running the tests in a separate subprocess using subprocess=False.
This is done to support seeding hash randomization, which is enabled by default in the
Python versions where it is supported. If subprocess=False, hash randomization is en-
abled/disabled according to whether it has been enabled or not in the calling Python
process. However, even if it is enabled, the seed cannot be printed unless it is called
from a new Python process.

1494 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Hash randomization was added in the minor Python versions 2.6.8, 2.7.3, 3.1.5, and
3.2.3, and is enabled by default in all Python versions after and including 3.3.0.
If hash randomization is not supported subprocess=False is used automatically.

>>> sympy.test(subprocess=False) # doctest: +SKIP

To set the hash randomization seed, set the environment variable PYTHONHASHSEED before
running the tests. This can be done from within Python using

>>> import os
>>> os.environ['PYTHONHASHSEED'] = '42' # doctest: +SKIP

Or from the command line using

$ PYTHONHASHSEED=42 ./bin/test
If the seed is not set, a random seed will be chosen.
Note that to reproduce the same hash values, you must use both the same seed as well
as the same architecture (32-bit vs. 64-bit).

5.37.13 Source Code Inspection

This module adds several functions for interactive source code inspection.
sympy.utilities.source.get_class(lookup_view)
Convert a string version of a class name to the object.
For example, get_class(‘sympy.core.Basic’) will return class Basic located in module
sympy.core
sympy.utilities.source.get_mod_func(callback)
splits the string path to a class into a string path to the module and the name of the class.
For example:

>>> from sympy.utilities.source import get_mod_func

>>> get_mod_func('sympy.core.basic.Basic')
('sympy.core.basic', 'Basic')

sympy.utilities.source.source(object)
Prints the source code of a given object.

5.37.14 Timing Utilities

Simple tools for timing functions’ execution, when IPython is not available.
sympy.utilities.timeutils.timed(func, setup=’pass’, limit=None)
Adaptively measure execution time of a function.

5.37. Utilities 1495

SymPy Documentation, Release 1.3

5.38 Parsing input

5.38.1 Parsing Functions Reference

sympy.parsing.sympy_parser.parse_expr(s, local_dict=None, transforma-

tions=(<function lambda_notation>,
<function auto_symbol>, <func-
tion repeated_decimals>, <func-
tion auto_number>, <function facto-
rial_notation>), global_dict=None, evalu-
ate=True)
Converts the string s to a SymPy expression, in local_dict
Parameters s : str
The string to parse.
local_dict : dict, optional
A dictionary of local variables to use when parsing.
global_dict : dict, optional
A dictionary of global variables. By default, this is initialized with
from sympy import *; provide this parameter to override this be-
havior (for instance, to parse ”Q & S”).
transformations : tuple, optional
A tuple of transformation functions used to modify the tokens of the
parsed expression before evaluation. The default transformations
convert numeric literals into their SymPy equivalents, convert un-
defined variables into SymPy symbols, and allow the use of standard
mathematical factorial notation (e.g. x!).
evaluate : bool, optional
When False, the order of the arguments will remain as they were in
the string and automatic simplification that would normally occur is
suppressed. (see examples)
See also:
stringify_expr (page 1497), eval_expr (page 1497), standard_transformations
(page 1497), implicit_multiplication_application (page 1499)

Examples

>>> from sympy.parsing.sympy_parser import parse_expr

>>> parse_expr(”1/2”)
1/2
>>> type(_)
<class 'sympy.core.numbers.Half'>
>>> from sympy.parsing.sympy_parser import standard_transformations,\
... implicit_multiplication_application
>>> transformations = (standard_transformations +
... (implicit_multiplication_application,))
(continues on next page)

1496 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> parse_expr(”2x”, transformations=transformations)
2*x

When evaluate=False, some automatic simplifications will not occur:

>>> parse_expr(”2**3”), parse_expr(”2**3”, evaluate=False)

(8, 2**3)

In addition the order of the arguments will not be made canonical. This feature allows
one to tell exactly how the expression was entered:

>>> a = parse_expr('1 + x', evaluate=False)

>>> b = parse_expr('x + 1', evaluate=0)
>>> a == b
False
>>> a.args
(1, x)
>>> b.args
(x, 1)

sympy.parsing.sympy_parser.stringify_expr(s, local_dict, global_dict, transforma-

tions)
Converts the string s to Python code, in local_dict
Generally, parse_expr should be used.
sympy.parsing.sympy_parser.eval_expr(code, local_dict, global_dict)
Evaluate Python code generated by stringify_expr.
Generally, parse_expr should be used.
sympy.parsing.maxima.parse_maxima(str, globals=None, name_dict={})
sympy.parsing.mathematica.mathematica(s, additional_translations=None)
Users can add their own translation dictionary # Example In [1]: mathe-
matica(‘Log3[9]’, {‘Log3[x]’:’log(x,3)’}) Out[1]: 2 In [2]: mathematica(‘F[7,5,3]’,
{‘F[x]’:’Max(*x)*Min(*x)’}) Out[2]: 21 variable-length argument needs ‘’ character

5.38.2 Parsing Transformations Reference

A transformation is a function that accepts the arguments tokens, local_dict,

global_dict and returns a list of transformed tokens. They can be used by passing a list
of functions to parse_expr() and are applied in the order given.
sympy.parsing.sympy_parser.standard_transformations = (<function lambda_notation>, <functio
Standard transformations for parse_expr() (page 1496). Inserts calls to Symbol, Inte-
ger, and other SymPy datatypes and allows the use of standard factorial notation (e.g.
x!).
sympy.parsing.sympy_parser.split_symbols(tokens, local_dict, global_dict)
Splits symbol names for implicit multiplication.
Intended to let expressions like xyz be parsed as x*y*z. Does not split Greek charac-
ter names, so theta will not become t*h*e*t*a. Generally this should be used with
implicit_multiplication.

5.38. Parsing input 1497

SymPy Documentation, Release 1.3

sympy.parsing.sympy_parser.split_symbols_custom(predicate)
Creates a transformation that splits symbol names.
predicate should return True if the symbol name is to be split.
For instance, to retain the default behavior but avoid splitting certain symbol names, a
predicate like this would work:

>>> from sympy.parsing.sympy_parser import (parse_expr, _token_splittable,

... standard_transformations, implicit_multiplication,
... split_symbols_custom)
>>> def can_split(symbol):
... if symbol not in ('list', 'of', 'unsplittable', 'names'):
... return _token_splittable(symbol)
... return False
...
>>> transformation = split_symbols_custom(can_split)
>>> parse_expr('unsplittable', transformations=standard_transformations +
... (transformation, implicit_multiplication))
unsplittable

sympy.parsing.sympy_parser.implicit_multiplication(result, local_dict,
global_dict)
Makes the multiplication operator optional in most cases.
Use this before implicit_application() (page 1498), otherwise expressions like sin
2x will be parsed as x * sin(2) rather than sin(2*x).

Examples

>>> from sympy.parsing.sympy_parser import (parse_expr,

... standard_transformations, implicit_multiplication)
>>> transformations = standard_transformations + (implicit_multiplication,)
>>> parse_expr('3 x y', transformations=transformations)
3*x*y

sympy.parsing.sympy_parser.implicit_application(result, local_dict, global_dict)

Makes parentheses optional in some cases for function calls.
Use this after implicit_multiplication() (page 1498), otherwise expressions like sin
2x will be parsed as x * sin(2) rather than sin(2*x).

Examples

>>> from sympy.parsing.sympy_parser import (parse_expr,

... standard_transformations, implicit_application)
>>> transformations = standard_transformations + (implicit_application,)
>>> parse_expr('cot z + csc z', transformations=transformations)
cot(z) + csc(z)

sympy.parsing.sympy_parser.function_exponentiation(tokens, local_dict,
global_dict)
Allows functions to be exponentiated, e.g. cos**2(x).

1498 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.parsing.sympy_parser import (parse_expr,

... standard_transformations, function_exponentiation)
>>> transformations = standard_transformations + (function_exponentiation,)
>>> parse_expr('sin**4(x)', transformations=transformations)
sin(x)**4

sympy.parsing.sympy_parser.implicit_multiplication_application(result, lo-
cal_dict,
global_dict)
Allows a slightly relaxed syntax.
• Parentheses for single-argument method calls are optional.
• Multiplication is implicit.
• Symbol names can be split (i.e. spaces are not needed between symbols).
• Functions can be exponentiated.

Examples

>>> from sympy.parsing.sympy_parser import (parse_expr,

... standard_transformations, implicit_multiplication_application)
>>> parse_expr(”10sin**2 x**2 + 3xyz + tan theta”,
... transformations=(standard_transformations +
... (implicit_multiplication_application,)))
3*x*y*z + 10*sin(x**2)**2 + tan(theta)

sympy.parsing.sympy_parser.rationalize(tokens, local_dict, global_dict)

Converts floats into Rational. Run AFTER auto_number.
sympy.parsing.sympy_parser.convert_xor(tokens, local_dict, global_dict)
Treats XOR, ^, as exponentiation, **.
These are included in :data:sympy.parsing.sympy_parser.standard_transformations and
generally don’t need to be manually added by the user.
sympy.parsing.sympy_parser.lambda_notation(tokens, local_dict, global_dict)
Substitutes “lambda” with its Sympy equivalent Lambda(). However, the conversion
doesn’t take place if only “lambda” is passed because that is a syntax error.
sympy.parsing.sympy_parser.auto_symbol(tokens, local_dict, global_dict)
Inserts calls to Symbol/Function for undefined variables.
sympy.parsing.sympy_parser.repeated_decimals(tokens, local_dict, global_dict)
Allows 0.2[1] notation to represent the repeated decimal 0.2111… (19/90)
Run this before auto_number.
sympy.parsing.sympy_parser.auto_number(tokens, local_dict, global_dict)
Converts numeric literals to use SymPy equivalents.
Complex numbers use I, integer literals use Integer, and float literals use Float.
sympy.parsing.sympy_parser.factorial_notation(tokens, local_dict, global_dict)
Allows standard notation for factorial.

5.38. Parsing input 1499

SymPy Documentation, Release 1.3

5.38.3 Experimental LATEX Parsing

LATEX parsing was ported from latex2sympy. While functional and its API should remain stable,
the parsing behavior or backend may change in future releases.

5.38.4 LATEX Parsing Caveats

The current implementation is experimental. The behavior, parser backend and API might
change in the future. Unlike some of the other parsers, LATEX is designed as a type-setting
language, not a computer algebra system and so can contain typographical conventions that
might be interpreted multiple ways.
In its current definition, the parser will at times will fail to fully parse the expression, but not
throw a warning:

parse_latex(r'x -')

Will simply find x. What is covered by this behavior will almost certainly change between
releases, and become stricter, more relaxed, or some mix.

5.38.5 LATEX Parsing Functions Reference

sympy.parsing.latex.parse_latex(s)
Converts the string s to a SymPy Expr
Parameters s : str
The LaTeX string to parse. In Python source containing LaTeX, *raw
strings*
(denoted with ‘r’‘‘, like this one) are preferred, as LaTeX makes lib-
eral
use of the ‘‘‘‘ character, which would trigger escaping in normal
Python
strings.
>>> from sympy.parsing.latex import parse_latex # doctest: +SKIP
>>> expr = parse_latex(r”frac {1 + sqrt {a}} {b}”) # doctest: +SKIP
>>> expr # doctest: +SKIP
(sqrt(a) + 1)/b
>>> expr.evalf(4, subs=dict(a=5, b=2)) # doctest: +SKIP
1.618

5.38.6 LATEX Parsing Exceptions Reference

class sympy.parsing.latex.LaTeXParsingError

1500 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.38.7 Runtime Installation

The currently-packaged parser backend is partially generated with ANTLR4, but to use the
parser, you only need the antlr4 Python package available.
Depending on your package manager, you can install the right package with, for example,
pip3 (Python 3 only):

$ pip3 install antlr4-python3-runtime

or pip (Python 2 only):

$ pip install antlr4-python2-runtime

or conda (Python 2 or Python 3):

$ conda install --channel=conda-forge antlr-python-runtime

5.39 Calculus

Calculus-related methods.
This module implements a method to find Euler-Lagrange Equations for given Lagrangian.
sympy.calculus.euler.euler_equations(L, funcs=(), vars=())
Find the Euler-Lagrange equations [R22] for a given Lagrangian.
Parameters L : Expr
The Lagrangian that should be a function of the functions listed in
the second argument and their derivatives.
For example, in the case of two functions f (x, y), g(x, y) and two inde-
pendent variables x, y the Lagrangian would have the form:

( )
∂f (x, y) ∂f (x, y) ∂g(x, y) ∂g(x, y)
L f (x, y), g(x, y), , , , , x, y
∂x ∂y ∂x ∂y

In many cases it is not necessary to provide anything, except the La-

grangian, it will be auto-detected (and an error raised if this couldn’t
be done).
funcs : Function or an iterable of Functions
The functions that the Lagrangian depends on. The Euler equations
are differential equations for each of these functions.
vars : Symbol or an iterable of Symbols
The Symbols that are the independent variables of the functions.
Returns eqns : list of Eq
The list of differential equations, one for each function.

5.39. Calculus 1501

SymPy Documentation, Release 1.3

References

[R22]

Examples

>>> from sympy import Symbol, Function

>>> from sympy.calculus.euler import euler_equations
>>> x = Function('x')
>>> t = Symbol('t')
>>> L = (x(t).diff(t))**2/2 - x(t)**2/2
>>> euler_equations(L, x(t), t)
[Eq(-x(t) - Derivative(x(t), (t, 2)), 0)]
>>> u = Function('u')
>>> x = Symbol('x')
>>> L = (u(t, x).diff(t))**2/2 - (u(t, x).diff(x))**2/2
>>> euler_equations(L, u(t, x), [t, x])
[Eq(-Derivative(u(t, x), (t, 2)) + Derivative(u(t, x), (x, 2)), 0)]

5.39.1 Singularities

This module implements algorithms for finding singularities for a function and identifying
types of functions.
The differential calculus methods in this module include methods to identify the following
function types in the given Interval: - Increasing - Strictly Increasing - Decreasing - Strictly
Decreasing - Monotonic
sympy.calculus.singularities.is_decreasing(expression, interval=Reals, sym-
bol=None)
Return whether the function is decreasing in the given interval.

Examples

>>> from sympy import is_decreasing

>>> from sympy.abc import x, y
>>> from sympy import S, Interval, oo
>>> is_decreasing(1/(x**2 - 3*x), Interval.open(1.5, 3))
True
>>> is_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
True
>>> is_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, S(3)/2))
False
>>> is_decreasing(-x**2, Interval(-oo, 0))
False
>>> is_decreasing(-x**2 + y, Interval(-oo, 0), x)
False

sympy.calculus.singularities.is_increasing(expression, interval=Reals, sym-

bol=None)
Return whether the function is increasing in the given interval.

1502 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import is_increasing

>>> from sympy.abc import x, y
>>> from sympy import S, Interval, oo
>>> is_increasing(x**3 - 3*x**2 + 4*x, S.Reals)
True
>>> is_increasing(-x**2, Interval(-oo, 0))
True
>>> is_increasing(-x**2, Interval(0, oo))
False
>>> is_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval(-2, 3))
False
>>> is_increasing(x**2 + y, Interval(1, 2), x)
True

sympy.calculus.singularities.is_monotonic(expression, interval=Reals, sym-

bol=None)
Return whether the function is monotonic in the given interval.

Examples

>>> from sympy import is_monotonic

>>> from sympy.abc import x, y
>>> from sympy import S, Interval, oo
>>> is_monotonic(1/(x**2 - 3*x), Interval.open(1.5, 3))
True
>>> is_monotonic(1/(x**2 - 3*x), Interval.Lopen(3, oo))
True
>>> is_monotonic(x**3 - 3*x**2 + 4*x, S.Reals)
True
>>> is_monotonic(-x**2, S.Reals)
False
>>> is_monotonic(x**2 + y + 1, Interval(1, 2), x)
True

sympy.calculus.singularities.is_strictly_decreasing(expression, inter-
val=Reals, sym-
bol=None)
Return whether the function is strictly decreasing in the given interval.

Examples

>>> from sympy import is_strictly_decreasing

>>> from sympy.abc import x, y
>>> from sympy import S, Interval, oo
>>> is_strictly_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
True
>>> is_strictly_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, S(3)/2))
False
>>> is_strictly_decreasing(-x**2, Interval(-oo, 0))
False
>>> is_strictly_decreasing(-x**2 + y, Interval(-oo, 0), x)
False

5.39. Calculus 1503

SymPy Documentation, Release 1.3

sympy.calculus.singularities.is_strictly_increasing(expression, inter-
val=Reals, sym-
bol=None)
Return whether the function is strictly increasing in the given interval.

Examples

>>> from sympy import is_strictly_increasing

>>> from sympy.abc import x, y
>>> from sympy import Interval, oo
>>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.Ropen(-oo, -2))
True
>>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.Lopen(3, oo))
True
>>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.open(-2, 3))
False
>>> is_strictly_increasing(-x**2, Interval(0, oo))
False
>>> is_strictly_increasing(-x**2 + y, Interval(-oo, 0), x)
False

sympy.calculus.singularities.monotonicity_helper(expression, predicate, inter-

val=Reals, symbol=None)
Helper function for functions checking function monotonicity.
It returns a boolean indicating whether the interval in which the function’s derivative
satisfies given predicate is a superset of the given interval.
sympy.calculus.singularities.singularities(expression, symbol)
Find singularities of a given function.
Currently supported functions are: - univariate rational (real or complex) functions

Notes

This function does not find nonisolated singularities nor does it find branch points of the
expression.

References

[R23]

Examples

>>> from sympy.calculus.singularities import singularities

>>> from sympy import Symbol
>>> x = Symbol('x', real=True)
>>> y = Symbol('y', real=False)
>>> singularities(x**2 + x + 1, x)
EmptySet()
>>> singularities(1/(x + 1), x)
{-1}
(continues on next page)

1504 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> singularities(1/(y**2 + 1), y)
{-I, I}
>>> singularities(1/(y**3 + 1), y)
{-1, 1/2 - sqrt(3)*I/2, 1/2 + sqrt(3)*I/2}

5.39.2 Finite difference weights

This module implements an algorithm for efficient generation of finite difference weights for
ordinary differentials of functions for derivatives from 0 (interpolation) up to arbitrary order.
The core algorithm is provided in the finite difference weight generating function
(finite_diff_weights), and two convenience functions are provided for:
• estimating a derivative (or interpolate) directly from a series of points is also
provided (apply_finite_diff).
• differentiating by using finite difference approximations
(differentiate_finite).
sympy.calculus.finite_diff.apply_finite_diff(order, x_list, y_list, x0=0)
Calculates the finite difference approximation of the derivative of requested order at x0
from points provided in x_list and y_list.
Parameters order: int
order of derivative to approximate. 0 corresponds to interpolation.
x_list: sequence
Sequence of (unique) values for the independent variable.
y_list: sequence
The function value at corresponding values for the independent vari-
able in x_list.
x0: Number or Symbol
At what value of the independent variable the derivative should be
evaluated. Defaults to S(0).
Returns sympy.core.add.Add or sympy.core.numbers.Number
The finite difference expression approximating the requested deriva-
tive order at x0.
See also:
sympy.calculus.finite_diff.finite_diff_weights (page 1508)

Notes

Order = 0 corresponds to interpolation. Only supply so many points you think makes
sense to around x0 when extracting the derivative (the function need to be well behaved
within that region). Also beware of Runge’s phenomenon.

5.39. Calculus 1505

SymPy Documentation, Release 1.3

References

Fortran 90 implementation with Python interface for numerics: finitediff

Examples

>>> from sympy.calculus import apply_finite_diff

>>> cube = lambda arg: (1.0*arg)**3
>>> xlist = range(-3,3+1)
>>> apply_finite_diff(2, xlist, map(cube, xlist), 2) - 12 # doctest: +SKIP
-3.55271367880050e-15

we see that the example above only contain rounding errors. apply_finite_diff can also
be used on more abstract objects:

>>> from sympy import IndexedBase, Idx

>>> from sympy.calculus import apply_finite_diff
>>> x, y = map(IndexedBase, 'xy')
>>> i = Idx('i')
>>> x_list, y_list = zip(*[(x[i+j], y[i+j]) for j in range(-1,2)])
>>> apply_finite_diff(1, x_list, y_list, x[i])
((x[i + 1] - x[i])/(-x[i - 1] + x[i]) - 1)*y[i]/(x[i + 1] - x[i]) - (x[i + 1] -␣
,→x[i])*y[i - 1]/((x[i + 1] - x[i - 1])*(-x[i - 1] + x[i])) + (-x[i - 1] +␣

,→x[i])*y[i + 1]/((x[i + 1] - x[i - 1])*(x[i + 1] - x[i]))

sympy.calculus.finite_diff.as_finite_diff(derivative, points=1, x0=None,

wrt=None)
Returns an approximation of a derivative of a function in the form of a finite difference
formula. The expression is a weighted sum of the function at a number of discrete values
of (one of) the independent variable(s).
Parameters derivative: a Derivative instance
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 co-
efficient, it will be used as the step-size for generating an equidistant
sequence of length order+1 centered around x0. default: 1 (step-size
1)
x0: number or Symbol, optional
the value of the independent variable (wrt) at which the derivative is
to be approximated. Default: same as wrt.
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.
See also:
sympy.calculus.finite_diff.apply_finite_diff (page 1505), sympy.calculus.
finite_diff.finite_diff_weights (page 1508)

1506 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, Function, exp, sqrt, Symbol, as_finite_diff
>>> from sympy.utilities.exceptions import SymPyDeprecationWarning
>>> import warnings
>>> warnings.simplefilter(”ignore”, SymPyDeprecationWarning)
>>> x, h = symbols('x h')
>>> f = Function('f')
>>> as_finite_diff(f(x).diff(x))
-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:

>>> as_finite_diff(f(x).diff(x), h)
-f(-h/2 + x)/h + f(h/2 + x)/h

We can also specify the discretized values to be used in a sequence:

>>> as_finite_diff(f(x).diff(x), [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 = [x-h, x+h, x+e*h]
>>> as_finite_diff(f(x).diff(x, 1), xl, x+h*sq2)
2*h*((h + sqrt(2)*h)/(2*h) - (-sqrt(2)*h + h)/(2*h))*f(E*h + x)/((-h + E*h)*(h +␣
,→E*h)) + (-(-sqrt(2)*h + h)/(2*h) - (-sqrt(2)*h + E*h)/(2*h))*f(-h + x)/(h +␣

,→E*h) + (-(h + sqrt(2)*h)/(2*h) + (-sqrt(2)*h + E*h)/(2*h))*f(h + x)/(-h + E*h)

Partial derivatives are also supported:

>>> y = Symbol('y')
>>> d2fdxdy=f(x,y).diff(x,y)
>>> as_finite_diff(d2fdxdy, wrt=x)
-Derivative(f(x - 1/2, y), y) + Derivative(f(x + 1/2, y), y)

sympy.calculus.finite_diff.differentiate_finite(expr, *symbols, **kwargs)

Differentiate expr and replace Derivatives with finite differences.
Parameters expr : expression
*symbols : differentiate with respect to symbols
points: sequence or coefficient, optional
see Derivative.as_finite_difference
x0: number or Symbol, optional
see Derivative.as_finite_difference
wrt: Symbol, optional
see Derivative.as_finite_difference
evaluate : bool

5.39. Calculus 1507

SymPy Documentation, Release 1.3

kwarg passed on to diff, whether or not to evaluate the Derivative

intermediately (default: False).

Examples

>>> from sympy import cos, sin, Function, differentiate_finite

>>> from sympy.abc import x, y, h
>>> f, g = Function('f'), Function('g')
>>> differentiate_finite(f(x)*g(x), x, points=[x-h, x+h])
-f(-h + x)*g(-h + x)/(2*h) + f(h + x)*g(h + x)/(2*h)

Note that the above form preserves the product rule in discrete form. If we want we can
pass evaluate=True to get another form (which is usually not what we want):

>>> differentiate_finite(f(x)*g(x), x, points=[x-h, x+h], evaluate=True).

,→simplify()

-((f(-h + x) - f(h + x))*g(x) + (g(-h + x) - g(h + x))*f(x))/(2*h)

differentiate_finite works on any expression:

>>> differentiate_finite(f(x) + sin(x), x, 2)

-2*f(x) + f(x - 1) + f(x + 1) - 2*sin(x) + sin(x - 1) + sin(x + 1)
>>> differentiate_finite(f(x) + sin(x), x, 2, evaluate=True)
-2*f(x) + f(x - 1) + f(x + 1) - sin(x)
>>> differentiate_finite(f(x, y), x, y)
f(x - 1/2, y - 1/2) - f(x - 1/2, y + 1/2) - f(x + 1/2, y - 1/2) + f(x + 1/2, y +␣
,→1/2)

sympy.calculus.finite_diff.finite_diff_weights(order, x_list, x0=1)

Calculates the finite difference weights for an arbitrarily spaced one-dimensional grid
(x_list) for derivatives at x0 of order 0, 1, …, up to order using a recursive formula.
Order of accuracy is at least len(x_list) - order, if x_list is defined correctly.
Parameters order: int
Up to what derivative order weights should be calculated. 0 corre-
sponds to interpolation.
x_list: sequence
Sequence of (unique) values for the independent variable. It is useful
(but not necessary) to order x_list from nearest to furthest from x0;
see examples below.
x0: Number or Symbol
Root or value of the independent variable for which the finite differ-
ence weights should be generated. Default is S.One.
Returns list
A list of sublists, each corresponding to coefficients for increasing
derivative order, and each containing lists of coefficients for increas-
ing subsets of x_list.
See also:
sympy.calculus.finite_diff.apply_finite_diff (page 1505)

1508 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Notes

If weights for a finite difference approximation of 3rd order derivative is wanted, weights
for 0th, 1st and 2nd order are calculated “for free”, so are formulae using subsets of
x_list. This is something one can take advantage of to save computational cost. Be
aware that one should define x_list from nearest to farest from x0. If not, subsets of
x_list will yield poorer approximations, which might not grand an order of accuracy of
len(x_list) - order.

References

[R24]

Examples

>>> from sympy import S

>>> from sympy.calculus import finite_diff_weights
>>> res = finite_diff_weights(1, [-S(1)/2, S(1)/2, S(3)/2, S(5)/2], 0)
>>> res
[[[1, 0, 0, 0],
[1/2, 1/2, 0, 0],
[3/8, 3/4, -1/8, 0],
[5/16, 15/16, -5/16, 1/16]],
[[0, 0, 0, 0],
[-1, 1, 0, 0],
[-1, 1, 0, 0],
[-23/24, 7/8, 1/8, -1/24]]]
>>> res[0][-1] # FD weights for 0th derivative, using full x_list
[5/16, 15/16, -5/16, 1/16]
>>> res[1][-1] # FD weights for 1st derivative
[-23/24, 7/8, 1/8, -1/24]
>>> res[1][-2] # FD weights for 1st derivative, using x_list[:-1]
[-1, 1, 0, 0]
>>> res[1][-1][0] # FD weight for 1st deriv. for x_list[0]
-23/24
>>> res[1][-1][1] # FD weight for 1st deriv. for x_list[1], etc.
7/8

Each sublist contains the most accurate formula at the end. Note, that in the above
example res[1][1] is the same as res[1][2]. Since res[1][2] has an order of accuracy
of len(x_list[:3]) - order = 3 - 1 = 2, the same is true for res[1][1]!
>>> from sympy import S
>>> from sympy.calculus import finite_diff_weights
>>> res = finite_diff_weights(1, [S(0), S(1), -S(1), S(2), -S(2)], 0)[1]
>>> res
[[0, 0, 0, 0, 0],
[-1, 1, 0, 0, 0],
[0, 1/2, -1/2, 0, 0],
[-1/2, 1, -1/3, -1/6, 0],
[0, 2/3, -2/3, -1/12, 1/12]]
>>> res[0] # no approximation possible, using x_list[0] only
[0, 0, 0, 0, 0]
>>> res[1] # classic forward step approximation
(continues on next page)

5.39. Calculus 1509

SymPy Documentation, Release 1.3

(continued from previous page)

[-1, 1, 0, 0, 0]
>>> res[2] # classic centered approximation
[0, 1/2, -1/2, 0, 0]
>>> res[3:] # higher order approximations
[[-1/2, 1, -1/3, -1/6, 0], [0, 2/3, -2/3, -1/12, 1/12]]

Let us compare this to a differently defined x_list. Pay attention to foo[i][k] corre-
sponding to the gridpoint defined by x_list[k].

>>> from sympy import S

>>> from sympy.calculus import finite_diff_weights
>>> foo = finite_diff_weights(1, [-S(2), -S(1), S(0), S(1), S(2)], 0)[1]
>>> foo
[[0, 0, 0, 0, 0],
[-1, 1, 0, 0, 0],
[1/2, -2, 3/2, 0, 0],
[1/6, -1, 1/2, 1/3, 0],
[1/12, -2/3, 0, 2/3, -1/12]]
>>> foo[1] # not the same and of lower accuracy as res[1]!
[-1, 1, 0, 0, 0]
>>> foo[2] # classic double backward step approximation
[1/2, -2, 3/2, 0, 0]
>>> foo[4] # the same as res[4]
[1/12, -2/3, 0, 2/3, -1/12]

Note that, unless you plan on using approximations based on subsets of x_list, the
order of gridpoints does not matter.
The capability to generate weights at arbitrary points can be used e.g. to minimize
Runge’s phenomenon by using Chebyshev nodes:

>>> from sympy import cos, symbols, pi, simplify

>>> from sympy.calculus import finite_diff_weights
>>> N, (h, x) = 4, symbols('h x')
>>> x_list = [x+h*cos(i*pi/(N)) for i in range(N,-1,-1)] # chebyshev nodes
>>> print(x_list)
[-h + x, -sqrt(2)*h/2 + x, x, sqrt(2)*h/2 + x, h + x]
>>> mycoeffs = finite_diff_weights(1, x_list, 0)[1][4]
>>> [simplify(c) for c in mycoeffs] #doctest: +NORMALIZE_WHITESPACE
[(h**3/2 + h**2*x - 3*h*x**2 - 4*x**3)/h**4,
(-sqrt(2)*h**3 - 4*h**2*x + 3*sqrt(2)*h*x**2 + 8*x**3)/h**4,
6*x/h**2 - 8*x**3/h**4,
(sqrt(2)*h**3 - 4*h**2*x - 3*sqrt(2)*h*x**2 + 8*x**3)/h**4,
(-h**3/2 + h**2*x + 3*h*x**2 - 4*x**3)/h**4]

5.40 Physics Module

A module that helps solving problems in physics

5.40.1 Contents

1510 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Hydrogen Wavefunctions

sympy.physics.hydrogen.E_nl(n, Z=1)
Returns the energy of the state (n, l) in Hartree atomic units.
The energy doesn’t depend on “l”.

Examples

>>> from sympy import var

>>> from sympy.physics.hydrogen import E_nl
>>> var(”n Z”)
(n, Z)
>>> E_nl(n, Z)
-Z**2/(2*n**2)
>>> E_nl(1)
-1/2
>>> E_nl(2)
-1/8
>>> E_nl(3)
-1/18
>>> E_nl(3, 47)
-2209/18

sympy.physics.hydrogen.E_nl_dirac(n, l, spin_up=True, Z=1,

c=137.035999037000)
Returns the relativistic energy of the state (n, l, spin) in Hartree atomic units.
The energy is calculated from the Dirac equation. The rest mass energy is not included.
n, l quantum numbers ‘n’ and ‘l’
spin_up True if the electron spin is up (default), otherwise down
Z atomic number (1 for Hydrogen, 2 for Helium, …)
c speed of light in atomic units. Default value is 137.035999037, taken from: http:
//arxiv.org/abs/1012.3627

Examples

>>> from sympy.physics.hydrogen import E_nl_dirac

>>> E_nl_dirac(1, 0)
-0.500006656595360

>>> E_nl_dirac(2, 0)
-0.125002080189006
>>> E_nl_dirac(2, 1)
-0.125000416028342
>>> E_nl_dirac(2, 1, False)
-0.125002080189006

>>> E_nl_dirac(3, 0)
-0.0555562951740285
>>> E_nl_dirac(3, 1)
(continues on next page)

5.40. Physics Module 1511

SymPy Documentation, Release 1.3

(continued from previous page)

-0.0555558020932949
>>> E_nl_dirac(3, 1, False)
-0.0555562951740285
>>> E_nl_dirac(3, 2)
-0.0555556377366884
>>> E_nl_dirac(3, 2, False)
-0.0555558020932949

sympy.physics.hydrogen.Psi_nlm(n, l, m, r, phi, theta, Z=1)

Returns the Hydrogen wave function psi_{nlm}. It’s the product of the radial wavefunc-
tion R_{nl} and the spherical harmonic Y_{l}^{m}.
n, l, m quantum numbers ‘n’, ‘l’ and ‘m’
r radial coordinate
phi azimuthal angle
theta polar angle
Z atomic number (1 for Hydrogen, 2 for Helium, …)
Everything is in Hartree atomic units.

Examples

>>> from sympy.physics.hydrogen import Psi_nlm

>>> from sympy import Symbol
>>> r=Symbol(”r”, real=True, positive=True)
>>> phi=Symbol(”phi”, real=True)
>>> theta=Symbol(”theta”, real=True)
>>> Z=Symbol(”Z”, positive=True, integer=True, nonzero=True)
>>> Psi_nlm(1,0,0,r,phi,theta,Z)
Z**(3/2)*exp(-Z*r)/sqrt(pi)
>>> Psi_nlm(2,1,1,r,phi,theta,Z)
-Z**(5/2)*r*exp(I*phi)*exp(-Z*r/2)*sin(theta)/(8*sqrt(pi))

Integrating the absolute square of a hydrogen wavefunction psi_{nlm} over the whole
space leads 1.
The normalization of the hydrogen wavefunctions Psi_nlm is:

>>> from sympy import integrate, conjugate, pi, oo, sin

>>> wf=Psi_nlm(2,1,1,r,phi,theta,Z)
>>> abs_sqrd=wf*conjugate(wf)
>>> jacobi=r**2*sin(theta)
>>> integrate(abs_sqrd*jacobi, (r,0,oo), (phi,0,2*pi), (theta,0,pi))
1

sympy.physics.hydrogen.R_nl(n, l, r, Z=1)
Returns the Hydrogen radial wavefunction R_{nl}.
n, l quantum numbers ‘n’ and ‘l’
r radial coordinate
Z atomic number (1 for Hydrogen, 2 for Helium, …)
Everything is in Hartree atomic units.

1512 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.hydrogen import R_nl

>>> from sympy import var
>>> var(”r Z”)
(r, Z)
>>> R_nl(1, 0, r, Z)
2*sqrt(Z**3)*exp(-Z*r)
>>> R_nl(2, 0, r, Z)
sqrt(2)*(-Z*r + 2)*sqrt(Z**3)*exp(-Z*r/2)/4
>>> R_nl(2, 1, r, Z)
sqrt(6)*Z*r*sqrt(Z**3)*exp(-Z*r/2)/12

For Hydrogen atom, you can just use the default value of Z=1:
>>> R_nl(1, 0, r)
2*exp(-r)
>>> R_nl(2, 0, r)
sqrt(2)*(-r + 2)*exp(-r/2)/4
>>> R_nl(3, 0, r)
2*sqrt(3)*(2*r**2/9 - 2*r + 3)*exp(-r/3)/27

For Silver atom, you would use Z=47:

>>> R_nl(1, 0, r, Z=47)
94*sqrt(47)*exp(-47*r)
>>> R_nl(2, 0, r, Z=47)
47*sqrt(94)*(-47*r + 2)*exp(-47*r/2)/4
>>> R_nl(3, 0, r, Z=47)
94*sqrt(141)*(4418*r**2/9 - 94*r + 3)*exp(-47*r/3)/27

The normalization of the radial wavefunction is:

>>> from sympy import integrate, oo
>>> integrate(R_nl(1, 0, r)**2 * r**2, (r, 0, oo))
1
>>> integrate(R_nl(2, 0, r)**2 * r**2, (r, 0, oo))
1
>>> integrate(R_nl(2, 1, r)**2 * r**2, (r, 0, oo))
1

It holds for any atomic number:

>>> integrate(R_nl(1, 0, r, Z=2)**2 * r**2, (r, 0, oo))
1
>>> integrate(R_nl(2, 0, r, Z=3)**2 * r**2, (r, 0, oo))
1
>>> integrate(R_nl(2, 1, r, Z=4)**2 * r**2, (r, 0, oo))
1

Matrices

Known matrices related to physics

sympy.physics.matrices.mdft(n)
Returns an expression of a discrete Fourier transform as a matrix multiplication. It is an
n X n matrix.

5.40. Physics Module 1513

SymPy Documentation, Release 1.3

References

[R462]

Examples

>>> from sympy.physics.matrices import mdft

>>> mdft(3)
Matrix([
[sqrt(3)/3, sqrt(3)/3, sqrt(3)/3],
[sqrt(3)/3, sqrt(3)*exp(-2*I*pi/3)/3, sqrt(3)*exp(-4*I*pi/3)/3],
[sqrt(3)/3, sqrt(3)*exp(-4*I*pi/3)/3, sqrt(3)*exp(-8*I*pi/3)/3]])

sympy.physics.matrices.mgamma(mu, lower=False)
Returns a Dirac gamma matrix γ µ in the standard (Dirac) representation.
If you want γµ , use gamma(mu, True).
We use a convention:
γ5 = i · γ0 · γ1 · γ2 · γ3
γ5 = i · γ0 · γ1 · γ2 · γ3 = −γ 5

References

[R463]

Examples

>>> from sympy.physics.matrices import mgamma

>>> mgamma(1)
Matrix([
[ 0, 0, 0, 1],
[ 0, 0, 1, 0],
[ 0, -1, 0, 0],
[-1, 0, 0, 0]])

sympy.physics.matrices.msigma(i)
Returns a Pauli matrix σi with i = 1, 2, 3

References

[R464]

Examples

1514 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.matrices import msigma

>>> msigma(1)
Matrix([
[0, 1],
[1, 0]])

sympy.physics.matrices.pat_matrix(m, dx, dy, dz)

Returns the Parallel Axis Theorem matrix to translate the inertia matrix a distance of
(dx, dy, dz) for a body of mass m.

Examples

To translate a body having a mass of 2 units a distance of 1 unit along the x-axis we get:

>>> from sympy.physics.matrices import pat_matrix

>>> pat_matrix(2, 1, 0, 0)
Matrix([
[0, 0, 0],
[0, 2, 0],
[0, 0, 2]])

Pauli Algebra

This module implements Pauli algebra by subclassing Symbol. Only algebraic properties of
Pauli matrices are used (we don’t use the Matrix class).
See the documentation to the class Pauli for examples.

References

sympy.physics.paulialgebra.evaluate_pauli_product(arg)
Help function to evaluate Pauli matrices product with symbolic objects
Parameters arg: symbolic expression that contains Paulimatrices

Examples

>>> from sympy.physics.paulialgebra import Pauli, evaluate_pauli_product

>>> from sympy import I
>>> evaluate_pauli_product(I*Pauli(1)*Pauli(2))
-sigma3

>>> from sympy.abc import x,y

>>> evaluate_pauli_product(x**2*Pauli(2)*Pauli(1))
-I*x**2*sigma3

5.40. Physics Module 1515

SymPy Documentation, Release 1.3

Quantum Harmonic Oscillator in 1-D

sympy.physics.qho_1d.E_n(n, omega)
Returns the Energy of the One-dimensional harmonic oscillator
n the “nodal” quantum number
omega the harmonic oscillator angular frequency
The unit of the returned value matches the unit of hw, since the energy is calculated as:
E_n = hbar * omega*(n + 1/2)

Examples

>>> from sympy.physics.qho_1d import E_n

>>> from sympy import var
>>> var(”x omega”)
(x, omega)
>>> E_n(x, omega)
hbar*omega*(x + 1/2)

sympy.physics.qho_1d.coherent_state(n, alpha)
Returns <n|alpha> for the coherent states of 1D harmonic oscillator. See http://en.
wikipedia.org/wiki/Coherent_states
n the “nodal” quantum number
alpha the eigen value of annihilation operator
sympy.physics.qho_1d.psi_n(n, x, m, omega)
Returns the wavefunction psi_{n} for the One-dimensional harmonic oscillator.
n the “nodal” quantum number. Corresponds to the number of nodes in the wavefunc-
tion. n >= 0
x x coordinate
m mass of the particle
omega angular frequency of the oscillator

Examples

>>> from sympy.physics.qho_1d import psi_n

>>> from sympy import var
>>> var(”x m omega”)
(x, m, omega)
>>> psi_n(0, x, m, omega)
(m*omega)**(1/4)*exp(-m*omega*x**2/(2*hbar))/(hbar**(1/4)*pi**(1/4))

Quantum Harmonic Oscillator in 3-D

sympy.physics.sho.E_nl(n, l, hw)
Returns the Energy of an isotropic harmonic oscillator
n the “nodal” quantum number

1516 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

l the orbital angular momentum

hw the harmonic oscillator parameter.
The unit of the returned value matches the unit of hw, since the energy is calculated as:
E_nl = (2*n + l + 3/2)*hw

Examples

>>> from sympy.physics.sho import E_nl

>>> from sympy import symbols
>>> x, y, z = symbols('x, y, z')
>>> E_nl(x, y, z)
z*(2*x + y + 3/2)

sympy.physics.sho.R_nl(n, l, nu, r)
Returns the radial wavefunction R_{nl} for a 3d isotropic harmonic oscillator.
n the “nodal” quantum number. Corresponds to the number of nodes in the wavefunc-
tion. n >= 0
l the quantum number for orbital angular momentum
nu mass-scaled frequency: nu = m*omega/(2*hbar) where m is the mass and omega the
frequency of the oscillator. (in atomic units nu == omega/2)
r Radial coordinate

Examples

>>> from sympy.physics.sho import R_nl

>>> from sympy import var
>>> var(”r nu l”)
(r, nu, l)
>>> R_nl(0, 0, 1, r)
2*2**(3/4)*exp(-r**2)/pi**(1/4)
>>> R_nl(1, 0, 1, r)
4*2**(1/4)*sqrt(3)*(-2*r**2 + 3/2)*exp(-r**2)/(3*pi**(1/4))

l, nu and r may be symbolic:

>>> R_nl(0, 0, nu, r)

2*2**(3/4)*sqrt(nu**(3/2))*exp(-nu*r**2)/pi**(1/4)
>>> R_nl(0, l, 1, r)
r**l*sqrt(2**(l + 3/2)*2**(l + 2)/factorial2(2*l + 1))*exp(-r**2)/pi**(1/4)

The normalization of the radial wavefunction is:

>>> from sympy import Integral, oo

>>> Integral(R_nl(0, 0, 1, r)**2 * r**2, (r, 0, oo)).n()
1.00000000000000
>>> Integral(R_nl(1, 0, 1, r)**2 * r**2, (r, 0, oo)).n()
1.00000000000000
>>> Integral(R_nl(1, 1, 1, r)**2 * r**2, (r, 0, oo)).n()
1.00000000000000

5.40. Physics Module 1517

SymPy Documentation, Release 1.3

Second Quantization

Second quantization operators and states for bosons.

This follow the formulation of Fetter and Welecka, “Quantum Theory of Many-Particle Sys-
tems.”
class sympy.physics.secondquant.Dagger
Hermitian conjugate of creation/annihilation operators.

Examples

>>> from sympy import I

>>> from sympy.physics.secondquant import Dagger, B, Bd
>>> Dagger(2*I)
-2*I
>>> Dagger(B(0))
CreateBoson(0)
>>> Dagger(Bd(0))
AnnihilateBoson(0)

classmethod eval(arg)
Evaluates the Dagger instance.

Examples

>>> from sympy import I

>>> from sympy.physics.secondquant import Dagger, B, Bd
>>> Dagger(2*I)
-2*I
>>> Dagger(B(0))
CreateBoson(0)
>>> Dagger(Bd(0))
AnnihilateBoson(0)

The eval() method is called automatically.

class sympy.physics.secondquant.KroneckerDelta
The discrete, or Kronecker, delta function.
A function that takes in two integers i and j. It returns 0 if i and j are not equal or it
returns 1 if i and j are equal.
Parameters i : Number, Symbol
The first index of the delta function.
j : Number, Symbol
The second index of the delta function.
See also:
eval (page 1519), sympy.functions.special.delta_functions.DiracDelta
(page 498)

1518 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R487]

Examples

A simple example with integer indices:

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> KroneckerDelta(1, 2)
0
>>> KroneckerDelta(3, 3)
1

Symbolic indices:

>>> from sympy.abc import i, j, k

>>> KroneckerDelta(i, j)
KroneckerDelta(i, j)
>>> KroneckerDelta(i, i)
1
>>> KroneckerDelta(i, i + 1)
0
>>> KroneckerDelta(i, i + 1 + k)
KroneckerDelta(i, i + k + 1)

classmethod eval(i, j)
Evaluates the discrete delta function.

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy.abc import i, j, k

>>> KroneckerDelta(i, j)
KroneckerDelta(i, j)
>>> KroneckerDelta(i, i)
1
>>> KroneckerDelta(i, i + 1)
0
>>> KroneckerDelta(i, i + 1 + k)
KroneckerDelta(i, i + k + 1)

# indirect doctest
indices_contain_equal_information
Returns True if indices are either both above or below fermi.

Examples

5.40. Physics Module 1519

SymPy Documentation, Release 1.3

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, q).indices_contain_equal_information
True
>>> KroneckerDelta(p, q+1).indices_contain_equal_information
True
>>> KroneckerDelta(i, p).indices_contain_equal_information
False

is_above_fermi
True if Delta can be non-zero above fermi
See also:
is_below_fermi (page 1520), is_only_below_fermi (page 1521),
is_only_above_fermi (page 1521)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_above_fermi
True
>>> KroneckerDelta(p, i).is_above_fermi
False
>>> KroneckerDelta(p, q).is_above_fermi
True

is_below_fermi
True if Delta can be non-zero below fermi
See also:
is_above_fermi (page 1520), is_only_above_fermi (page 1521),
is_only_below_fermi (page 1521)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_below_fermi
False
>>> KroneckerDelta(p, i).is_below_fermi
(continues on next page)

1520 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

True
>>> KroneckerDelta(p, q).is_below_fermi
True

is_only_above_fermi
True if Delta is restricted to above fermi
See also:
is_above_fermi (page 1520), is_below_fermi (page 1520), is_only_below_fermi
(page 1521)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, a).is_only_above_fermi
True
>>> KroneckerDelta(p, q).is_only_above_fermi
False
>>> KroneckerDelta(p, i).is_only_above_fermi
False

is_only_below_fermi
True if Delta is restricted to below fermi
See also:
is_above_fermi (page 1520), is_below_fermi (page 1520), is_only_above_fermi
(page 1521)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')
>>> q = Symbol('q')
>>> KroneckerDelta(p, i).is_only_below_fermi
True
>>> KroneckerDelta(p, q).is_only_below_fermi
False
>>> KroneckerDelta(p, a).is_only_below_fermi
False

killable_index
Returns the index which is preferred to substitute in the final expression.
The index to substitute is the index with less information regarding fermi level. If
indices contain same information, ‘a’ is preferred before ‘b’.

5.40. Physics Module 1521

SymPy Documentation, Release 1.3

See also:
preferred_index (page 1522)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> j = Symbol('j', below_fermi=True)
>>> p = Symbol('p')
>>> KroneckerDelta(p, i).killable_index
p
>>> KroneckerDelta(p, a).killable_index
p
>>> KroneckerDelta(i, j).killable_index
j

preferred_index
Returns the index which is preferred to keep in the final expression.
The preferred index is the index with more information regarding fermi level. If
indices contain same information, ‘a’ is preferred before ‘b’.
See also:
killable_index (page 1521)

Examples

>>> from sympy.functions.special.tensor_functions import KroneckerDelta

>>> from sympy import Symbol
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> j = Symbol('j', below_fermi=True)
>>> p = Symbol('p')
>>> KroneckerDelta(p, i).preferred_index
i
>>> KroneckerDelta(p, a).preferred_index
a
>>> KroneckerDelta(i, j).preferred_index
i

class sympy.physics.secondquant.AnnihilateBoson
Bosonic annihilation operator.

Examples

>>> from sympy.physics.secondquant import B

>>> from sympy.abc import x
>>> B(x)
AnnihilateBoson(x)

1522 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

apply_operator(state)
Apply state to self if self is not symbolic and state is a FockStateKet, else multiply
self by state.

Examples

>>> from sympy.physics.secondquant import B, BKet

>>> from sympy.abc import x, y, n
>>> B(x).apply_operator(y)
y*AnnihilateBoson(x)
>>> B(0).apply_operator(BKet((n,)))
sqrt(n)*FockStateBosonKet((n - 1,))

class sympy.physics.secondquant.CreateBoson
Bosonic creation operator.
apply_operator(state)
Apply state to self if self is not symbolic and state is a FockStateKet, else multiply
self by state.

Examples

>>> from sympy.physics.secondquant import B, Dagger, BKet

>>> from sympy.abc import x, y, n
>>> Dagger(B(x)).apply_operator(y)
y*CreateBoson(x)
>>> B(0).apply_operator(BKet((n,)))
sqrt(n)*FockStateBosonKet((n - 1,))

class sympy.physics.secondquant.AnnihilateFermion
Fermionic annihilation operator.
apply_operator(state)
Apply state to self if self is not symbolic and state is a FockStateKet, else multiply
self by state.

Examples

>>> from sympy.physics.secondquant import B, Dagger, BKet

>>> from sympy.abc import x, y, n
>>> Dagger(B(x)).apply_operator(y)
y*CreateBoson(x)
>>> B(0).apply_operator(BKet((n,)))
sqrt(n)*FockStateBosonKet((n - 1,))

is_only_q_annihilator
Always destroy a quasi-particle? (annihilate hole or annihilate particle)
>>> from sympy import Symbol
>>> from sympy.physics.secondquant import F
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

5.40. Physics Module 1523

SymPy Documentation, Release 1.3

>>> F(a).is_only_q_annihilator
True
>>> F(i).is_only_q_annihilator
False
>>> F(p).is_only_q_annihilator
False

is_only_q_creator
Always create a quasi-particle? (create hole or create particle)

>>> from sympy import Symbol

>>> from sympy.physics.secondquant import F
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

>>> F(a).is_only_q_creator
False
>>> F(i).is_only_q_creator
True
>>> F(p).is_only_q_creator
False

is_q_annihilator
Can we destroy a quasi-particle? (annihilate hole or annihilate particle) If so, would
that be above or below the fermi surface?

>>> from sympy import Symbol

>>> from sympy.physics.secondquant import F
>>> a = Symbol('a', above_fermi=1)
>>> i = Symbol('i', below_fermi=1)
>>> p = Symbol('p')

>>> F(a).is_q_annihilator
1
>>> F(i).is_q_annihilator
0
>>> F(p).is_q_annihilator
1

is_q_creator
Can we create a quasi-particle? (create hole or create particle) If so, would that be
above or below the fermi surface?

>>> from sympy import Symbol

>>> from sympy.physics.secondquant import F
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

>>> F(a).is_q_creator
0
>>> F(i).is_q_creator
-1
>>> F(p).is_q_creator
-1

1524 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.secondquant.CreateFermion
Fermionic creation operator.
apply_operator(state)
Apply state to self if self is not symbolic and state is a FockStateKet, else multiply
self by state.

Examples

>>> from sympy.physics.secondquant import B, Dagger, BKet

>>> from sympy.abc import x, y, n
>>> Dagger(B(x)).apply_operator(y)
y*CreateBoson(x)
>>> B(0).apply_operator(BKet((n,)))
sqrt(n)*FockStateBosonKet((n - 1,))

is_only_q_annihilator
Always destroy a quasi-particle? (annihilate hole or annihilate particle)
>>> from sympy import Symbol
>>> from sympy.physics.secondquant import Fd
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

>>> Fd(a).is_only_q_annihilator
False
>>> Fd(i).is_only_q_annihilator
True
>>> Fd(p).is_only_q_annihilator
False

is_only_q_creator
Always create a quasi-particle? (create hole or create particle)
>>> from sympy import Symbol
>>> from sympy.physics.secondquant import Fd
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

>>> Fd(a).is_only_q_creator
True
>>> Fd(i).is_only_q_creator
False
>>> Fd(p).is_only_q_creator
False

is_q_annihilator
Can we destroy a quasi-particle? (annihilate hole or annihilate particle) If so, would
that be above or below the fermi surface?
>>> from sympy import Symbol
>>> from sympy.physics.secondquant import Fd
>>> a = Symbol('a', above_fermi=1)
(continues on next page)

5.40. Physics Module 1525

SymPy Documentation, Release 1.3

(continued from previous page)

>>> i = Symbol('i', below_fermi=1)
>>> p = Symbol('p')

>>> Fd(a).is_q_annihilator
0
>>> Fd(i).is_q_annihilator
-1
>>> Fd(p).is_q_annihilator
-1

is_q_creator
Can we create a quasi-particle? (create hole or create particle) If so, would that be
above or below the fermi surface?

>>> from sympy import Symbol

>>> from sympy.physics.secondquant import Fd
>>> a = Symbol('a', above_fermi=True)
>>> i = Symbol('i', below_fermi=True)
>>> p = Symbol('p')

>>> Fd(a).is_q_creator
1
>>> Fd(i).is_q_creator
0
>>> Fd(p).is_q_creator
1

class sympy.physics.secondquant.FockState
Many particle Fock state with a sequence of occupation numbers.
Anywhere you can have a FockState, you can also have S.Zero. All code must check for
this!
Base class to represent FockStates.
class sympy.physics.secondquant.FockStateBra
Representation of a bra.
class sympy.physics.secondquant.FockStateKet
Representation of a ket.
class sympy.physics.secondquant.FockStateBosonKet
Many particle Fock state with a sequence of occupation numbers.
Occupation numbers can be any integer >= 0.

Examples

>>> from sympy.physics.secondquant import BKet

>>> BKet([1, 2])
FockStateBosonKet((1, 2))

class sympy.physics.secondquant.FockStateBosonBra
Describes a collection of BosonBra particles.

1526 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.secondquant import BBra

>>> BBra([1, 2])
FockStateBosonBra((1, 2))

sympy.physics.secondquant.BBra
alias of sympy.physics.secondquant.FockStateBosonBra (page 1526)
sympy.physics.secondquant.BKet
alias of sympy.physics.secondquant.FockStateBosonKet (page 1526)
sympy.physics.secondquant.FBra
alias of sympy.physics.secondquant.FockStateFermionBra
sympy.physics.secondquant.FKet
alias of sympy.physics.secondquant.FockStateFermionKet
sympy.physics.secondquant.F
alias of sympy.physics.secondquant.AnnihilateFermion (page 1523)
sympy.physics.secondquant.Fd
alias of sympy.physics.secondquant.CreateFermion (page 1524)
sympy.physics.secondquant.B
alias of sympy.physics.secondquant.AnnihilateBoson (page 1522)
sympy.physics.secondquant.Bd
alias of sympy.physics.secondquant.CreateBoson (page 1523)
sympy.physics.secondquant.apply_operators(e)
Take a sympy expression with operators and states and apply the operators.

Examples

>>> from sympy.physics.secondquant import apply_operators

>>> from sympy import sympify
>>> apply_operators(sympify(3)+4)
7

class sympy.physics.secondquant.InnerProduct
An unevaluated inner product between a bra and ket.
Currently this class just reduces things to a product of Kronecker Deltas. In the future,
we could introduce abstract states like |a> and |b>, and leave the inner product uneval-
uated as <a|b>.
bra
Returns the bra part of the state
ket
Returns the ket part of the state
class sympy.physics.secondquant.BosonicBasis
Base class for a basis set of bosonic Fock states.
class sympy.physics.secondquant.VarBosonicBasis(n_max)
A single state, variable particle number basis set.

5.40. Physics Module 1527

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.secondquant import VarBosonicBasis

>>> b = VarBosonicBasis(5)
>>> b
[FockState((0,)), FockState((1,)), FockState((2,)),
FockState((3,)), FockState((4,))]

index(state)
Returns the index of state in basis.

Examples

>>> from sympy.physics.secondquant import VarBosonicBasis

>>> b = VarBosonicBasis(3)
>>> state = b.state(1)
>>> b
[FockState((0,)), FockState((1,)), FockState((2,))]
>>> state
FockStateBosonKet((1,))
>>> b.index(state)
1

state(i)
The state of a single basis.

Examples

>>> from sympy.physics.secondquant import VarBosonicBasis

>>> b = VarBosonicBasis(5)
>>> b.state(3)
FockStateBosonKet((3,))

class sympy.physics.secondquant.FixedBosonicBasis(n_particles, n_levels)

Fixed particle number basis set.

Examples

>>> from sympy.physics.secondquant import FixedBosonicBasis

>>> b = FixedBosonicBasis(2, 2)
>>> state = b.state(1)
>>> b
[FockState((2, 0)), FockState((1, 1)), FockState((0, 2))]
>>> state
FockStateBosonKet((1, 1))
>>> b.index(state)
1

index(state)
Returns the index of state in basis.

1528 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.secondquant import FixedBosonicBasis

>>> b = FixedBosonicBasis(2, 3)
>>> b.index(b.state(3))
3

state(i)
Returns the state that lies at index i of the basis

Examples

>>> from sympy.physics.secondquant import FixedBosonicBasis

>>> b = FixedBosonicBasis(2, 3)
>>> b.state(3)
FockStateBosonKet((1, 0, 1))

class sympy.physics.secondquant.Commutator
The Commutator: [A, B] = A*B - B*A
The arguments are ordered according to .__cmp__()

>>> from sympy import symbols

>>> from sympy.physics.secondquant import Commutator
>>> A, B = symbols('A,B', commutative=False)
>>> Commutator(B, A)
-Commutator(A, B)

Evaluate the commutator with .doit()

>>> comm = Commutator(A,B); comm

Commutator(A, B)
>>> comm.doit()
A*B - B*A

For two second quantization operators the commutator is evaluated immediately:

>>> from sympy.physics.secondquant import Fd, F

>>> a = symbols('a', above_fermi=True)
>>> i = symbols('i', below_fermi=True)
>>> p,q = symbols('p,q')

>>> Commutator(Fd(a),Fd(i))
2*NO(CreateFermion(a)*CreateFermion(i))

But for more complicated expressions, the evaluation is triggered by a call to .doit()

>>> comm = Commutator(Fd(p)*Fd(q),F(i)); comm

Commutator(CreateFermion(p)*CreateFermion(q), AnnihilateFermion(i))
>>> comm.doit(wicks=True)
-KroneckerDelta(i, p)*CreateFermion(q) +
KroneckerDelta(i, q)*CreateFermion(p)

doit(**hints)
Enables the computation of complex expressions.

5.40. Physics Module 1529

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.secondquant import Commutator, F, Fd

>>> from sympy import symbols
>>> i, j = symbols('i,j', below_fermi=True)
>>> a, b = symbols('a,b', above_fermi=True)
>>> c = Commutator(Fd(a)*F(i),Fd(b)*F(j))
>>> c.doit(wicks=True)
0

classmethod eval(a, b)
The Commutator [A,B] is on canonical form if A < B.

Examples

>>> from sympy.physics.secondquant import Commutator, F, Fd

>>> from sympy.abc import x
>>> c1 = Commutator(F(x), Fd(x))
>>> c2 = Commutator(Fd(x), F(x))
>>> Commutator.eval(c1, c2)
0

sympy.physics.secondquant.matrix_rep(op, basis)
Find the representation of an operator in a basis.

Examples

>>> from sympy.physics.secondquant import VarBosonicBasis, B, matrix_rep

>>> b = VarBosonicBasis(5)
>>> o = B(0)
>>> matrix_rep(o, b)
Matrix([
[0, 1, 0, 0, 0],
[0, 0, sqrt(2), 0, 0],
[0, 0, 0, sqrt(3), 0],
[0, 0, 0, 0, 2],
[0, 0, 0, 0, 0]])

sympy.physics.secondquant.contraction(a, b)
Calculates contraction of Fermionic operators a and b.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import F, Fd, contraction
>>> p, q = symbols('p,q')
>>> a, b = symbols('a,b', above_fermi=True)
>>> i, j = symbols('i,j', below_fermi=True)

A contraction is non-zero only if a quasi-creator is to the right of a quasi-annihilator:

1530 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> contraction(F(a),Fd(b))
KroneckerDelta(a, b)
>>> contraction(Fd(i),F(j))
KroneckerDelta(i, j)

For general indices a non-zero result restricts the indices to below/above the fermi sur-
face:

>>> contraction(Fd(p),F(q))
KroneckerDelta(_i, q)*KroneckerDelta(p, q)
>>> contraction(F(p),Fd(q))
KroneckerDelta(_a, q)*KroneckerDelta(p, q)

Two creators or two annihilators always vanishes:

>>> contraction(F(p),F(q))
0
>>> contraction(Fd(p),Fd(q))
0

sympy.physics.secondquant.wicks(e, **kw_args)
Returns the normal ordered equivalent of an expression using Wicks Theorem.

Examples

>>> from sympy import symbols, Function, Dummy

>>> from sympy.physics.secondquant import wicks, F, Fd, NO
>>> p,q,r = symbols('p,q,r')
>>> wicks(Fd(p)*F(q)) # doctest: +SKIP
d(p, q)*d(q, _i) + NO(CreateFermion(p)*AnnihilateFermion(q))

By default, the expression is expanded:

>>> wicks(F(p)*(F(q)+F(r))) # doctest: +SKIP

NO(AnnihilateFermion(p)*AnnihilateFermion(q)) + NO(
AnnihilateFermion(p)*AnnihilateFermion(r))

With the keyword ‘keep_only_fully_contracted=True’, only fully contracted terms are

returned.
By request, the result can be simplified in the following order: – KroneckerDelta
functions are evaluated – Dummy variables are substituted consistently across terms

>>> p, q, r = symbols('p q r', cls=Dummy)

>>> wicks(Fd(p)*(F(q)+F(r)), keep_only_fully_contracted=True) # doctest: +SKIP
KroneckerDelta(_i, _q)*KroneckerDelta(
_p, _q) + KroneckerDelta(_i, _r)*KroneckerDelta(_p, _r)

class sympy.physics.secondquant.NO
This Object is used to represent normal ordering brackets.
i.e. {abcd} sometimes written :abcd:
Applying the function NO(arg) to an argument means that all operators in the argument
will be assumed to anticommute, and have vanishing contractions. This allows an imme-
diate reordering to canonical form upon object creation.

5.40. Physics Module 1531

SymPy Documentation, Release 1.3

>>> from sympy import symbols

>>> from sympy.physics.secondquant import NO, F, Fd
>>> p,q = symbols('p,q')
>>> NO(Fd(p)*F(q))
NO(CreateFermion(p)*AnnihilateFermion(q))
>>> NO(F(q)*Fd(p))
-NO(CreateFermion(p)*AnnihilateFermion(q))

Note: If you want to generate a normal ordered equivalent of an expression, you should
use the function wicks(). This class only indicates that all operators inside the brackets
anticommute, and have vanishing contractions. Nothing more, nothing less.
doit(**kw_args)
Either removes the brackets or enables complex computations in its arguments.

Examples

>>> from sympy.physics.secondquant import NO, Fd, F

>>> from textwrap import fill
>>> from sympy import symbols, Dummy
>>> p,q = symbols('p,q', cls=Dummy)
>>> print(fill(str(NO(Fd(p)*F(q)).doit())))
KroneckerDelta(_a, _p)*KroneckerDelta(_a,
_q)*CreateFermion(_a)*AnnihilateFermion(_a) + KroneckerDelta(_a,
_p)*KroneckerDelta(_i, _q)*CreateFermion(_a)*AnnihilateFermion(_i) -
KroneckerDelta(_a, _q)*KroneckerDelta(_i,
_p)*AnnihilateFermion(_a)*CreateFermion(_i) - KroneckerDelta(_i,
_p)*KroneckerDelta(_i, _q)*AnnihilateFermion(_i)*CreateFermion(_i)

get_subNO(i)
Returns a NO() without FermionicOperator at index i.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import F, NO
>>> p,q,r = symbols('p,q,r')

>>> NO(F(p)*F(q)*F(r)).get_subNO(1) # doctest: +SKIP

NO(AnnihilateFermion(p)*AnnihilateFermion(r))

has_q_annihilators
Return 0 if the rightmost argument of the first argument is a not a q_annihilator,
else 1 if it is above fermi or -1 if it is below fermi.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import NO, F, Fd

1532 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> a = symbols('a', above_fermi=True)

>>> i = symbols('i', below_fermi=True)
>>> NO(Fd(a)*Fd(i)).has_q_annihilators
-1
>>> NO(F(i)*F(a)).has_q_annihilators
1
>>> NO(Fd(a)*F(i)).has_q_annihilators
0

has_q_creators
Return 0 if the leftmost argument of the first argument is a not a q_creator, else 1 if
it is above fermi or -1 if it is below fermi.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import NO, F, Fd

>>> a = symbols('a', above_fermi=True)

>>> i = symbols('i', below_fermi=True)
>>> NO(Fd(a)*Fd(i)).has_q_creators
1
>>> NO(F(i)*F(a)).has_q_creators
-1
>>> NO(Fd(i)*F(a)).has_q_creators #doctest: +SKIP
0

iter_q_annihilators()
Iterates over the annihilation operators.

Examples

>>> from sympy import symbols

>>> i, j = symbols('i j', below_fermi=True)
>>> a, b = symbols('a b', above_fermi=True)
>>> from sympy.physics.secondquant import NO, F, Fd
>>> no = NO(Fd(a)*F(i)*F(b)*Fd(j))

>>> no.iter_q_creators()
<generator object... at 0x...>
>>> list(no.iter_q_creators())
[0, 1]
>>> list(no.iter_q_annihilators())
[3, 2]

iter_q_creators()
Iterates over the creation operators.

5.40. Physics Module 1533

SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> i, j = symbols('i j', below_fermi=True)
>>> a, b = symbols('a b', above_fermi=True)
>>> from sympy.physics.secondquant import NO, F, Fd
>>> no = NO(Fd(a)*F(i)*F(b)*Fd(j))

>>> no.iter_q_creators()
<generator object... at 0x...>
>>> list(no.iter_q_creators())
[0, 1]
>>> list(no.iter_q_annihilators())
[3, 2]

sympy.physics.secondquant.evaluate_deltas(e)
We evaluate KroneckerDelta symbols in the expression assuming Einstein summation.
If one index is repeated it is summed over and in effect substituted with the other one.
If both indices are repeated we substitute according to what is the preferred index. this
is determined by KroneckerDelta.preferred_index and KroneckerDelta.killable_index.
In case there are no possible substitutions or if a substitution would imply a loss of
information, nothing is done.
In case an index appears in more than one KroneckerDelta, the resulting substitution
depends on the order of the factors. Since the ordering is platform dependent, the literal
expression resulting from this function may be hard to predict.

Examples

We assume the following:

>>> from sympy import symbols, Function, Dummy, KroneckerDelta

>>> from sympy.physics.secondquant import evaluate_deltas
>>> i,j = symbols('i j', below_fermi=True, cls=Dummy)
>>> a,b = symbols('a b', above_fermi=True, cls=Dummy)
>>> p,q = symbols('p q', cls=Dummy)
>>> f = Function('f')
>>> t = Function('t')

The order of preference for these indices according to KroneckerDelta is (a, b, i, j, p, q).
Trivial cases:

>>> evaluate_deltas(KroneckerDelta(i,j)*f(i)) # d_ij f(i) -> f(j)

f(_j)
>>> evaluate_deltas(KroneckerDelta(i,j)*f(j)) # d_ij f(j) -> f(i)
f(_i)
>>> evaluate_deltas(KroneckerDelta(i,p)*f(p)) # d_ip f(p) -> f(i)
f(_i)
>>> evaluate_deltas(KroneckerDelta(q,p)*f(p)) # d_qp f(p) -> f(q)
f(_q)
>>> evaluate_deltas(KroneckerDelta(q,p)*f(q)) # d_qp f(q) -> f(p)
f(_p)

More interesting cases:

1534 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> evaluate_deltas(KroneckerDelta(i,p)*t(a,i)*f(p,q))
f(_i, _q)*t(_a, _i)
>>> evaluate_deltas(KroneckerDelta(a,p)*t(a,i)*f(p,q))
f(_a, _q)*t(_a, _i)
>>> evaluate_deltas(KroneckerDelta(p,q)*f(p,q))
f(_p, _p)

Finally, here are some cases where nothing is done, because that would imply a loss of
information:

>>> evaluate_deltas(KroneckerDelta(i,p)*f(q))
f(_q)*KroneckerDelta(_i, _p)
>>> evaluate_deltas(KroneckerDelta(i,p)*f(i))
f(_i)*KroneckerDelta(_i, _p)

class sympy.physics.secondquant.AntiSymmetricTensor
Stores upper and lower indices in separate Tuple’s.
Each group of indices is assumed to be antisymmetric.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import AntiSymmetricTensor
>>> i, j = symbols('i j', below_fermi=True)
>>> a, b = symbols('a b', above_fermi=True)
>>> AntiSymmetricTensor('v', (a, i), (b, j))
AntiSymmetricTensor(v, (a, i), (b, j))
>>> AntiSymmetricTensor('v', (i, a), (b, j))
-AntiSymmetricTensor(v, (a, i), (b, j))

As you can see, the indices are automatically sorted to a canonical form.
doit(**kw_args)
Returns self.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import AntiSymmetricTensor
>>> i, j = symbols('i,j', below_fermi=True)
>>> a, b = symbols('a,b', above_fermi=True)
>>> AntiSymmetricTensor('v', (a, i), (b, j)).doit()
AntiSymmetricTensor(v, (a, i), (b, j))

lower
Returns the lower indices.

Examples

5.40. Physics Module 1535

SymPy Documentation, Release 1.3

>>> from sympy import symbols

>>> from sympy.physics.secondquant import AntiSymmetricTensor
>>> i, j = symbols('i,j', below_fermi=True)
>>> a, b = symbols('a,b', above_fermi=True)
>>> AntiSymmetricTensor('v', (a, i), (b, j))
AntiSymmetricTensor(v, (a, i), (b, j))
>>> AntiSymmetricTensor('v', (a, i), (b, j)).lower
(b, j)

symbol
Returns the symbol of the tensor.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import AntiSymmetricTensor
>>> i, j = symbols('i,j', below_fermi=True)
>>> a, b = symbols('a,b', above_fermi=True)
>>> AntiSymmetricTensor('v', (a, i), (b, j))
AntiSymmetricTensor(v, (a, i), (b, j))
>>> AntiSymmetricTensor('v', (a, i), (b, j)).symbol
v

upper
Returns the upper indices.

Examples

>>> from sympy import symbols

>>> from sympy.physics.secondquant import AntiSymmetricTensor
>>> i, j = symbols('i,j', below_fermi=True)
>>> a, b = symbols('a,b', above_fermi=True)
>>> AntiSymmetricTensor('v', (a, i), (b, j))
AntiSymmetricTensor(v, (a, i), (b, j))
>>> AntiSymmetricTensor('v', (a, i), (b, j)).upper
(a, i)

sympy.physics.secondquant.substitute_dummies(expr, new_indices=False,
pretty_indices={})
Collect terms by substitution of dummy variables.
This routine allows simplification of Add expressions containing terms which differ only
due to dummy variables.
The idea is to substitute all dummy variables consistently depending on the structure of
the term. For each term, we obtain a sequence of all dummy variables, where the order is
determined by the index range, what factors the index belongs to and its position in each
factor. See _get_ordered_dummies() for more inforation about the sorting of dummies.
The index sequence is then substituted consistently in each term.

1536 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols, Function, Dummy

>>> from sympy.physics.secondquant import substitute_dummies
>>> a,b,c,d = symbols('a b c d', above_fermi=True, cls=Dummy)
>>> i,j = symbols('i j', below_fermi=True, cls=Dummy)
>>> f = Function('f')

>>> expr = f(a,b) + f(c,d); expr

f(_a, _b) + f(_c, _d)

Since a, b, c and d are equivalent summation indices, the expression can be simplified
to a single term (for which the dummy indices are still summed over)
>>> substitute_dummies(expr)
2*f(_a, _b)

Controlling output:
By default the dummy symbols that are already present in the expression will be reused in
a different permutation. However, if new_indices=True, new dummies will be generated
and inserted. The keyword ‘pretty_indices’ can be used to control this generation of new
symbols.
By default the new dummies will be generated on the form i_1, i_2, a_1, etc. If you supply
a dictionary with key:value pairs in the form:
{ index_group: string_of_letters }
The letters will be used as labels for the new dummy symbols. The index_groups must
be one of ‘above’, ‘below’ or ‘general’.
>>> expr = f(a,b,i,j)
>>> my_dummies = { 'above':'st', 'below':'uv' }
>>> substitute_dummies(expr, new_indices=True, pretty_indices=my_dummies)
f(_s, _t, _u, _v)

If we run out of letters, or if there is no keyword for some index_group the default dummy
generator will be used as a fallback:
>>> p,q = symbols('p q', cls=Dummy) # general indices
>>> expr = f(p,q)
>>> substitute_dummies(expr, new_indices=True, pretty_indices=my_dummies)
f(_p_0, _p_1)

class sympy.physics.secondquant.PermutationOperator
Represents the index permutation operator P(ij).
P(ij)*f(i)*g(j) = f(i)*g(j) - f(j)*g(i)
get_permuted(expr)
Returns -expr with permuted indices.
>>> from sympy import symbols, Function
>>> from sympy.physics.secondquant import PermutationOperator
>>> p,q = symbols('p,q')
>>> f = Function('f')
>>> PermutationOperator(p,q).get_permuted(f(p,q))
-f(q, p)

5.40. Physics Module 1537

SymPy Documentation, Release 1.3

sympy.physics.secondquant.simplify_index_permutations(expr, permuta-
tion_operators)
Performs simplification by introducing PermutationOperators where appropriate.
Schematically: [abij] - [abji] - [baij] + [baji] -> P(ab)*P(ij)*[abij]
permutation_operators is a list of PermutationOperators to consider.
If permutation_operators=[P(ab),P(ij)] we will try to introduce the permutation operators
P(ij) and P(ab) in the expression. If there are other possible simplifications, we ignore
them.

>>> from sympy import symbols, Function

>>> from sympy.physics.secondquant import simplify_index_permutations
>>> from sympy.physics.secondquant import PermutationOperator
>>> p,q,r,s = symbols('p,q,r,s')
>>> f = Function('f')
>>> g = Function('g')

>>> expr = f(p)*g(q) - f(q)*g(p); expr

f(p)*g(q) - f(q)*g(p)
>>> simplify_index_permutations(expr,[PermutationOperator(p,q)])
f(p)*g(q)*PermutationOperator(p, q)

>>> PermutList = [PermutationOperator(p,q),PermutationOperator(r,s)]

>>> expr = f(p,r)*g(q,s) - f(q,r)*g(p,s) + f(q,s)*g(p,r) - f(p,s)*g(q,r)
>>> simplify_index_permutations(expr,PermutList)
f(p, r)*g(q, s)*PermutationOperator(p, q)*PermutationOperator(r, s)

Wigner Symbols

Wigner, Clebsch-Gordan, Racah, and Gaunt coefficients

Collection of functions for calculating Wigner 3j, 6j, 9j, Clebsch-Gordan, Racah as well as
Gaunt coefficients exactly, all evaluating to a rational number times the square root of a
rational number [Rasch03].
Please see the description of the individual functions for further details and examples.

References

Credits and Copyright

This code was taken from Sage with the permission of all authors:
https://groups.google.com/forum/#!topic/sage-devel/M4NZdu-7O38
AUTHORS:
• Jens Rasch (2009-03-24): initial version for Sage
• Jens Rasch (2009-05-31): updated to sage-4.0
Copyright (C) 2008 Jens Rasch <[email protected]>
sympy.physics.wigner.clebsch_gordan(j_1, j_2, j_3, m_1, m_2, m_3)
Calculates the Clebsch-Gordan coefficient ⟨j1 m1 j2 m2 |j3 m3 ⟩.

1538 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The reference for this function is [Edmonds74].

INPUT:
• j_1, j_2, j_3, m_1, m_2, m_3 - integer or half integer
OUTPUT:
Rational number times the square root of a rational number.
EXAMPLES:

>>> from sympy import S

>>> from sympy.physics.wigner import clebsch_gordan
>>> clebsch_gordan(S(3)/2, S(1)/2, 2, S(3)/2, S(1)/2, 2)
1
>>> clebsch_gordan(S(3)/2, S(1)/2, 1, S(3)/2, -S(1)/2, 1)
sqrt(3)/2
>>> clebsch_gordan(S(3)/2, S(1)/2, 1, -S(1)/2, S(1)/2, 0)
-sqrt(2)/2

NOTES:
The Clebsch-Gordan coefficient will be evaluated via its relation to Wigner 3j symbols:
√
⟨j1 m1 j2 m2 |j3 m3 ⟩ = (−1)j1 −j2 +m3 2j3 + 1 Wigner3j(j1 , j2 , j3 , m1 , m2 , −m3 )

See also the documentation on Wigner 3j symbols which exhibit much higher symmetry
relations than the Clebsch-Gordan coefficient.
AUTHORS:
• Jens Rasch (2009-03-24): initial version
sympy.physics.wigner.dot_rot_grad_Ynm(j, p, l, m, theta, phi)
Returns dot product of rotational gradients of spherical harmonics.
This function returns the right hand side of the following expression:

∑
l+j
1
⃗ p · RY
RY ⃗ ml = (−1)
m+p
Y m+p ∗ αl,m,j,p,k ∗ (k 2 − j 2 − l2 + k − j − l)
j k
2
k=|l−j|

Arguments

j, p, l, m …. indices in spherical harmonics (expressions or integers) theta, phi …. angle

arguments in spherical harmonics

Example

>>> from sympy import symbols

>>> from sympy.physics.wigner import dot_rot_grad_Ynm
>>> theta, phi = symbols(”theta phi”)
>>> dot_rot_grad_Ynm(3, 2, 2, 0, theta, phi).doit()
3*sqrt(55)*Ynm(5, 2, theta, phi)/(11*sqrt(pi))

5.40. Physics Module 1539

SymPy Documentation, Release 1.3

sympy.physics.wigner.gaunt(l_1, l_2, l_3, m_1, m_2, m_3, prec=None)

Calculate the Gaunt coefficient.
The Gaunt coefficient is defined as the integral over three spherical harmonics:
∫
Gaunt(l1 , l2 , l3 , m1 , m2 , m3 ) = Yl1 ,m1 (Ω)Yl2 ,m2 (Ω)Yl3 ,m3 (Ω) dΩ
√
(2l1 + 1)(2l2 + 1)(2l3 + 1)
= Wigner3j(l1 , l2 , l3 , 0, 0, 0) Wigner3j(l1 , l2 , l3 , m1 , m2 , m3 )
4π
INPUT:
• l_1, l_2, l_3, m_1, m_2, m_3 - integer
• prec - precision, default: None. Providing a precision can drastically speed up the
calculation.
OUTPUT:
Rational number times the square root of a rational number (if prec=None), or real num-
ber if a precision is given.

Examples

>>> from sympy.physics.wigner import gaunt

>>> gaunt(1,0,1,1,0,-1)
-1/(2*sqrt(pi))
>>> gaunt(1000,1000,1200,9,3,-12).n(64)
0.00689500421922113448...

It is an error to use non-integer values for l and m:

sage: gaunt(1.2,0,1.2,0,0,0)
Traceback (most recent call last):
...
ValueError: l values must be integer
sage: gaunt(1,0,1,1.1,0,-1.1)
Traceback (most recent call last):
...
ValueError: m values must be integer

NOTES:
The Gaunt coefficient obeys the following symmetry rules:
• invariant under any permutation of the columns

Y (l1 , l2 , l3 , m1 , m2 , m3 ) = Y (l3 , l1 , l2 , m3 , m1 , m2 )
= Y (l2 , l3 , l1 , m2 , m3 , m1 )
= Y (l3 , l2 , l1 , m3 , m2 , m1 )
= Y (l1 , l3 , l2 , m1 , m3 , m2 )
= Y (l2 , l1 , l3 , m2 , m1 , m3 )

• invariant under space inflection, i.e.

Y (l1 , l2 , l3 , m1 , m2 , m3 ) = Y (l1 , l2 , l3 , −m1 , −m2 , −m3 )

1540 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• symmetric with respect to the 72 Regge symmetries as inherited for the 3j symbols
[Regge58]
• zero for l1 , l2 , l3 not fulfilling triangle relation
• zero for violating any one of the conditions: l1 ≥ |m1 |, l2 ≥ |m2 |, l3 ≥ |m3 |
• non-zero only for an even sum of the li , i.e. L = l1 + l2 + l3 = 2n for n in N
ALGORITHM:
This function uses the algorithm of [Liberatodebrito82] to calculate the value of the
Gaunt coefficient exactly. Note that the formula contains alternating sums over large
factorials and is therefore unsuitable for finite precision arithmetic and only useful for a
computer algebra system [Rasch03].
REFERENCES:
AUTHORS:
• Jens Rasch (2009-03-24): initial version for Sage
sympy.physics.wigner.racah(aa, bb, cc, dd, ee, ff, prec=None)
Calculate the Racah symbol W (a, b, c, d; e, f ).
INPUT:
• a, …, f - integer or half integer
• prec - precision, default: None. Providing a precision can drastically speed up the
calculation.
OUTPUT:
Rational number times the square root of a rational number (if prec=None), or real num-
ber if a precision is given.

Examples

>>> from sympy.physics.wigner import racah

>>> racah(3,3,3,3,3,3)
-1/14

NOTES:
The Racah symbol is related to the Wigner 6j symbol:

Wigner6j(j1 , j2 , j3 , j4 , j5 , j6 ) = (−1)j1 +j2 +j4 +j5 W (j1 , j2 , j5 , j4 , j3 , j6 )

Please see the 6j symbol for its much richer symmetries and for additional properties.
ALGORITHM:
This function uses the algorithm of [Edmonds74] to calculate the value of the 6j symbol
exactly. Note that the formula contains alternating sums over large factorials and is
therefore unsuitable for finite precision arithmetic and only useful for a computer alge-
bra system [Rasch03].
AUTHORS:
• Jens Rasch (2009-03-24): initial version

5.40. Physics Module 1541

SymPy Documentation, Release 1.3

sympy.physics.wigner.wigner_3j(j_1, j_2, j_3, m_1, m_2, m_3)

Calculate the Wigner 3j symbol Wigner3j(j1 , j2 , j3 , m1 , m2 , m3 ).
INPUT:
• j_1, j_2, j_3, m_1, m_2, m_3 - integer or half integer
OUTPUT:
Rational number times the square root of a rational number.

Examples

>>> from sympy.physics.wigner import wigner_3j

>>> wigner_3j(2, 6, 4, 0, 0, 0)
sqrt(715)/143
>>> wigner_3j(2, 6, 4, 0, 0, 1)
0

It is an error to have arguments that are not integer or half integer values:

sage: wigner_3j(2.1, 6, 4, 0, 0, 0)
Traceback (most recent call last):
...
ValueError: j values must be integer or half integer
sage: wigner_3j(2, 6, 4, 1, 0, -1.1)
Traceback (most recent call last):
...
ValueError: m values must be integer or half integer

NOTES:
The Wigner 3j symbol obeys the following symmetry rules:
• invariant under any permutation of the columns (with the exception of a sign change
where J := j1 + j2 + j3 ):

Wigner3j(j1 , j2 , j3 , m1 , m2 , m3 ) = Wigner3j(j3 , j1 , j2 , m3 , m1 , m2 )
= Wigner3j(j2 , j3 , j1 , m2 , m3 , m1 )
= (−1)J Wigner3j(j3 , j2 , j1 , m3 , m2 , m1 )
= (−1)J Wigner3j(j1 , j3 , j2 , m1 , m3 , m2 )
= (−1)J Wigner3j(j2 , j1 , j3 , m2 , m1 , m3 )

• invariant under space inflection, i.e.

Wigner3j(j1 , j2 , j3 , m1 , m2 , m3 ) = (−1)J Wigner3j(j1 , j2 , j3 , −m1 , −m2 , −m3 )

• symmetric with respect to the 72 additional symmetries based on the work by

[Regge58]
• zero for j1 , j2 , j3 not fulfilling triangle relation
• zero for m1 + m2 + m3 ̸= 0
• zero for violating any one of the conditions j1 ≥ |m1 |, j2 ≥ |m2 |, j3 ≥ |m3 |

1542 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ALGORITHM:
This function uses the algorithm of [Edmonds74] to calculate the value of the 3j symbol
exactly. Note that the formula contains alternating sums over large factorials and is
therefore unsuitable for finite precision arithmetic and only useful for a computer alge-
bra system [Rasch03].
REFERENCES:
AUTHORS:
• Jens Rasch (2009-03-24): initial version
sympy.physics.wigner.wigner_6j(j_1, j_2, j_3, j_4, j_5, j_6, prec=None)
Calculate the Wigner 6j symbol Wigner6j(j1 , j2 , j3 , j4 , j5 , j6 ).
INPUT:
• j_1, …, j_6 - integer or half integer
• prec - precision, default: None. Providing a precision can drastically speed up the
calculation.
OUTPUT:
Rational number times the square root of a rational number (if prec=None), or real num-
ber if a precision is given.

Examples

>>> from sympy.physics.wigner import wigner_6j

>>> wigner_6j(3,3,3,3,3,3)
-1/14
>>> wigner_6j(5,5,5,5,5,5)
1/52

It is an error to have arguments that are not integer or half integer values or do not fulfill
the triangle relation:

sage: wigner_6j(2.5,2.5,2.5,2.5,2.5,2.5)
Traceback (most recent call last):
...
ValueError: j values must be integer or half integer and fulfill the triangle␣
,→relation

sage: wigner_6j(0.5,0.5,1.1,0.5,0.5,1.1)
Traceback (most recent call last):
...
ValueError: j values must be integer or half integer and fulfill the triangle␣
,→relation

NOTES:
The Wigner 6j symbol is related to the Racah symbol but exhibits more symmetries as
detailed below.

Wigner6j(j1 , j2 , j3 , j4 , j5 , j6 ) = (−1)j1 +j2 +j4 +j5 W (j1 , j2 , j5 , j4 , j3 , j6 )

The Wigner 6j symbol obeys the following symmetry rules:

5.40. Physics Module 1543

SymPy Documentation, Release 1.3

• Wigner 6j symbols are left invariant under any permutation of the columns:

Wigner6j(j1 , j2 , j3 , j4 , j5 , j6 ) = Wigner6j(j3 , j1 , j2 , j6 , j4 , j5 )
= Wigner6j(j2 , j3 , j1 , j5 , j6 , j4 )
= Wigner6j(j3 , j2 , j1 , j6 , j5 , j4 )
= Wigner6j(j1 , j3 , j2 , j4 , j6 , j5 )
= Wigner6j(j2 , j1 , j3 , j5 , j4 , j6 )

• They are invariant under the exchange of the upper and lower arguments in each of
any two columns, i.e.

Wigner6j(j1 , j2 , j3 , j4 , j5 , j6 ) = Wigner6j(j1 , j5 , j6 , j4 , j2 , j3 ) = Wigner6j(j4 , j2 , j6 , j1 , j5 , j3 ) = Wigner6j(j4 , j5

• additional 6 symmetries [Regge59] giving rise to 144 symmetries in total

• only non-zero if any triple of j’s fulfill a triangle relation
ALGORITHM:
This function uses the algorithm of [Edmonds74] to calculate the value of the 6j symbol
exactly. Note that the formula contains alternating sums over large factorials and is
therefore unsuitable for finite precision arithmetic and only useful for a computer alge-
bra system [Rasch03].
REFERENCES:
sympy.physics.wigner.wigner_9j(j_1, j_2, j_3, j_4, j_5, j_6, j_7, j_8, j_9, prec=None)
Calculate the Wigner 9j symbol Wigner9j(j1 , j2 , j3 , j4 , j5 , j6 , j7 , j8 , j9 ).
INPUT:
• j_1, …, j_9 - integer or half integer
• prec - precision, default: None. Providing a precision can drastically speed up the
calculation.
OUTPUT:
Rational number times the square root of a rational number (if prec=None), or real num-
ber if a precision is given.

Examples

>>> from sympy.physics.wigner import wigner_9j

>>> wigner_9j(1,1,1, 1,1,1, 1,1,0 ,prec=64) # ==1/18
0.05555555...

>>> wigner_9j(1/2,1/2,0, 1/2,3/2,1, 0,1,1 ,prec=64) # ==1/6

0.1666666...

It is an error to have arguments that are not integer or half integer values or do not fulfill
the triangle relation:

sage: wigner_9j(0.5,0.5,0.5, 0.5,0.5,0.5, 0.5,0.5,0.5,prec=64)

Traceback (most recent call last):
...
(continues on next page)

1544 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

ValueError: j values must be integer or half integer and fulfill the triangle␣
,→relation

sage: wigner_9j(1,1,1, 0.5,1,1.5, 0.5,1,2.5,prec=64)

Traceback (most recent call last):
...
ValueError: j values must be integer or half integer and fulfill the triangle␣
,→relation

ALGORITHM:
This function uses the algorithm of [Edmonds74] to calculate the value of the 3j symbol
exactly. Note that the formula contains alternating sums over large factorials and is
therefore unsuitable for finite precision arithmetic and only useful for a computer alge-
bra system [Rasch03].

Unit systems

This module integrates unit systems into SymPy, allowing a user choose which system to use
when doing their computations and providing utilities to display and convert units.
Unit systems are composed of units and constants, which are themselves described from
dimensions and numbers, and possibly a prefix. Quantities are defined by their unit and their
numerical value, with respect to the current system.
The main advantage of this implementation over the old unit module is that it divides the
units in unit systems, so that the user can decide which units to use, instead of having all in
the name space (for example astrophysicists can only use units with ua, Earth or Sun masses,
the theoricists will use natural system, etc.). Moreover it allows a better control over the
dimensions and conversions.
Ideas about future developments can be found on the Github wiki.

Philosophy behind unit systems

Dimensions

Introduction

At the root of unit systems are dimension systems, whose structure mainly determines the
one of unit systems. Our definition could seem rough but they are largely sufficient for our
purposes.
A dimension will be defined as a property which is measurable and assigned to a specific
phenomenon. In this sense dimensions are different from pure numbers because they carry
some extra-sense, and for this reason two different dimensions cannot be added. For example
time or length are dimensions, but also any other things which has some sense for us, like
angle, number of particles (moles…) or information (bits…).
From this point of view the only truly dimensionless quantity are pure numbers. The idea
of being dimensionless is very system-dependent, as can be seen from the (c, ℏ, G), in which
all units appears to be dimensionless in the usual common sense. This is unavoidable for
computability of generic unit systems (but at the end we can tell the program what is dimen-
sionless).

5.40. Physics Module 1545

SymPy Documentation, Release 1.3

Dimensions can be composed together by taking their product or their ratio (to be defined
below). For example the velocity is defined as length divided by time, or we can see the length
as velocity multiplied by time, depending of what we see as the more fundamental: in general
we can select a set of base dimensions from which we can describe all the others.

Group structure

After this short introduction whose aim was to introduce the dimensions from an intuitive
perspective, we describe the mathematical structure. A dimension system with n independent
dimensions {di }i=1,...,n is described by a multiplicative group G:
• there an identity element 1 corresponding to pure numbers;
• the product D3 = D1 D2 of two elements D1 , D2 ∈ G is also in G;
• any element D ∈ G has an inverse D−1 ∈ G.
We denote
Dn = D × · · · × D,
| {z }
n times

and by definition D0 = 1. The {di }i=1,...,n are called generators of the group since any element
D ∈ G can be expressed as the product of powers of the generators:

∏
n
D= dai i , ai ∈ Z.
i=1

The identity is given for ai = 0, ∀i, while we recover the generator di for ai = 1, aj = 0, ∀j ̸= i.
This group has the following properties:
1. abelian, since the generator commutes, [di , dj ] = 0;
2. countable (infinite but discrete) since the elements are indexed by the powers of the
generators1 .
One can change the dimension basis {d′i }i=1,...,n by taking some combination of the old gener-
ators:
∏
n
d′i =
P
dj ij .
j=1

Linear space representation

It is possible to use the linear space Zn as a representation of the group since the power
coefficients ai carry all the information one needs (we do not distinguish between the element
of the group and its representation):
 
a1
 
(di )j = δij , D =  ...  .
an
1 In general we will consider only dimensions with a maximum coefficient, so we can only a truncation of the
group; but this is not useful for the algorithm.

1546 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The change of basis to d′i follows the usual rule of change of basis for linear space, the matrix
being given by the coefficients Pij , which are simply the coefficients of the new vectors in
term of the old basis:

d′i = Pij dj .

We will use this last solution in our algorithm.

An example

In order to illustrate all this formalism, we end this section with a specific example, the MKS
system (m, kg, s) with dimensions (L: length, M: mass, T: time). They are represented as (we
will always sort the vectors in alphabetic order)
     
1 0 0
L = 0 , M = 1 , T = 0 .
0 0 1

Other dimensions can be derived, for example velocity V or action A

V = LT −1 , A = M L2 T −2 ,
   
1 2
V =  0 , A =  1 .
−1 −2

We can change the basis to go to the natural system (m, c, ℏ) with dimension (L: length, V:
velocity, A: action)2 . In this basis the generators are
     
1 0 0
A = 0 , L = 1 , V = 0 ,
0 0 1

whereas the mass and time are given by

T = LV −1 , M = AV −2 ,
   
0 1
T =  1 , M =  0 .
−1 −2

Finally the inverse change of basis matrix P −1 is obtained by gluing the vectors expressed in
the old basis:
 
2 1 1
P −1 =  1 0 0  .
−2 0 −1

To find the change of basis matrix we just have to take the inverse
 
0 1 0
P = 1 0 1 .
0 −2 −1
2 We anticipate a little by considering c and ℏ as units and not as physical constants.

5.40. Physics Module 1547

SymPy Documentation, Release 1.3

Quantities

A quantity is defined by its name, dimension and factor to a canonical quantity of the same
dimension. The canonical quantities are an internal reference of the units module and should
not be relevant for end-users. Both units and physical constants are quantities.

Units

Units, such as meters, seconds and kilograms, are usually reference quantities chosen by men
to refer to other quantities.
After defining several units of different dimensions we can form a unit system, which is basi-
cally a dimension system with a notion of scale.

Constants

Physical constants are just quantities. They indicate that we used not to understand that two
dimensions are in fact the same. For example, we see a velocity for the light different from
1 because we do not think that time is the same as space (which is normal because of our
sense; but it is different at the fundamental level). For example, once there was the “heat
constant” which allowed to convert between joules and calories since people did not know
that heat was energy. As soon as they understood it they fixed this constant to 1 (this is a very
schematic story).
We can interpret the fact that now we fix the value of fundamental constants in the SI as
showing that they are units (and we use them to define the other usual units).

The need for a reference

It is not possible to define from scratch units and unit systems: one needs to define some
references, and then build the rest over them. Said in another way, we need an origin for the
scales of our units (i.e. a unit with factor 1), and to be sure that all units of a given dimension
are defined consistently we need to use the same origin for all of them. This can happen if
we want to use a derived unit as a base units in another system: we should not define it as
having a scale 1, because, even if it is inconsistent inside the system, we could not convert
to the first system since we have two different units (from our point of view) of same scale
(which means they are equal for the computer).
We will say that the dimensions and scales defined outside systems are canonical, because
we use them for all computations. On the other side the dimensions and scales obtained with
reference to a system are called physical, because they ultimately carry a sense.
Let’s use a concrete (and important) example: the case of the mass units. We would like to
define the gram as the origin. We would like to define the gram as the canonical origin for
the mass, so we assign it a scale 1. Then we can define a system (e.g. in chemistry) that take
it as a base unit. The MKS system prefers to use the kilogram; a naive choice would be to
attribute it a scale if 1 since it is a base, but we see that we could not convert to the chemistry
system because g and kg have both been given the same factor. So we need to define kg as
1000 g, and only then use it as a base in MKS. But as soon as we ask the question “what is
the factor of kg in MKS?”, we get the answer 1, since it is a base unit.
Thus we will define all computations without referring to a system, and it is only at the end
that we can plug the result into a system to give the context we are interested in.

1548 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Literature

Examples

In the following sections we give few examples of what can be done with this module.

Dimensional analysis

We will start from Newton’s second law

ma = F

where m, a and F are the mass, the acceleration and the force respectively. Knowing the
dimensions of m (M ) and a (LT −2 ), we will determine the dimension of F ; obviously we will
find that it is a force: M LT −2 .
From there we will use the expression of the gravitational force between the particle of mass
m and the body of mass M , at a distance r
GmM
F =
r2
to determine the dimension of the Newton’s constant G. The result should be L3 M −1 T −2 .
>>> from sympy import symbols
>>> from sympy.physics.units import length, mass, acceleration, force
>>> from sympy.physics.units import gravitational_constant as G
>>> from sympy.physics.units.dimensions import dimsys_SI
>>> F = mass*acceleration
>>> F
Dimension(acceleration*mass)
>>> dimsys_SI.get_dimensional_dependencies(F)
{'length': 1, 'mass': 1, 'time': -2}
>>> dimsys_SI.get_dimensional_dependencies(force)
{'length': 1, 'mass': 1, 'time': -2}

Dimensions cannot compared directly, even if in the SI convention they are the
same:
>>> F == force
False

Dimension system objects provide a way to test the equivalence of dimensions:

>>> dimsys_SI.equivalent_dims(F, force)
True

>>> m1, m2, r = symbols(”m1 m2 r”)

>>> grav_eq = G * m1 * m2 / r**2
>>> F2 = grav_eq.subs({m1: mass, m2: mass, r: length, G: G.dimension})
>>> F2 #doctest: +SKIP
Dimension(mass*length*time**-2)
>>> F2.get_dimensional_dependencies() #doctest: +SKIP
{'length': 1, 'mass': 1, 'time': -2}

Note that one should first solve the equation, and then substitute with the dimensions.

5.40. Physics Module 1549

SymPy Documentation, Release 1.3

Equation with quantities

Using Kepler’s third law

T2 4π 2
=
a3 GM
we can find the Venus orbital period using the known values for the other variables (taken
from Wikipedia). The result should be 224.701 days.

>>> from sympy import solve, symbols, pi, Eq

>>> from sympy.physics.units import Quantity, length, mass
>>> from sympy.physics.units import day, gravitational_constant as G
>>> from sympy.physics.units import meter, kilogram
>>> T = symbols(”T”)
>>> a = Quantity(”venus_a”)

Specify the dimension and scale in SI units:

>>> a.set_dimension(length, ”SI”)

>>> a.set_scale_factor(108208000e3*meter, ”SI”)

Add the solar mass as quantity:

>>> M = Quantity(”solar_mass”)
>>> M.set_dimension(mass, ”SI”)
>>> M.set_scale_factor(1.9891e30*kilogram, ”SI”)

Now Kepler’s law:

>>> eq = Eq(T**2 / a**3, 4*pi**2 / G / M)

>>> eq
Eq(T**2/venus_a**3, 4*pi**2/(gravitational_constant*solar_mass))
>>> q = solve(eq, T)[1]
>>> q
2*pi*venus_a**(3/2)/(sqrt(gravitational_constant)*sqrt(solar_mass))

To convert to days, use the convert_to function (and possibly approximate the outcoming
result):

>>> from sympy.physics.units import convert_to

>>> convert_to(q, day)
71.5123904642338*pi*day
>>> convert_to(q, day).n()
224.662800523082*day

We could also have the solar mass and the day as units coming from the astrophysical system,
but we wanted to show how to create a unit that one needs.
We can see in this example that intermediate dimensions can be ill-defined, such as sqrt(G),
but one should check that the final result - when all dimensions are combined - is well defined.

Dimensions and dimension systems

Definition of physical dimensions.

Unit systems will be constructed on top of these dimensions.

1550 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Most of the examples in the doc use MKS system and are presented from the computer point
of view: from a human point, adding length to time is not legal in MKS but it is in natural
system; for a computer in natural system there is no time dimension (but a velocity dimension
instead) - in the basis - so the question of adding time to length has no meaning.
class sympy.physics.units.dimensions.Dimension
This class represent the dimension of a physical quantities.
The Dimension constructor takes as parameters a name and an optional symbol.
For example, in classical mechanics we know that time is different from temperature and
dimensions make this difference (but they do not provide any measure of these quantites.

>>> from sympy.physics.units import Dimension

>>> length = Dimension('length')
>>> length
Dimension(length)
>>> time = Dimension('time')
>>> time
Dimension(time)

Dimensions can be composed using multiplication, division and exponentiation (by a

number) to give new dimensions. Addition and subtraction is defined only when the two
objects are the same dimension.

>>> velocity = length / time

>>> velocity
Dimension(length/time)

It is possible to use a dimension system object to get the dimensionsal dependencies of

a dimension, for example the dimension system used by the SI units convention can be
used:

>>> from sympy.physics.units.dimensions import dimsys_SI

>>> dimsys_SI.get_dimensional_dependencies(velocity)
{'length': 1, 'time': -1}
>>> length + length
Dimension(length)
>>> l2 = length**2
>>> l2
Dimension(length**2)
>>> dimsys_SI.get_dimensional_dependencies(l2)
{'length': 2}

has_integer_powers(dim_sys)
Check if the dimension object has only integer powers.
All the dimension powers should be integers, but rational powers may appear in
intermediate steps. This method may be used to check that the final result is well-
defined.
is_dimensionless
Check if the dimension object really has a dimension.
A dimension should have at least one component with non-zero power.
class sympy.physics.units.dimensions.DimensionSystem
DimensionSystem represents a coherent set of dimensions.
The constructor takes three parameters:

5.40. Physics Module 1551

SymPy Documentation, Release 1.3

• base dimensions;
• derived dimensions: these are defined in terms of the base dimensions (for example
velocity is defined from the division of length by time);
• dependency of dimensions: how the derived dimensions depend on the base dimen-
sions.
Optionally either the derived_dims or the dimensional_dependencies may be omitted.

can_transf_matrix
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Return the canonical transformation matrix from the canonical to the base dimen-
sion basis.
It is the inverse of the matrix computed with inv_can_transf_matrix().
dim
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Give the dimension of the system.
That is return the number of dimensions forming the basis.
dim_can_vector(dim)
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Dimensional representation in terms of the canonical base dimensions.
dim_vector(dim)
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Vector representation in terms of the base dimensions.
inv_can_transf_matrix
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Compute the inverse transformation matrix from the base to the canonical dimension
basis.
It corresponds to the matrix where columns are the vector of base dimensions in
canonical basis.
This matrix will almost never be used because dimensions are always defined with
respect to the canonical basis, so no work has to be done to get them in this basis.
Nonetheless if this matrix is not square (or not invertible) it means that we have
chosen a bad basis.
is_consistent
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Check if the system is well defined.

1552 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

is_dimensionless(dimension)
Check if the dimension object really has a dimension.
A dimension should have at least one component with non-zero power.
list_can_dims
Useless method, kept for compatibility with previous versions.
DO NOT USE.
List all canonical dimension names.
print_dim_base(dim)
Give the string expression of a dimension in term of the basis symbols.
static sort_dims(dims)
Useless method, kept for compatibility with previous versions.
DO NOT USE.
Sort dimensions given in argument using their str function.
This function will ensure that we get always the same tuple for a given set of dimen-
sions.

Unit prefixes

Module defining unit prefixe class and some constants.

Constant dict for SI and binary prefixes are defined as PREFIXES and BIN_PREFIXES.
class sympy.physics.units.prefixes.Prefix
This class represent prefixes, with their name, symbol and factor.
Prefixes are used to create derived units from a given unit. They should always be en-
capsulated into units.
The factor is constructed from a base (default is 10) to some power, and it gives the total
multiple or fraction. For example the kilometer km is constructed from the meter (factor
1) and the kilo (10 to the power 3, i.e. 1000). The base can be changed to allow e.g.
binary prefixes.
A prefix multiplied by something will always return the product of this other object times
the factor, except if the other object:
• is a prefix and they can be combined into a new prefix;
• defines multiplication with prefixes (which is the case for the Unit class).

Units and unit systems

Unit system for physical quantities; include definition of constants.

class sympy.physics.units.unitsystem.UnitSystem(base, units=(), name=”, de-
scr=”)
UnitSystem represents a coherent set of units.
A unit system is basically a dimension system with notions of scales. Many of the methods
are defined in the same way.
It is much better if all base units have a symbol.

5.40. Physics Module 1553

SymPy Documentation, Release 1.3

dim
Give the dimension of the system.
That is return the number of units forming the basis.
extend(base, units=(), name=”, description=”)
Extend the current system into a new one.
Take the base and normal units of the current system to merge them to the base
and normal units given in argument. If not provided, name and description are
overridden by empty strings.
is_consistent
Check if the underlying dimension system is consistent.
print_unit_base(unit)
Useless method.
DO NOT USE, use instead convert_to.
Give the string expression of a unit in term of the basis.
Units are displayed by decreasing power.

Physical quantities

Physical quantities.
class sympy.physics.units.quantities.Quantity
Physical quantity: can be a unit of measure, a constant or a generic quantity.
abbrev
Symbol representing the unit name.
Prepend the abbreviation with the prefix symbol if it is defines.
convert_to(other)
Convert the quantity to another quantity of same dimensions.

Examples

>>> from sympy.physics.units import speed_of_light, meter, second

>>> speed_of_light
speed_of_light
>>> speed_of_light.convert_to(meter/second)
299792458*meter/second

>>> from sympy.physics.units import liter

>>> liter.convert_to(meter**3)
meter**3/1000

free_symbols
Return free symbols from quantity.
scale_factor
Overall magnitude of the quantity as compared to the canonical units.

1554 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Conversion between quantities

Several methods to simplify expressions involving unit objects.

sympy.physics.units.util.convert_to(expr, target_units)
Convert expr to the same expression with all of its units and quantities represented as
factors of target_units, whenever the dimension is compatible.
target_units may be a single unit/quantity, or a collection of units/quantities.

Examples

>>> from sympy.physics.units import speed_of_light, meter, gram, second, day

>>> from sympy.physics.units import mile, newton, kilogram, atomic_mass_constant
>>> from sympy.physics.units import kilometer, centimeter
>>> from sympy.physics.units import convert_to
>>> convert_to(mile, kilometer)
25146*kilometer/15625
>>> convert_to(mile, kilometer).n()
1.609344*kilometer
>>> convert_to(speed_of_light, meter/second)
299792458*meter/second
>>> convert_to(day, second)
86400*second
>>> 3*newton
3*newton
>>> convert_to(3*newton, kilogram*meter/second**2)
3*kilogram*meter/second**2
>>> convert_to(atomic_mass_constant, gram)
1.66053904e-24*gram

Conversion to multiple units:

>>> convert_to(speed_of_light, [meter, second])

299792458*meter/second
>>> convert_to(3*newton, [centimeter, gram, second])
300000*centimeter*gram/second**2

Conversion to Planck units:

>>> from sympy.physics.units import gravitational_constant, hbar

>>> convert_to(atomic_mass_constant, [gravitational_constant, speed_of_light,␣
,→hbar]).n()

7.62950196312651e-20*gravitational_constant**(-0.5)*hbar**0.5*speed_of_light**0.5

High energy physics

Abstract

Contains docstrings for methods in high energy physics.

5.40. Physics Module 1555

SymPy Documentation, Release 1.3

Gamma matrices

Module to handle gamma matrices expressed as tensor objects.

Examples

>>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, LorentzIndex

>>> from sympy.tensor.tensor import tensor_indices
>>> i = tensor_indices('i', LorentzIndex)
>>> G(i)
GammaMatrix(i)

Note that there is already an instance of GammaMatrixHead in four dimensions: GammaMa-

trix, which is simply declare as

>>> from sympy.physics.hep.gamma_matrices import GammaMatrix

>>> from sympy.tensor.tensor import tensor_indices
>>> i = tensor_indices('i', LorentzIndex)
>>> GammaMatrix(i)
GammaMatrix(i)

To access the metric tensor

>>> LorentzIndex.metric
metric(LorentzIndex,LorentzIndex)

sympy.physics.hep.gamma_matrices.extract_type_tens(expression, component)
Extract from a TensExpr all tensors with component.
Returns two tensor expressions:
• the first contains all Tensor of having component.
• the second contains all remaining.
sympy.physics.hep.gamma_matrices.gamma_trace(t)
trace of a single line of gamma matrices

Examples

>>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, gamma_

,→trace, LorentzIndex

>>> from sympy.tensor.tensor import tensor_indices, tensorhead

>>> p, q = tensorhead('p, q', [LorentzIndex], [[1]])
>>> i0,i1,i2,i3,i4,i5 = tensor_indices('i0:6', LorentzIndex)
>>> ps = p(i0)*G(-i0)
>>> qs = q(i0)*G(-i0)
>>> gamma_trace(G(i0)*G(i1))
4*metric(i0, i1)
>>> gamma_trace(ps*ps) - 4*p(i0)*p(-i0)
0
>>> gamma_trace(ps*qs + ps*ps) - 4*p(i0)*p(-i0) - 4*p(i0)*q(-i0)
0

1556 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.physics.hep.gamma_matrices.kahane_simplify(expression)
This function cancels contracted elements in a product of four dimensional gamma ma-
trices, resulting in an expression equal to the given one, without the contracted gamma
matrices.
Parameters ‘expression‘ the tensor expression containing the gamma
matrices to simplify.

Notes

If spinor indices are given, the matrices must be given in the order given in the product.

References

[1] Algorithm for Reducing Contracted Products of gamma Matrices, Joseph Kahane,
Journal of Mathematical Physics, Vol. 9, No. 10, October 1968.

Examples

When using, always remember that the original expression coefficient has to be handled
separately

>>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, LorentzIndex

>>> from sympy.physics.hep.gamma_matrices import kahane_simplify
>>> from sympy.tensor.tensor import tensor_indices
>>> i0, i1, i2 = tensor_indices('i0:3', LorentzIndex)
>>> ta = G(i0)*G(-i0)
>>> kahane_simplify(ta)
Matrix([
[4, 0, 0, 0],
[0, 4, 0, 0],
[0, 0, 4, 0],
[0, 0, 0, 4]])
>>> tb = G(i0)*G(i1)*G(-i0)
>>> kahane_simplify(tb)
-2*GammaMatrix(i1)
>>> t = G(i0)*G(-i0)
>>> kahane_simplify(t)
Matrix([
[4, 0, 0, 0],
[0, 4, 0, 0],
[0, 0, 4, 0],
[0, 0, 0, 4]])
>>> t = G(i0)*G(-i0)
>>> kahane_simplify(t)
Matrix([
[4, 0, 0, 0],
[0, 4, 0, 0],
[0, 0, 4, 0],
[0, 0, 0, 4]])

If there are no contractions, the same expression is returned

5.40. Physics Module 1557

SymPy Documentation, Release 1.3

>>> tc = G(i0)*G(i1)
>>> kahane_simplify(tc)
GammaMatrix(i0)*GammaMatrix(i1)

Algorithm

The idea behind the algorithm is to use some well-known identities, i.e., for contractions
enclosing an even number of γ matrices
γ µ γa1 · · · γa2N γµ = 2(γa2N γa1 · · · γa2N −1 + γa2N −1 · · · γa1 γa2N )
for an odd number of γ matrices
γ µ γa1 · · · γa2N +1 γµ = −2γa2N +1 γa2N · · · γa1
Instead of repeatedly applying these identities to cancel out all contracted indices, it is
possible to recognize the links that would result from such an operation, the problem is
thus reduced to a simple rearrangement of free gamma matrices.
sympy.physics.hep.gamma_matrices.simplify_gpgp(ex, sort=True)
simplify products G(i)*p(-i)*G(j)*p(-j) -> p(i)*p(-i)

Examples

>>> from sympy.physics.hep.gamma_matrices import GammaMatrix as G, ␣

,→LorentzIndex, simplify_gpgp

>>> from sympy.tensor.tensor import tensor_indices, tensorhead

>>> p, q = tensorhead('p, q', [LorentzIndex], [[1]])
>>> i0,i1,i2,i3,i4,i5 = tensor_indices('i0:6', LorentzIndex)
>>> ps = p(i0)*G(-i0)
>>> qs = q(i0)*G(-i0)
>>> simplify_gpgp(ps*qs*qs)
GammaMatrix(-L_0)*p(L_0)*q(L_1)*q(-L_1)

The Physics Vector Module

Abstract

In this documentation the components of the sympy.physics.vector module have been dis-
cussed. vector has been written to facilitate the operations pertaining to 3-dimensional
vectors, as functions of time or otherwise, in sympy.physics.

References for Physics/Vector

Guide to Vector

1558 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Vector & ReferenceFrame

In vector, vectors and reference frames are the “building blocks” of dynamic systems. This
document will describe these mathematically and describe how to use them with this module’s
code.

Vector

A vector is a geometric object that has a magnitude (or length) and a direction. Vectors in
3-space are often represented on paper as:

Vector out Vector

Vector on page
of page into page

Vector Algebra

Vector algebra is the first topic to be discussed.

Two vectors are said to be equal if and only if (iff) they have the same magnitude and orien-
tation.

Vector Operations

Multiple algebraic operations can be done with vectors: addition between vectors, scalar
multiplication, and vector multiplication.
Vector addition as based on the parallelogram law.

b
a

a+b a
b

5.40. Physics Module 1559

SymPy Documentation, Release 1.3

Vector addition is also commutative:

a+b=b+a
(a + b) + c = a + (b + c)

Scalar multiplication is the product of a vector and a scalar; the result is a vector with the
same orientation but whose magnitude is scaled by the scalar. Note that multiplication by
-1 is equivalent to rotating the vector by 180 degrees about an arbitrary axis in the plane
perpendicular to the vector.
a
2a

-a
A unit vector is simply a vector whose magnitude is equal to 1. Given any vector v we can
define a unit vector as:
v
^
nv =
∥v∥

Note that every vector can be written as the product of a scalar and unit vector.
Three vector products are implemented in vector: the dot product, the cross product, and
the outer product.
The dot product operation maps two vectors to a scalar. It is defined as:

a · b = ∥a∥∥b∥ cos(θ)

where θ is the angle between a and b.

The dot product of two unit vectors represent the magnitude of the common direction; for
other vectors, it is the product of the magnitude of the common direction and the two vectors’
magnitudes. The dot product of two perpendicular is zero. The figure below shows some
examples:

b
a c

a a 45° a

a⋅b=0 a⋅a=1 a ⋅ c = 1/sqrt(2)

1560 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The dot product is commutative:

a·b=b·a

The cross product vector multiplication operation of two vectors returns a vector:

a×b=c

The vector c has the following properties: it’s orientation is perpendicular to both a and b,
it’s magnitude is defined as ∥c∥ = ∥a∥∥b∥ sin(θ) (where θ is the angle between a and b), and
has a sense defined by using the right hand rule between ∥a∥∥b∥. The figure below shows
this:

c / sqrt(2)
c

b a 45°
d
a axa=0

The cross product has the following properties:

It is not commutative:
a × b ̸= b × a
a × b = −b × a

and not associative:

(a × b) × c ̸= a × (b × c)

Two parallel vectors will have a zero cross product.

The outer product between two vectors will not be not be discussed here, but instead in the

5.40. Physics Module 1561

SymPy Documentation, Release 1.3

inertia section (that is where it is used). Other useful vector properties and relationships are:

α(a + b) = αa + αb
a · (b + c) = a · b + a · c
a × (b + c) = a × b + a × b
(a × b) · c gives the scalar triple product.
a × (b · c) does not work, as you cannot cross a vector and a scalar.
(a × b) · c = a · (b × c)
(a × b) · c = (b × c) · a = (c × a) · b
(a × b) × c = b(a · c) − a(b · c)
a × (b × c) = b(a · c) − c(a · b)

Alternative Representation

If we have three non-coplanar unit vectors ^ nx , ^

ny , ^
nz , we can represent any vector a as a =
ax^nx + ay^
ny + az^
nz . In this situation ^
nx , ^
ny , ^
nz are referred to as a basis. ax , ay , az are called the
measure numbers. Usually the unit vectors are mutually perpendicular, in which case we can
refer to them as an orthonormal basis, and they are usually right-handed.
To test equality between two vectors, now we can do the following. With vectors:

a = ax^
nx + ay^ ny + az^ nz
b = bx^
n x + by ^
n y + bz ^
nz

We can claim equality if: ax = bx , ay = by , az = bz .

Vector addition is then represented, for the same two vectors, as:

a + b = (ax + bx )^
nx + (ay + by )^
ny + (az + bz )^
nz

Multiplication operations are now defined as:

αb = αbx^
nx + αby^
ny + αbz^
nz
a · b = ax bx + ay by + az bz
 
^
nx ^ ny ^ nz
a × b = det  ax ay az 
bx by bz
 
ax ay az
(a × b) · c = det  bx by bz 
cx cy cz

To write a vector in a given basis, we can do the follow:

a = (a · ^ nx + (a · ^
nx )^ ny + (a · ^
ny )^ nz )^
nz

1562 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Some numeric examples of these operations follow:

a=^
nx + 5^
ny
b=^
ny + α^
nz
a+b=^
nx + 6^
ny + α^
nz
a·b=5
a ·^
ny = 5
a ·^
nz = 0
a × b = 5α^
nx − α^
ny + ^
nz
b × a = −5α^ ny − ^
nx + α^ nz

Vector Calculus

To deal with the calculus of vectors with moving object, we have to introduce the concept of
a reference frame. A classic example is a train moving along its tracks, with you and a friend
inside. If both you and your friend are sitting, the relative velocity between the two of you is
zero. From an observer outside the train, you will both have velocity though.
We will now apply more rigor to this definition. A reference frame is a virtual “platform”
which we choose to observe vector quantities from. If we have a reference frame N, vector
a is said to be fixed in the frame N if none of its properties ever change when observed from
N. We will typically assign a fixed orthonormal basis vector set with each reference frame; N
will have ^nx , ^
ny , ^
nz as its basis vectors.

Derivatives of Vectors

A vector which is not fixed in a reference frame therefore has changing properties when
observed from that frame. Calculus is the study of change, and in order to deal with the
peculiarities of vectors fixed and not fixed in different reference frames, we need to be more
explicit in our definitions.

5.40. Physics Module 1563

SymPy Documentation, Release 1.3

f
B
e Fixed in:
A B
A cx
d dx
e x
c f x
In the above figure, we have vectors c, d, e, f. If one were to take the derivative of e with
respect to θ:

de
dθ
it is not clear what the derivative is. If you are observing from frame A, it is clearly non-zero.
If you are observing from frame B, the derivative is zero. We will therefore introduce the
frame as part of the derivative notation:
A
de
̸= 0, the derivative of e with respect to θ in the reference frame A
dθ
B
de
= 0, the derivative of e with respect to θ in the reference frame B
dθ
A
dc
= 0, the derivative of c with respect to θ in the reference frame A
dθ
B
dc
̸= 0, the derivative of c with respect to θ in the reference frame B
dθ
Here are some additional properties of derivatives of vectors in specific frames:
A A
d da A db
(a + b) = +
dt dt dt
A A
d dγ da
γa = a+γ
dt dt dt
A A A
d da db
(a × b) = ×b+a×
dt dt dt

Relating Sets of Basis Vectors

We need to now define the relationship between two different reference frames; or how to
relate the basis vectors of one frame to another. We can do this using a direction cosine matrix
(DCM). The direction cosine matrix relates the basis vectors of one frame to another, in the

1564 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

following fashion:
  ^ 
^
ax [A B ] bx
^
ay  = C ^ by 
^
az ^
bz
When two frames (say, A & B) are initially aligned, then one frame has all of its basis vectors
rotated around an axis which is aligned with a basis vector, we say the frames are related by
a simple rotation. The figure below shows this:

az
bz

B
by
A θ
ay
θ
ax bx
The above rotation is a simple rotation about the Z axis by an angle θ. Note that after the
az and ^
rotation, the basis vectors ^ bz are still aligned.
This rotation can be characterized by the following direction cosine matrix:
 
cos(θ) − sin(θ) 0
C =  sin(θ) cos(θ) 0
A B

0 0 1
Simple rotations about the X and Y axes are defined by:
 
1 0 0
DCM for x-axis rotation: 0 cos(θ) − sin(θ)
0 sin(θ) cos(θ)
 
cos(θ) 0 sin(θ)
DCM for y-axis rotation:  0 1 0 
− sin(θ) 0 cos(θ)
Rotation in the positive direction here will be defined by using the right-hand rule.
The direction cosine matrix is also involved with the definition of the dot product between
sets of basis vectors. If we have two reference frames with associated basis vectors, their
direction cosine matrix can be defined as:
   
Cxx Cxy Cxz ^ax · ^
bx ^ax · ^ ax · ^
by ^ bz
Cyx Cyy Cyz  = ^ay · ^
bx ^ay · ^ bz 
ay · ^
by ^
Czx Czy Czz ^ ^
az · b x ^ ^
az · by ^ ^
az · b z
Additionally, the direction cosine matrix is orthogonal, in that:
A
CB = (B CA )−1
= (B CA )T

5.40. Physics Module 1565

SymPy Documentation, Release 1.3

If we have reference frames A and B, which in this example have undergone a simple z-axis
rotation by an amount θ, we will have two sets of basis vectors. We can then define two
vectors: a = ^
ax + ^ az and b = ^
ay + ^ bx + ^
by + ^
bz . If we wish to express b in the A frame, we do
the following:

b =^
bx + ^ by + ^
bz
[ ] [ ] [ ]
b= ^ ax · (bx + ^
^ by + ^
bz ) ^ax + ^ay · (^
bx + ^
by + ^
bz ) ^ay + ^az · (^
bx + ^
by + ^
bz ) ^az
b = (cos(θ) − sin(θ))^ ay + ^
ax + (sin(θ) + cos(θ))^ az

And if we wish to express a in the B, we do:

a =^ax + ^ay + ^
az
[ ] [ ] [ ]
a= ^ bx · (^
ax + ^ az ) ^
ay + ^ bx + ^by · (^
ax + ^ az ) ^
ay + ^ by + ^
bz · (^
ax + ^ az ) ^
ay + ^ bz
a = (cos(θ) + sin(θ))^bx + (− sin(θ) + cos(θ))^ by + ^ bz

Derivatives with Multiple Frames

If we have reference frames A and B we will have two sets of basis vectors. We can then
define two vectors: a = ax^ ax + ay^ az and b = bx^
ay + az^ b x + by ^
b y + bz ^
bz . If we want to take
the derivative of b in the reference frame A, we must first express it in A, and the take the
derivatives of the measure numbers:
A
db d(b · ^
ax ) d(b · ^
ay ) d(b · ^
az )
= ^
ax + ^
ay + ^
az +
dx dx dx dx

Examples

An example of vector calculus:

1566 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ay by

ax bx

A B
In this example we have two bodies, each with an attached reference frame. We will say that
θ and x are functions of time. We wish to know the time derivative of vector c in both the A
and B frames.
First, we need to define c; c = x^
bx + l^
by . This provides a definition in the B frame. We can
now do the following:
B
dc dx ^ dl
= bx + ^ by
dt dt dt
= ẋ^
bx

To take the derivative in the A frame, we have to first relate the two frames:
 
cos(θ) 0 sin(θ)
C =
A B
0 1 0 
− sin(θ) 0 cos(θ)

Now we can do the following:

A
dc d(c · ^ax ) d(c · ^
ay ) d(c · ^ az )
= ^
ax + ^
ay + ^
az
dt dt dt dt
d(cos(θ)x) d(l) d(− sin(θ)x)
= ^
ax + ^
ay + ^az
dt dt dt
= (−θ̇ sin(θ)x + cos(θ)ẋ)^ ax + (θ̇ cos(θ)x + sin(θ)ẋ)^
az

5.40. Physics Module 1567

SymPy Documentation, Release 1.3

Note that this is the time derivative of c in A, and is expressed in the A frame. We can express
it in the B frame however, and the expression will still be valid:
A
dc
= (−θ̇ sin(θ)x + cos(θ)ẋ)^
ax + (θ̇ cos(θ)x + sin(θ)ẋ)^
az
dt
= ẋ^
bx − θx^bz

Note the difference in expression complexity between the two forms. They are equivalent, but
one is much simpler. This is an extremely important concept, as defining vectors in the more
complex forms can vastly slow down formulation of the equations of motion and increase their
length, sometimes to a point where they cannot be shown on screen.

Using Vectors and Reference Frames

We have waited until after all of the relevant mathematical relationships have been defined
for vectors and reference frames to introduce code. This is due to how vectors are formed.
When starting any problem in vector, one of the first steps is defining a reference frame
(remember to import sympy.physics.vector first):
>>> from sympy.physics.vector import *
>>> N = ReferenceFrame('N')

Now we have created a reference frame, N. To have access to any basis vectors, first a
reference frame needs to be created. Now that we have made and object representing N, we
can access its basis vectors:
>>> N.x
N.x
>>> N.y
N.y
>>> N.z
N.z

Vector Algebra, in physics.vector

We can now do basic algebraic operations on these vectors.:

>>> N.x == N.x
True
>>> N.x == N.y
False
>>> N.x + N.y
N.x + N.y
>>> 2 * N.x + N.y
2*N.x + N.y

Remember, don’t add a scalar quantity to a vector (N.x + 5); this will raise an error. At this
point, we’ll use SymPy’s Symbol in our vectors. Remember to refer to SymPy’s Gotchas and
Pitfalls when dealing with symbols.:
>>> from sympy import Symbol, symbols
>>> x = Symbol('x')
>>> x * N.x
(continues on next page)

1568 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

x*N.x
>>> x*(N.x + N.y)
x*N.x + x*N.y

In vector multiple interfaces to vector multiplication have been implemented, at the operator
level, method level, and function level. The vector dot product can work as follows:

>>> N.x & N.x

1
>>> N.x & N.y
0
>>> N.x.dot(N.x)
1
>>> N.x.dot(N.y)
0
>>> dot(N.x, N.x)
1
>>> dot(N.x, N.y)
0

The “official” interface is the function interface; this is what will be used in all examples. This
is to avoid confusion with the attribute and methods being next to each other, and in the case
of the operator operation priority. The operators used in vector for vector multiplication do
not posses the correct order of operations; this can lead to errors. Care with parentheses is
needed when using operators to represent vector multiplication.
The cross product is the other vector multiplication which will be discussed here. It offers
similar interfaces to the dot product, and comes with the same warnings.

>>> N.x ^ N.x

0
>>> N.x ^ N.y
N.z
>>> N.x.cross(N.x)
0
>>> N.x.cross(N.z)
- N.y
>>> cross(N.x, N.y)
N.z
>>> N.x ^ (N.y + N.z)
- N.y + N.z

Two additional operations can be done with vectors: normalizing the vector to length 1, and
getting its magnitude. These are done as follows:

>>> (N.x + N.y).normalize()

sqrt(2)/2*N.x + sqrt(2)/2*N.y
>>> (N.x + N.y).magnitude()
sqrt(2)

Vectors are often expressed in a matrix form, especially for numerical purposes. Since the
matrix form does not contain any information about the reference frame the vector is defined
in, you must provide a reference frame to extract the measure numbers from the vector. There
is a convenience function to do this:

5.40. Physics Module 1569

SymPy Documentation, Release 1.3

>>> (x * N.x + 2 * x * N.y + 3 * x * N.z).to_matrix(N)

Matrix([
[ x],
[2*x],
[3*x]])

Vector Calculus, in physics.vector

We have already introduced our first reference frame. We can take the derivative in that
frame right now, if we desire:
>>> (x * N.x + N.y).diff(x, N)
N.x

SymPy has a diff function, but it does not currently work with vector Vectors, so please use
Vector’s diff method. The reason for this is that when differentiating a Vector, the frame
of reference must be specified in addition to what you are taking the derivative with respect
to; SymPy’s diff function doesn’t fit this mold.
The more interesting case arise with multiple reference frames. If we introduce a second
reference frame, A, we now have two frames. Note that at this point we can add components
of N and A together, but cannot perform vector multiplication, as no relationship between the
two frames has been defined.
>>> A = ReferenceFrame('A')
>>> A.x + N.x
N.x + A.x

If we want to do vector multiplication, first we have to define and orientation. The orient
method of ReferenceFrame provides that functionality.
>>> A.orient(N, 'Axis', [x, N.y])

If we desire, we can view the DCM between these two frames at any time. This can be
calculated with the dcm method. This code: N.dcm(A) gives the dcm N CA .
This orients the A frame relative to the N frame by a simple rotation around the Y axis, by an
amount x. Other, more complicated rotation types include Body rotations, Space rotations,
quaternions, and arbitrary axis rotations. Body and space rotations are equivalent to doing 3
simple rotations in a row, each about a basis vector in the new frame. An example follows:
>>> N = ReferenceFrame('N')
>>> Bp = ReferenceFrame('Bp')
>>> Bpp = ReferenceFrame('Bpp')
>>> B = ReferenceFrame('B')
>>> q1,q2,q3 = symbols('q1 q2 q3')
>>> Bpp.orient(N,'Axis', [q1, N.x])
>>> Bp.orient(Bpp,'Axis', [q2, Bpp.y])
>>> B.orient(Bp,'Axis', [q3, Bp.z])
>>> N.dcm(B)
Matrix([
[ cos(q2)*cos(q3), -
,→sin(q3)*cos(q2), sin(q2)],
[sin(q1)*sin(q2)*cos(q3) + sin(q3)*cos(q1), -sin(q1)*sin(q2)*sin(q3) +␣
,→cos(q1)*cos(q3), -sin(q1)*cos(q2)],

(continues on next page)

1570 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[sin(q1)*sin(q3) - sin(q2)*cos(q1)*cos(q3), sin(q1)*cos(q3) +␣
,→sin(q2)*sin(q3)*cos(q1), cos(q1)*cos(q2)]])
>>> B.orient(N,'Body',[q1,q2,q3],'XYZ')
>>> N.dcm(B)
Matrix([
[ cos(q2)*cos(q3), -
,→sin(q3)*cos(q2), sin(q2)],
[sin(q1)*sin(q2)*cos(q3) + sin(q3)*cos(q1), -sin(q1)*sin(q2)*sin(q3) +␣
,→cos(q1)*cos(q3), -sin(q1)*cos(q2)],

[sin(q1)*sin(q3) - sin(q2)*cos(q1)*cos(q3), sin(q1)*cos(q3) +␣

,→sin(q2)*sin(q3)*cos(q1), cos(q1)*cos(q2)]])

Space orientations are similar to body orientation, but applied from the frame to body. Body
and space rotations can involve either two or three axes: ‘XYZ’ works, as does ‘YZX’, ‘ZXZ’,
‘YXY’, etc. What is key is that each simple rotation is about a different axis than the previous
one; ‘ZZX’ does not completely orient a set of basis vectors in 3 space.
Sometimes it will be more convenient to create a new reference frame and orient relative to an
existing one in one step. The orientnew method allows for this functionality, and essentially
wraps the orient method. All of the things you can do in orient, you can do in orientnew.

>>> C = N.orientnew('C', 'Axis', [q1, N.x])

Quaternions (or Euler Parameters) use 4 value to characterize the orientation of the frame.
This and arbitrary axis rotations are described in the orient and orientnew method help, or
in the references [Kane1983].
Finally, before starting multiframe calculus operations, we will introduce another vector tool:
dynamicsymbols. dynamicsymbols is a shortcut function to create undefined functions of time
within SymPy. The derivative of such a ‘dynamicsymbol’ is shown below.

>>> from sympy import diff

>>> q1, q2, q3 = dynamicsymbols('q1 q2 q3')
>>> diff(q1, Symbol('t'))
Derivative(q1(t), t)

The ‘dynamicsymbol’ printing is not very clear above; we will also introduce a few other tools
here. We can use vprint instead of print for non-interactive sessions.

>>> q1
q1(t)
>>> q1d = diff(q1, Symbol('t'))
>>> vprint(q1)
q1
>>> vprint(q1d)
q1'

For interactive sessions use init_vprinting. There also exist analogs for SymPy’s vprint,
vpprint, and latex, vlatex.

>>> from sympy.physics.vector import init_vprinting

>>> init_vprinting(pretty_print=False)
>>> q1
q1
>>> q1d
q1'

5.40. Physics Module 1571

SymPy Documentation, Release 1.3

A ‘dynamicsymbol’ should be used to represent any time varying quantity in vector, whether
it is a coordinate, varying position, or force. The primary use of a ‘dynamicsymbol’ is for
speeds and coordinates (of which there will be more discussion in the Kinematics Section of
the documentation).
Now we will define the orientation of our new frames with a ‘dynamicsymbol’, and can take
derivatives and time derivatives with ease. Some examples follow.

>>> N = ReferenceFrame('N')
>>> B = N.orientnew('B', 'Axis', [q1, N.x])
>>> (B.y*q2 + B.z).diff(q2, N)
B.y
>>> (B.y*q2 + B.z).dt(N)
(-q1' + q2')*B.y + q2*q1'*B.z

Note that the output vectors are kept in the same frames that they were provided in. This
remains true for vectors with components made of basis vectors from multiple frames:

>>> (B.y*q2 + B.z + q2*N.x).diff(q2, N)

N.x + B.y

How Vectors are Coded

What follows is a short description of how vectors are defined by the code in vector. It is
provided for those who want to learn more about how this part of sympy.physics.vector
works, and does not need to be read to use this module; don’t read it unless you want to learn
how this module was implemented.
Every Vector’s main information is stored in the args attribute, which stores the three mea-
sure numbers for each basis vector in a frame, for every relevant frame. A vector does not
exist in code until a ReferenceFrame is created. At this point, the x, y, and z attributes of the
reference frame are immutable Vector’s which have measure numbers of [1,0,0], [0,1,0], and
[0,0,1] associated with that ReferenceFrame. Once these vectors are accessible, new vectors
can be created by doing algebraic operations with the basis vectors. A vector can have com-
ponents from multiple frames though. That is why args is a list; it has as many elements in
the list as there are unique ReferenceFrames in its components, i.e. if there are A and B frame
basis vectors in our new vector, args is of length 2; if it has A, B, and C frame basis vector,
args is of length three.
Each element in the args list is a 2-tuple; the first element is a SymPy Matrix (this is where
the measure numbers for each set of basis vectors are stored) and the second element is a
ReferenceFrame to associate those measure numbers with.
ReferenceFrame stores a few things. First, it stores the name you supply it on creation (name
attribute). It also stores the direction cosine matrices, defined upon creation with the ori-
entnew method, or calling the orient method after creation. The direction cosine matrices
are represented by SymPy’s Matrix, and are part of a dictionary where the keys are the Ref-
erenceFrame and the value the Matrix; these are set bi-directionally; in that when you orient
A to N you are setting A’s orientation dictionary to include N and its Matrix, but you are also
setting N’s orientation dictionary to include A and its Matrix (that DCM being the transpose
of the other).

1572 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Vector: Kinematics

This document will give some mathematical background to describing a system’s kinematics
as well as how to represent the kinematics in physics.vector.

Introduction to Kinematics

The first topic is rigid motion kinematics. A rigid body is an idealized representation of a
physical object which has mass and rotational inertia. Rigid bodies are obviously not flexible.
We can break down rigid body motion into translational motion, and rotational motion (when
dealing with particles, we only have translational motion). Rotational motion can further be
broken down into simple rotations and general rotations.
Translation of a rigid body is defined as a motion where the orientation of the body does not
change during the motion; or during the motion any line segment would be parallel to itself
at the start of the motion.
Simple rotations are rotations in which the orientation of the body may change, but there is
always one line which remains parallel to itself at the start of the motion.
General rotations are rotations which there is not always one line parallel to itself at the start
of the motion.

Angular Velocity

The angular velocity of a rigid body refers to the rate of change of its orientation. The angular
velocity of a body is written down as: N ω B , or the angular velocity of B in N, which is a vector.
Note that here, the term rigid body was used, but reference frames can also have angular
velocities. Further discussion of the distinction between a rigid body and a reference frame
will occur later when describing the code representation.
Angular velocity is defined as being positive in the direction which causes the orientation
angles to increase (for simple rotations, or series of simple rotations).

5.40. Physics Module 1573

SymPy Documentation, Release 1.3

nx

nx
N
nz
B

ny

N
wB=q nx
The angular velocity vector represents the time derivative of the orientation. As a time deriva-
tive vector quantity, like those covered in the Vector & ReferenceFrame documentation, this
quantity (angular velocity) needs to be defined in a reference frame. That is what the N is in
the above definition of angular velocity; the frame in which the angular velocity is defined in.
The angular velocity of B in N can also be defined by:
N
d^
by ^ ^ N ^
db z ^ ^ N ^
dbx ^ ^
N
ωB = ( · bz )bx + ( · bx )by + ( · by )bz
dt dt dt
It is also common for a body’s angular velocity to be written as:
N
ω B = wx^
b x + wy ^
b y + wz ^
bz

There are a few additional important points relating to angular velocity. The first is the addi-
tion theorem for angular velocities, a way of relating the angular velocities of multiple bodies
and frames. The theorem follows:
N
ω D =N ω A +A ω B +B ω C +C ω D

This is also shown in the following example:

1574 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

nz
A
N
ny ax
q2
nx
q1 cy
bz

q3
B C
D

N
ωA = 0
A
ω B = q˙1^
ax
ω = −q˙2^
B C
bz
C
ω D = q˙3^
cy
N
ax − q˙2^
ω D = q˙1^ bz + q˙3^
cy

Note the signs used in the angular velocity definitions, which are related to how the displace-
ment angle is defined in this case.
This theorem makes defining angular velocities of multibody systems much easier, as the
angular velocity of a body in a chain needs to only be defined to the previous body in order to
be fully defined (and the first body needs to be defined in the desired reference frame). The
following figure shows an example of when using this theorem can make things easier.

p2 w3
w1 w2

p3
p1

Here we can easily write the angular velocity of the body D in the reference frame of the first
body A:
A
ω D = w1 p^1 + w2 p^2 + w3 p^3

5.40. Physics Module 1575

SymPy Documentation, Release 1.3

It is very important to remember to only use this with angular velocities; you cannot use this
theorem with the velocities of points.
There is another theorem commonly used: the derivative theorem. It provides an alternative
method (which can be easier) to calculate the time derivative of a vector in a reference frame:
N B
dv dv N B
= + ω ×v
dt dt
The vector v can be any vector quantity: a position vector, a velocity vector, angular velocity
vector, etc. Instead of taking the time derivative of the vector in N, we take it in B, where B
can be any reference frame or body, usually one in which it is easy to take the derivative on v
in (v is usually composed only of the basis vector set belonging to B). Then we add the cross
product of the angular velocity of our newer frame, N ω B and our vector quantity v. Again, you
can choose any alternative frame for this. Examples follow:

Angular Acceleration

Angular acceleration refers to the time rate of change of the angular velocity vector. Just as
the angular velocity vector is for a body and is specified in a frame, the angular acceleration
vector is for a body and is specified in a frame: N αB , or the angular acceleration of B in N,
which is a vector.
Calculating the angular acceleration is relatively straight forward:
N N
N B d ωB
α =
dt
Note that this can be calculated with the derivative theorem, and when the angular velocity
is defined in a body fixed frame, becomes quite simple:
N N
N B d ωB
α =
dt

B N
d ωB N B N B
N B
α = + ω × ω
dt

N
if ω B = wx^
bx + wy^
by + wz^
bz

B N
N B d ωB
then α = + N
ω B ×N ω B
dt | {z }
this is 0 by definition

N B dwx ^ dwy ^ dwz ^

α = bx + by + bz
dt dt dt

N B
α = w˙x^
bx + w˙y^
by + w˙z^
bz

Again, this is only for the case in which the angular velocity of the body is defined in body
fixed components.

1576 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Point Velocity & Acceleration

Consider a point, P : we can define some characteristics of the point. First, we can define
a position vector from some other point to P . Second, we can define the velocity vector of
P in a reference frame of our choice. Third, we can define the acceleration vector of P in a
reference frame of our choice.
These three quantities are read as:

rOP , the position vector from O to P

N P
v , the velocity of P in the reference frame N
N P
a , the acceleration of P in the reference frame N

Note that the position vector does not have a frame associated with it; this is because there
is no time derivative involved, unlike the velocity and acceleration vectors.
We can find these quantities for a simple example easily:

rOP P
O

Let’s define: rOP = qx^

nx + q y ^
ny
N
N P drOP
v =
dt
N P
then we can calculate: v = q̇x nx + q̇y^
^ ny
N N P
N d v
and : aP =
dt
N P
a = q̈x^
nx + q̈y^
ny

It is critical to understand in the above example that the point O is fixed in the reference frame
N. There is no addition theorem for translational velocities; alternatives will be discussed
later though. Also note that the position of every point might not always need to be defined
to form the dynamic equations of motion. When you don’t want to define the position vector
of a point, you can start by just defining the velocity vector. For the above example:
N P
Let us instead define the velocity vector as: v = ux^
nx + uy^
ny
N P
then acceleration can be written as: a = u̇x^
nx + u̇y^
ny

5.40. Physics Module 1577

SymPy Documentation, Release 1.3

There will often be cases when the velocity of a point is desired and a related point’s velocity
is known. For the cases in which we have two points fixed on a rigid body, we use the 2-Point
Theorem:

N
P
fixed in B
B

S
fixed in B

O
fixed in N
Let’s say we know the velocity of the point S and the angular velocity of the body B, both
defined in the reference frame N. We can calculate the velocity and acceleration of the point
P in N as follows:

v =N vS +N ω B × rSP
N P

a =N aS +N αB × rSP +N ω B × (N ω B × rSP )
N P

When only one of the two points is fixed on a body, the 1 point theorem is used instead.

1578 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

N
P
not fixed in B
B
S
fixed in B

O
fixed in N
Here, the velocity of point S is known in the frame N, the angular velocity of B is known in
N, and the velocity of the point P is known in the frame associated with body B. We can then
write the velocity and acceleration of P in N as:

v =B vP +N vS +N ω B × rSP
N P

a =B aS +N aO +N αB × rSP +N ω B × (N ω B × rSP ) + 2N ω B ×B vP
N P

Examples of applications of the 1 point and 2 point theorem follow.

5.40. Physics Module 1579

SymPy Documentation, Release 1.3

bz
B
nz O by
bx
N P

ny rOP
nx
This example has a disc translating and rotating in a plane. We can easily define the angular
velocity of the body B and velocity of the point O:
N
nz = u3^
ω B = u3^ bz
N O
v = u1^
nx + u2^
ny

and accelerations can be written as:

N B
nz = u˙3^
α = u˙3^ bz
N O
a = u˙1^
nx + u˙2^
ny

We can use the 2 point theorem to calculate the velocity and acceleration of point P now.

rOP = R^
bx
v =N vO +N ω B × rOP
N P

N P
v = u1^ ny + u3^
nx + u2^ bz × R^
bx = u1^ ny + u3 R^
nx + u2^ by
a =N aO +N αB × rOP +N ω B × (N ω B × rOP )
N P

N P
a = u˙1^ ny + u˙3^
nx + u˙2^ bz × R^
bx + u3^
bz × (u3^
bz × R^
bx )
N P
a = u˙1^ ny + Ru˙3^
nx + u˙2^ by − Ru23^
bx

N ny
by
O
bx cy

nx B cx
Q
C P
1580 Chapter 5. SymPy Modules Reference
 SymPy Documentation, Release 1.3

In this example we have a double pendulum. We can use the two point theorem twice here in
order to find the velocity of points Q and P ; point O’s velocity is zero in N.

rOQ = l^
bx
rQP = l^
cx
ω = u1^
N B
bz
N
ω C = u2^
cz
v =N vO +N ω B × rOQ
N Q

v = u1 l^
N Q
by
v =N vQ +N ω C × rQP
N P

v = u1 l^
N Q
by + u2^cz × l^
cx
v = u1 l^
N Q
by + u2 l^
cy

nz

N
O
ny
nx
q1

Q C
q2 P
cz

cy

cx
In this example we have a particle moving on a ring; the ring is supported by a rod which can
rotate about the ^
nx axis. First we use the two point theorem to find the velocity of the center
point of the ring, Q, then use the 1 point theorem to find the velocity of the particle on the

5.40. Physics Module 1581

SymPy Documentation, Release 1.3

ring.
N
ω C = u1^
nx
rOQ = −l^
cz
N Q
v = u1 l^
cy
QP
r cx + sin(q2 )^
= R(cos(q2 )^ cy )
C P
v = Ru2 (−sin(q2 )^
cx + cos(q2 )^
cy )
N P
v =C vP +N vQ +N ω C × rQP
N P
v = Ru2 (−sin(q2 )^
cx + cos(q2 )^
cy ) + u1 l^ cx × R(cos(q2 )^
cy + u1^ cx + sin(q2 )^
cy
N P
v = −Ru2 sin(q2 )^
cx + (Ru2 cos(q2 ) + u1 l)^
cy + Ru1 sin(q2 )^
cz
A final topic in the description of velocities of points is that of rolling, or rather, rolling without
slip. Two bodies are said to be rolling without slip if and only if the point of contact on each
body has the same velocity in another frame. See the following figure:

N A
Pa is the contact point on body A

P Pb is the contact point on body B

Rolling without slip iff:

N Pa
v = NvPb
B
This is commonly used to form the velocity of a point on one object rolling on another fixed
object, such as in the following example:

Kinematics in physics.vector

It should be clear by now that the topic of kinematics here has been mostly describing the
correct way to manipulate vectors into representing the velocities of points. Within vector
there are convenient methods for storing these velocities associated with frames and points.
We’ll now revisit the above examples and show how to represent them in sympy (page 801).
The topic of reference frame creation has already been covered. When a ReferenceFrame is
created though, it automatically calculates the angular velocity of the frame using the time
derivative of the DCM and the angular velocity definition.
>>> from sympy import Symbol, sin, cos
>>> from sympy.physics.vector import *
>>> N = ReferenceFrame('N')
>>> q1 = dynamicsymbols('q1')
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> A.ang_vel_in(N)
q1'*N.x

1582 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Note that the angular velocity can be defined in an alternate way:

>>> B = ReferenceFrame('B')
>>> u1 = dynamicsymbols('u1')
>>> B.set_ang_vel(N, u1 * B.y)
>>> B.ang_vel_in(N)
u1*B.y
>>> N.ang_vel_in(B)
- u1*B.y

Both upon frame creation during orientnew and when calling set_ang_vel, the angular ve-
locity is set in both frames involved, as seen above.

nz
A
N
ny ax
q2
nx
q1 cy
bz

q3
B C
D

Here we have multiple bodies with angular velocities defined relative to each other. This is
coded as:

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> B = ReferenceFrame('B')
>>> C = ReferenceFrame('C')
>>> D = ReferenceFrame('D')
>>> u1, u2, u3 = dynamicsymbols('u1 u2 u3')
>>> A.set_ang_vel(N, 0)
>>> B.set_ang_vel(A, u1 * A.x)
>>> C.set_ang_vel(B, -u2 * B.z)
>>> D.set_ang_vel(C, u3 * C.y)
>>> D.ang_vel_in(N)
u1*A.x - u2*B.z + u3*C.y

In vector the shortest path between two frames is used when finding the angular velocity.
That would mean if we went back and set:

>>> D.set_ang_vel(N, 0)
>>> D.ang_vel_in(N)
0

The path that was just defined is what is used. This can cause problems though, as now the

5.40. Physics Module 1583

SymPy Documentation, Release 1.3

angular velocity definitions are inconsistent. It is recommended that you avoid doing this.
Points are a translational analog to the rotational ReferenceFrame. Creating a Point can be
done in two ways, like ReferenceFrame:
>>> O = Point('O')
>>> P = O.locatenew('P', 3 * N.x + N.y)
>>> P.pos_from(O)
3*N.x + N.y
>>> Q = Point('Q')
>>> Q.set_pos(P, N.z)
>>> Q.pos_from(P)
N.z
>>> Q.pos_from(O)
3*N.x + N.y + N.z

Similar to ReferenceFrame, the position vector between two points is found by the shortest
path (number of intermediate points) between them. Unlike rotational motion, there is no
addition theorem for the velocity of points. In order to have the velocity of a Point in a
ReferenceFrame, you have to set the value.
>>> O = Point('O')
>>> O.set_vel(N, u1*N.x)
>>> O.vel(N)
u1*N.x

For both translational and rotational accelerations, the value is computed by taking the time
derivative of the appropriate velocity, unless the user sets it otherwise.
>>> O.acc(N)
u1'*N.x
>>> O.set_acc(N, u2*u1*N.y)
>>> O.acc(N)
u1*u2*N.y

Next is a description of the 2 point and 1 point theorems, as used in sympy.

bz
B
nz O by
bx
N P

ny rOP
nx
First is the translating, rotating disc.

1584 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> N = ReferenceFrame('N')
>>> u1, u2, u3 = dynamicsymbols('u1 u2 u3')
>>> R = Symbol('R')
>>> B = ReferenceFrame('B')
>>> O = Point('O')
>>> O.set_vel(N, u1 * N.x + u2 * N.y)
>>> P = O.locatenew('P', R * B.x)
>>> B.set_ang_vel(N, u3 * B.z)
>>> P.v2pt_theory(O, N, B)
u1*N.x + u2*N.y + R*u3*B.y
>>> P.a2pt_theory(O, N, B)
u1'*N.x + u2'*N.y - R*u3**2*B.x + R*u3'*B.y

We will also cover implementation of the 1 point theorem.

nz

N
O
ny
nx
q1

Q C
q2 P
cz

cy

cx
This is the particle moving on a ring, again.

>>> N = ReferenceFrame('N')
>>> u1, u2 = dynamicsymbols('u1 u2')
>>> q1, q2 = dynamicsymbols('q1 q2')
>>> l = Symbol('l')
>>> R = Symbol('R')
>>> C = N.orientnew('C', 'Axis', [q1, N.x])
>>> C.set_ang_vel(N, u1 * N.x)
>>> O = Point('O')
>>> O.set_vel(N, 0)
>>> Q = O.locatenew('Q', -l * C.z)
>>> P = Q.locatenew('P', R * (cos(q2) * C.x + sin(q2) * C.y))
>>> P.set_vel(C, R * u2 * (-sin(q2) * C.x + cos(q2) * C.y))
(continues on next page)

5.40. Physics Module 1585

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Q.v2pt_theory(O, N, C)
l*u1*C.y
>>> P.v1pt_theory(Q, N, C)
- R*u2*sin(q2)*C.x + (R*u2*cos(q2) + l*u1)*C.y + R*u1*sin(q2)*C.z

Potential Issues/Advanced Topics/Future Features in Physics/Vector Module

This document will describe some of the more advanced functionality that this module offers
but which is not part of the “official” interface. Here, some of the features that will be im-
plemented in the future will also be covered, along with unanswered questions about proper
functionality. Also, common problems will be discussed, along with some solutions.

Inertia (Dyadics)

A dyadic tensor is a second order tensor formed by the juxtaposition of a pair of vectors.
There are various operations defined with respect to dyadics, which have been implemented
in vector in the form of class Dyadic. To know more, refer to the Dyadic and Vector class
APIs. Dyadics are used to define the inertia of bodies within mechanics. Inertia dyadics can
be defined explicitly but the inertia function is typically much more convenient for the user:

>>> from sympy.physics.mechanics import ReferenceFrame, inertia

>>> N = ReferenceFrame('N')

Supply a reference frame and the moments of inertia if the object

is symmetrical:

>>> inertia(N, 1, 2, 3)
(N.x|N.x) + 2*(N.y|N.y) + 3*(N.z|N.z)

Supply a reference frame along with the products and moments of inertia
for a general object:

>>> inertia(N, 1, 2, 3, 4, 5, 6)
(N.x|N.x) + 4*(N.x|N.y) + 6*(N.x|N.z) + 4*(N.y|N.x) + 2*(N.y|N.y) + 5*(N.y|N.z) +␣
,→6*(N.z|N.x) + 5*(N.z|N.y) + 3*(N.z|N.z)

Notice that the inertia function returns a dyadic with each component represented as two
unit vectors separated by a |. Refer to the Dyadic (page 1628) section for more information
about dyadics.
Inertia is often expressed in a matrix, or tensor, form, especially for numerical purposes.
Since the matrix form does not contain any information about the reference frame(s) the
inertia dyadic is defined in, you must provide one or two reference frames to extract the
measure numbers from the dyadic. There is a convenience function to do this:

>>> inertia(N, 1, 2, 3, 4, 5, 6).to_matrix(N)

Matrix([
[1, 4, 6],
[4, 2, 5],
[6, 5, 3]])

1586 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Common Issues

Here issues with numerically integrating code, choice of dynamicsymbols for coordinate and
speed representation, printing, differentiating, and substitution will occur.

Printing

The default printing options are to use sorting for Vector and Dyadic measure numbers, and
have unsorted output from the vprint, vpprint, and vlatex functions. If you are printing
something large, please use one of those functions, as the sorting can increase printing time
from seconds to minutes.

Substitution

Substitution into large expressions can be slow, and take a few minutes.

Acceleration of Points

At a minimum, points need to have their velocities defined, as the acceleration can be calcu-
lated by taking the time derivative of the velocity in the same frame. If the 1 point or 2 point
theorems were used to compute the velocity, the time derivative of the velocity expression
will most likely be more complex than if you were to use the acceleration level 1 point and 2
point theorems. Using the acceleration level methods can result in shorted expressions at this
point, which will result in shorter expressions later (such as when forming Kane’s equations).

Advanced Interfaces

Here we will cover advanced options in: ReferenceFrame, dynamicsymbols, and some asso-
ciated functionality.

ReferenceFrame

ReferenceFrame is shown as having a .name attribute and .x, .y, and .z attributes for ac-
cessing the basis vectors, as well as a fairly rigidly defined print output. If you wish to have
a different set of indices defined, there is an option for this. This will also require a different
interface for accessing the basis vectors.
>>> from sympy.physics.vector import ReferenceFrame, vprint, vpprint, vlatex
>>> N = ReferenceFrame('N', indices=['i', 'j', 'k'])
>>> N['i']
N['i']
>>> N.x
N['i']
>>> vlatex(N.x)
'\\mathbf{\\hat{n}_{i}}'

Also, the latex output can have custom strings; rather than just indices though, the entirety
of each basis vector can be specified. The custom latex strings can occur without custom
indices, and also overwrites the latex string that would be used if there were custom indices.

5.40. Physics Module 1587

SymPy Documentation, Release 1.3

>>> from sympy.physics.vector import ReferenceFrame, vlatex

>>> N = ReferenceFrame('N', latexs=['n1','\mathbf{n}_2','cat'])
>>> vlatex(N.x)
'n1'
>>> vlatex(N.y)
'\\mathbf{n}_2'
>>> vlatex(N.z)
'cat'

dynamicsymbols

The dynamicsymbols function also has ‘hidden’ functionality; the variable which is associated
with time can be changed, as well as the notation for printing derivatives.

>>> from sympy import symbols

>>> from sympy.physics.vector import dynamicsymbols, vprint
>>> q1 = dynamicsymbols('q1')
>>> q1
q1(t)
>>> dynamicsymbols._t = symbols('T')
>>> q2 = dynamicsymbols('q2')
>>> q2
q2(T)
>>> q1
q1(t)
>>> q1d = dynamicsymbols('q1', 1)
>>> vprint(q1d)
q1'
>>> dynamicsymbols._str = 'd'
>>> vprint(q1d)
q1d
>>> dynamicsymbols._str = '\''
>>> dynamicsymbols._t = symbols('t')

Note that only dynamic symbols created after the change are different. The same is not true
for the .s tr attribute; this affects the printing output only, so dynamic symbols created before
or after will print the same way.
Also note that Vector’s .dt method uses the ._t attribute of dynamicsymbols, along with a
number of other important functions and methods. Don’t mix and match symbols representing
time.

Scalar and Vector Field Functionality

Introduction

Vectors and Scalars

In physics, we deal with two kinds of quantities – scalars and vectors.

A scalar is an entity which only has a magnitude – no direction. Examples of scalar quantities
include mass, electric charge, temperature, distance, etc.

1588 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

A vector, on the other hand, is an entity that is characterized by a magnitude and a direction.
Examples of vector quantities are displacement, velocity, magnetic field, etc.
A scalar can be depicted just by a number, for e.g. a temperature of 300 K. On the other
hand, vectorial quantities like acceleration are usually denoted by a vector. Given a vector
V, the magnitude of the corresponding quantity can be calculated as the magnitude of the
vector itself ∥V∥, while the direction would be specified by a unit vector in the direction of the
original vector, ^ V
V = ∥V∥ .

For example, consider a displacement of (3^ i + 4^

j + 5^
k) m, where , as per standard convention,
^
i, ^
j and ^
k represent unit vectors in the X, Y and Z directions √ respectively. Therefore, it can
be concluded that the distance traveled is ∥3^ i + 4^
j + 5^
k∥ m = 5 2 m. The direction of travel is
3 ^ 4 ^ 5 ^
given by the unit vector 5√ 2
i + 5√ 2
j + 5√ 2
k.

Fields

In general, a f ield is a vector or scalar quantity that can be specified everywhere in space as
a function of position (Note that in general a field may also be dependent on time and other
custom variables). In this module, we deal with 3-dimensional spaces only. Hence, a field is
defined as a function of the x, y and z coordinates corresponding to a location in 3D space.
For example, temperate in 3 dimensional space (a temperature field) can be written as T (x, y, z)
– a scalar function of the position. An example of a scalar field in electromagnetism is the
electric potential.
In a similar manner, a vector field can be defined as a vectorial function of the location (x, y, z)
of any point in space.
For instance, every point on the earth may be considered to be in the gravitational force field
of the earth. We may specify the field by the magnitude and the direction of acceleration due
to gravity (i.e. force per unit mass ) g(x, y, z) at every point in space.
To give an example from electromagnetism, consider an electric potential of form 2x2 y, a
scalar field in 3D space. The corresponding conservative electric field can be computed as
the gradient of the electric potential function, and expressed as 4xy^i + 2x 2^
√ j. The magnitude of
this electric field can in turn be expressed as a scalar field of the form 4x4 + 16x2 y 2 .

Implementation of fields in sympy.physics.vector

In sympy.physics.vector, every ReferenceFrame instance is assigned basis vectors corre-

sponding to the X, Y and Z directions. These can be accessed using the attributes named x,
y and z respectively. Hence, to define a vector v of the form 3^
i + 4^
j + 5^
k with respect to a given
frame R, you would do

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> v = 3*R.x + 4*R.y + 5*R.z

Vector math and basic calculus operations with respect to vectors have already been elabo-
rated upon in other sections of this module’s documentation.
On the other hand, base scalars (or coordinate variables) are implemented as special SymPy
Symbol s assigned to every frame, one for each direction from X, Y and Z. For a frame R, the
X, Y and Z base scalar Symbol s can be accessed using the R[0], R[1] and R[2] expressions
respectively.

5.40. Physics Module 1589

SymPy Documentation, Release 1.3

Therefore, to generate the expression for the aforementioned electric potential field 2x2 y, you
would have to do

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> electric_potential = 2*R[0]**2*R[1]
>>> electric_potential
2*R_x**2*R_y

In string representation, R_x denotes the X base scalar assigned to ReferenceFrame R. Es-
sentially, R_x is the string representation of R[0].
Scalar fields can be treated just as any other SymPy expression, for any math/calculus func-
tionality. Hence, to differentiate the above electric potential with respect to x (i.e. R[0]), you
would have to use the diff method.

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> electric_potential = 2*R[0]**2*R[1]
>>> from sympy import diff
>>> diff(electric_potential, R[0])
4*R_x*R_y

Like vectors (and vector fields), scalar fields can also be re-expressed in other frames of
reference, apart from the one they were defined in – assuming that an orientation relationship
exists between the concerned frames. This can be done using the express method, in a way
similar to vectors - but with the variables parameter set to True.

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> electric_potential = 2*R[0]**2*R[1]
>>> from sympy.physics.vector import dynamicsymbols, express
>>> q = dynamicsymbols('q')
>>> R1 = R.orientnew('R1', rot_type = 'Axis', amounts = [q, R.z])
>>> express(electric_potential, R1, variables=True)
2*(R1_x*sin(q(t)) + R1_y*cos(q(t)))*(R1_x*cos(q(t)) - R1_y*sin(q(t)))**2

Moreover, considering scalars can also be functions of time just as vectors, differentiation
with respect to time is also possible. Depending on the Symbol s present in the expression
and the frame with respect to which the time differentiation is being done, the output will
change/remain the same.

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> electric_potential = 2*R[0]**2*R[1]
>>> q = dynamicsymbols('q')
>>> R1 = R.orientnew('R1', rot_type = 'Axis', amounts = [q, R.z])
>>> from sympy.physics.vector import time_derivative
>>> time_derivative(electric_potential, R)
0
>>> time_derivative(electric_potential, R1).simplify()
2*(R1_x*cos(q(t)) - R1_y*sin(q(t)))*(3*R1_x**2*cos(2*q(t))/2 -
R1_x**2/2 - 3*R1_x*R1_y*sin(2*q(t)) - 3*R1_y**2*cos(2*q(t))/2 -
R1_y**2/2)*Derivative(q(t), t)

1590 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Field operators and other related functions

Here we describe some basic field-related functionality implemented in sympy.physics.vector

Curl

A curl is a mathematical operator that describes an infinitesimal rotation of a vector in 3D

space. The direction is determined by the right-hand rule (along the axis of rotation), and the
magnitude is given by the magnitude of rotation.
In the 3D Cartesian system, the curl of a 3D vector F , denoted by ∇ × F is given by -
( ) ( )
∂Fy ^ ( ∂Fx )
∂Fz ^ ∂Fy ∂Fx ^
∇ × F = ∂F∂y
z
− ∂z i + ∂z − ∂x j + ∂x − ∂y k

where Fx denotes the X component of vector F.

To compute the curl of a vector field in physics.vector, you would do

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> from sympy.physics.vector import curl
>>> field = R[0]*R[1]*R[2]*R.x
>>> curl(field, R)
R_x*R_y*R.y - R_x*R_z*R.z

Divergence

Divergence is a vector operator that measures the magnitude of a vector field’s source or sink
at a given point, in terms of a signed scalar.
The divergence operator always returns a scalar after operating on a vector.
In the 3D Cartesian system, the divergence of a 3D vector F, denoted by ∇ · F is given by -
∇·F= ∂U
∂x + ∂V
∂y + ∂W
∂z

where U , V and W denote the X, Y and Z components of F respectively.

To compute the divergence of a vector field in physics.vector, you would do

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> from sympy.physics.vector import divergence
>>> field = R[0]*R[1]*R[2] * (R.x+R.y+R.z)
>>> divergence(field, R)
R_x*R_y + R_x*R_z + R_y*R_z

Gradient

Consider a scalar field f (x, y, z) in 3D space. The gradient of this field is defined as the vector of
the 3 partial derivatives of f with respect to x, y and z in the X, Y and Z directions respectively.
In the 3D Cartesian system, the gradient of a scalar field f , denoted by ∇f is given by -
∂f^ ∂f^ ∂f ^
∇f = ∂x i + ∂y j + ∂z k

5.40. Physics Module 1591

SymPy Documentation, Release 1.3

To compute the gradient of a scalar field in physics.vector, you would do

>>> from sympy.physics.vector import ReferenceFrame

>>> R = ReferenceFrame('R')
>>> from sympy.physics.vector import gradient
>>> scalar_field = R[0]*R[1]*R[2]
>>> gradient(scalar_field, R)
R_y*R_z*R.x + R_x*R_z*R.y + R_x*R_y*R.z

Conservative and Solenoidal fields

In vector calculus, a conservative field is a field that is the gradient of some scalar field.
Conservative fields have the property that their line integral over any path depends only on
the end-points, and is independent of the path between them. A conservative vector field is
also said to be ‘irrotational’, since the curl of a conservative field is always zero.
In physics, conservative fields represent forces in physical systems where energy is con-
served.
To check if a vector field is conservative in physics.vector, use the is_conservative func-
tion.

>>> from sympy.physics.vector import ReferenceFrame, is_conservative

>>> R = ReferenceFrame('R')
>>> field = R[1]*R[2]*R.x + R[0]*R[2]*R.y + R[0]*R[1]*R.z
>>> is_conservative(field)
True
>>> curl(field, R)
0

A solenoidal field, on the other hand, is a vector field whose divergence is zero at all points
in space.
To check if a vector field is solenoidal in physics.vector, use the is_solenoidal function.

>>> from sympy.physics.vector import ReferenceFrame, is_solenoidal

>>> R = ReferenceFrame('R')
>>> field = R[1]*R[2]*R.x + R[0]*R[2]*R.y + R[0]*R[1]*R.z
>>> is_solenoidal(field)
True
>>> divergence(field, R)
0

Scalar potential functions

We have previously mentioned that every conservative field can be defined as the gradient of
some scalar field. This scalar field is also called the ‘scalar potential field’ corresponding to
the aforementioned conservative field.
The scalar_potential function in physics.vector calculates the scalar potential field cor-
responding to a given conservative vector field in 3D space - minus the extra constant of
integration, of course.
Example of usage -

1592 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.vector import ReferenceFrame, scalar_potential

>>> R = ReferenceFrame('R')
>>> conservative_field = 4*R[0]*R[1]*R[2]*R.x + 2*R[0]**2*R[2]*R.y + 2*R[0]**2*R[1]*R.
,→z

>>> scalar_potential(conservative_field, R)
2*R_x**2*R_y*R_z

Providing a non-conservative vector field as an argument to scalar_potential raises a Val-

ueError.
The scalar potential difference, or simply ‘potential difference’, corresponding to a conser-
vative vector field can be defined as the difference between the values of its scalar potential
function at two points in space. This is useful in calculating a line integral with respect to a
conservative function, since it depends only on the endpoints of the path.
This computation is performed as follows in physics.vector.

>>> from sympy.physics.vector import ReferenceFrame, Point

>>> from sympy.physics.vector import scalar_potential_difference
>>> R = ReferenceFrame('R')
>>> O = Point('O')
>>> P = O.locatenew('P', 1*R.x + 2*R.y + 3*R.z)
>>> vectfield = 4*R[0]*R[1]*R.x + 2*R[0]**2*R.y
>>> scalar_potential_difference(vectfield, R, O, P, O)
4

If provided with a scalar expression instead of a vector field, scalar_potential_difference

returns the difference between the values of that scalar field at the two given points in space.

Vector API

Essential Classes

CoordinateSym

class sympy.physics.vector.frame.CoordinateSym
A coordinate symbol/base scalar associated wrt a Reference Frame.
Ideally, users should not instantiate this class. Instances of this class must only be ac-
cessed through the corresponding frame as ‘frame[index]’.
CoordinateSyms having the same frame and index parameters are equal (even though
they may be instantiated separately).
Parameters name : string
The display name of the CoordinateSym
frame : ReferenceFrame
The reference frame this base scalar belongs to
index : 0, 1 or 2
The index of the dimension denoted by this coordinate variable

5.40. Physics Module 1593

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import ReferenceFrame, CoordinateSym

>>> A = ReferenceFrame('A')
>>> A[1]
A_y
>>> type(A[0])
<class 'sympy.physics.vector.frame.CoordinateSym'>
>>> a_y = CoordinateSym('a_y', A, 1)
>>> a_y == A[1]
True

ReferenceFrame

class sympy.physics.vector.frame.ReferenceFrame(name, indices=None, la-

texs=None, variables=None)
A reference frame in classical mechanics.
ReferenceFrame is a class used to represent a reference frame in classical mechanics.
It has a standard basis of three unit vectors in the frame’s x, y, and z directions.
It also can have a rotation relative to a parent frame; this rotation is defined by a direction
cosine matrix relating this frame’s basis vectors to the parent frame’s basis vectors. It
can also have an angular velocity vector, defined in another frame.
ang_acc_in(otherframe)
Returns the angular acceleration Vector of the ReferenceFrame.
Effectively returns the Vector: ^N alpha ^B which represent the angular accelera-
tion of B in N, where B is self, and N is otherframe.
Parameters otherframe : ReferenceFrame
The ReferenceFrame which the angular acceleration is returned in.

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> V = 10 * N.x
>>> A.set_ang_acc(N, V)
>>> A.ang_acc_in(N)
10*N.x

ang_vel_in(otherframe)
Returns the angular velocity Vector of the ReferenceFrame.
Effectively returns the Vector: ^N omega ^B which represent the angular velocity
of B in N, where B is self, and N is otherframe.
Parameters otherframe : ReferenceFrame
The ReferenceFrame which the angular velocity is returned in.

1594 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> V = 10 * N.x
>>> A.set_ang_vel(N, V)
>>> A.ang_vel_in(N)
10*N.x

dcm(otherframe)
The direction cosine matrix between frames.
This gives the DCM between this frame and the otherframe. The format is N.xyz =
N.dcm(B) * B.xyz A SymPy Matrix is returned.
Parameters otherframe : ReferenceFrame
The otherframe which the DCM is generated to.

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = ReferenceFrame('N')
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> N.dcm(A)
Matrix([
[1, 0, 0],
[0, cos(q1), -sin(q1)],
[0, sin(q1), cos(q1)]])

orient(parent, rot_type, amounts, rot_order=”)

Defines the orientation of this frame relative to a parent frame.
Parameters parent : ReferenceFrame
The frame that this ReferenceFrame will have its orientation matrix
defined in relation to.
rot_type : str
The type of orientation matrix that is being created. Supported types
are ‘Body’, ‘Space’, ‘Quaternion’, ‘Axis’, and ‘DCM’. See examples for
correct usage.
amounts : list OR value
The quantities that the orientation matrix will be defined by. In case of
rot_type=’DCM’, value must be a sympy.matrices.MatrixBase object
(or subclasses of it).
rot_order : str
If applicable, the order of a series of rotations.

5.40. Physics Module 1595

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> from sympy import symbols, eye, ImmutableMatrix
>>> q0, q1, q2, q3 = symbols('q0 q1 q2 q3')
>>> N = ReferenceFrame('N')
>>> B = ReferenceFrame('B')

Now we have a choice of how to implement the orientation. First is Body. Body
orientation takes this reference frame through three successive simple rotations.
Acceptable rotation orders are of length 3, expressed in XYZ or 123, and cannot
have a rotation about about an axis twice in a row.

>>> B.orient(N, 'Body', [q1, q2, q3], '123')

>>> B.orient(N, 'Body', [q1, q2, 0], 'ZXZ')
>>> B.orient(N, 'Body', [0, 0, 0], 'XYX')

Next is Space. Space is like Body, but the rotations are applied in the opposite order.

>>> B.orient(N, 'Space', [q1, q2, q3], '312')

Next is Quaternion. This orients the new ReferenceFrame with Quaternions, defined
as a finite rotation about lambda, a unit vector, by some amount theta. This orienta-
tion is described by four parameters: q0 = cos(theta/2) q1 = lambda_x sin(theta/2)
q2 = lambda_y sin(theta/2) q3 = lambda_z sin(theta/2) Quaternion does not take in
a rotation order.

>>> B.orient(N, 'Quaternion', [q0, q1, q2, q3])

Next is Axis. This is a rotation about an arbitrary, non-time-varying axis by some

angle. The axis is supplied as a Vector. This is how simple rotations are defined.

>>> B.orient(N, 'Axis', [q1, N.x + 2 * N.y])

Last is DCM (Direction Cosine Matrix). This is a rotation matrix given manually.

>>> B.orient(N, 'DCM', eye(3))

>>> B.orient(N, 'DCM', ImmutableMatrix([[0, 1, 0], [0, 0, -1], [-1, 0, 0]]))

orientnew(newname, rot_type, amounts, rot_order=”, variables=None, in-

dices=None, latexs=None)
Creates a new ReferenceFrame oriented with respect to this Frame.
See ReferenceFrame.orient() for acceptable rotation types, amounts, and orders.
Parent is going to be self.
Parameters newname : str
The name for the new ReferenceFrame
rot_type : str
The type of orientation matrix that is being created.
amounts : list OR value
The quantities that the orientation matrix will be defined by.
rot_order : str

1596 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If applicable, the order of a series of rotations.

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> from sympy import symbols
>>> q0, q1, q2, q3 = symbols('q0 q1 q2 q3')
>>> N = ReferenceFrame('N')

Now we have a choice of how to implement the orientation. First is Body. Body
orientation takes this reference frame through three successive simple rotations.
Acceptable rotation orders are of length 3, expressed in XYZ or 123, and cannot
have a rotation about about an axis twice in a row.

>>> A = N.orientnew('A', 'Body', [q1, q2, q3], '123')

>>> A = N.orientnew('A', 'Body', [q1, q2, 0], 'ZXZ')
>>> A = N.orientnew('A', 'Body', [0, 0, 0], 'XYX')

Next is Space. Space is like Body, but the rotations are applied in the opposite order.

>>> A = N.orientnew('A', 'Space', [q1, q2, q3], '312')

Next is Quaternion. This orients the new ReferenceFrame with Quaternions, defined
as a finite rotation about lambda, a unit vector, by some amount theta. This orienta-
tion is described by four parameters: q0 = cos(theta/2) q1 = lambda_x sin(theta/2)
q2 = lambda_y sin(theta/2) q3 = lambda_z sin(theta/2) Quaternion does not take in
a rotation order.

>>> A = N.orientnew('A', 'Quaternion', [q0, q1, q2, q3])

Last is Axis. This is a rotation about an arbitrary, non-time-varying axis by some

angle. The axis is supplied as a Vector. This is how simple rotations are defined.

>>> A = N.orientnew('A', 'Axis', [q1, N.x])

partial_velocity(frame, *gen_speeds)
Returns the partial angular velocities of this frame in the given frame with respect
to one or more provided generalized speeds.
Parameters frame : ReferenceFrame
The frame with which the angular velocity is defined in.
gen_speeds : functions of time
The generalized speeds.
Returns partial_velocities : tuple of Vector
The partial angular velocity vectors corresponding to the provided
generalized speeds.

Examples

5.40. Physics Module 1597

SymPy Documentation, Release 1.3

>>> from sympy.physics.vector import ReferenceFrame, dynamicsymbols

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> u1, u2 = dynamicsymbols('u1, u2')
>>> A.set_ang_vel(N, u1 * A.x + u2 * N.y)
>>> A.partial_velocity(N, u1)
A.x
>>> A.partial_velocity(N, u1, u2)
(A.x, N.y)

set_ang_acc(otherframe, value)
Define the angular acceleration Vector in a ReferenceFrame.
Defines the angular acceleration of this ReferenceFrame, in another. Angular ac-
celeration can be defined with respect to multiple different ReferenceFrames. Care
must be taken to not create loops which are inconsistent.
Parameters otherframe : ReferenceFrame
A ReferenceFrame to define the angular acceleration in
value : Vector
The Vector representing angular acceleration

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> V = 10 * N.x
>>> A.set_ang_acc(N, V)
>>> A.ang_acc_in(N)
10*N.x

set_ang_vel(otherframe, value)
Define the angular velocity vector in a ReferenceFrame.
Defines the angular velocity of this ReferenceFrame, in another. Angular velocity
can be defined with respect to multiple different ReferenceFrames. Care must be
taken to not create loops which are inconsistent.
Parameters otherframe : ReferenceFrame
A ReferenceFrame to define the angular velocity in
value : Vector
The Vector representing angular velocity

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> V = 10 * N.x
(continues on next page)

1598 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> A.set_ang_vel(N, V)
>>> A.ang_vel_in(N)
10*N.x

variable_map(otherframe)
Returns a dictionary which expresses the coordinate variables of this frame in terms
of the variables of otherframe.
If Vector.simp is True, returns a simplified version of the mapped values. Else, re-
turns them without simplification.
Simplification of the expressions may take time.
Parameters otherframe : ReferenceFrame
The other frame to map the variables to

Examples

>>> from sympy.physics.vector import ReferenceFrame, dynamicsymbols

>>> A = ReferenceFrame('A')
>>> q = dynamicsymbols('q')
>>> B = A.orientnew('B', 'Axis', [q, A.z])
>>> A.variable_map(B)
{A_x: B_x*cos(q(t)) - B_y*sin(q(t)), A_y: B_x*sin(q(t)) + B_y*cos(q(t)), A_z:␣
,→B_z}

x
The basis Vector for the ReferenceFrame, in the x direction.
y
The basis Vector for the ReferenceFrame, in the y direction.
z
The basis Vector for the ReferenceFrame, in the z direction.

Vector

class sympy.physics.vector.vector.Vector(inlist)
The class used to define vectors.
It along with ReferenceFrame are the building blocks of describing a classical mechanics
system in PyDy and sympy.physics.vector.

Attributes

simp (Boolean) Let certain methods use trigsimp on their outputs

applyfunc(f)
Apply a function to each component of a vector.

5.40. Physics Module 1599

SymPy Documentation, Release 1.3

cross(other)
The cross product operator for two Vectors.
Returns a Vector, expressed in the same ReferenceFrames as self.
Parameters other : Vector
The Vector which we are crossing with

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = ReferenceFrame('N')
>>> N.x ^ N.y
N.z
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> A.x ^ N.y
N.z
>>> N.y ^ A.x
- sin(q1)*A.y - cos(q1)*A.z

diff(var, frame, var_in_dcm=True)

Returns the partial derivative of the vector with respect to a variable in the provided
reference frame.
Parameters var : Symbol
What the partial derivative is taken with respect to.
frame : ReferenceFrame
The reference frame that the partial derivative is taken in.
var_in_dcm : boolean
If true, the differentiation algorithm assumes that the variable may be
present in any of the direction cosine matrices that relate the frame
to the frames of any component of the vector. But if it is known that
the variable is not present in the direction cosine matrices, false can
be set to skip full reexpression in the desired frame.

Examples

>>> from sympy import Symbol

>>> from sympy.physics.vector import dynamicsymbols, ReferenceFrame
>>> from sympy.physics.vector import Vector
>>> Vector.simp = True
>>> t = Symbol('t')
>>> q1 = dynamicsymbols('q1')
>>> N = ReferenceFrame('N')
>>> A = N.orientnew('A', 'Axis', [q1, N.y])
>>> A.x.diff(t, N)
- q1'*A.z
>>> B = ReferenceFrame('B')
>>> u1, u2 = dynamicsymbols('u1, u2')
(continues on next page)

1600 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> v = u1 * A.x + u2 * B.y
>>> v.diff(u2, N, var_in_dcm=False)
B.y

doit(**hints)
Calls .doit() on each term in the Vector
dot(other)
Dot product of two vectors.
Returns a scalar, the dot product of the two Vectors
Parameters other : Vector
The Vector which we are dotting with

Examples

>>> from sympy.physics.vector import ReferenceFrame, dot

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = ReferenceFrame('N')
>>> dot(N.x, N.x)
1
>>> dot(N.x, N.y)
0
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> dot(N.y, A.y)
cos(q1)

dt(otherframe)
Returns a Vector which is the time derivative of the self Vector, taken in frame oth-
erframe.
Calls the global time_derivative method
Parameters otherframe : ReferenceFrame
The frame to calculate the time derivative in
express(otherframe, variables=False)
Returns a Vector equivalent to this one, expressed in otherframe. Uses the global
express method.
Parameters otherframe : ReferenceFrame
The frame for this Vector to be described in
variables : boolean
If True, the coordinate symbols(if present) in this Vector are re-
expressed in terms otherframe

Examples

5.40. Physics Module 1601

SymPy Documentation, Release 1.3

>>> from sympy.physics.vector import ReferenceFrame, Vector, dynamicsymbols

>>> q1 = dynamicsymbols('q1')
>>> N = ReferenceFrame('N')
>>> A = N.orientnew('A', 'Axis', [q1, N.y])
>>> A.x.express(N)
cos(q1)*N.x - sin(q1)*N.z

free_symbols(reference_frame)
Returns the free symbols in the measure numbers of the vector expressed in the
given reference frame.

Parameter

reference_frame [ReferenceFrame] The frame with respect to which the free sym-
bols of the given vector is to be determined.

magnitude()
Returns the magnitude (Euclidean norm) of self.
normalize()
Returns a Vector of magnitude 1, codirectional with self.
outer(other)
Outer product between two Vectors.
A rank increasing operation, which returns a Dyadic from two Vectors
Parameters other : Vector
The Vector to take the outer product with

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer

>>> N = ReferenceFrame('N')
>>> outer(N.x, N.x)
(N.x|N.x)

separate()
The constituents of this vector in different reference frames, as per its definition.
Returns a dict mapping each ReferenceFrame to the corresponding constituent Vec-
tor.

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> R1 = ReferenceFrame('R1')
>>> R2 = ReferenceFrame('R2')
>>> v = R1.x + R2.x
>>> v.separate() == {R1: R1.x, R2: R2.x}
True

1602 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

simplify()
Returns a simplified Vector.
subs(*args, **kwargs)
Substitution on the Vector.

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy import Symbol
>>> N = ReferenceFrame('N')
>>> s = Symbol('s')
>>> a = N.x * s
>>> a.subs({s: 2})
2*N.x

to_matrix(reference_frame)
Returns the matrix form of the vector with respect to the given frame.
Parameters reference_frame : ReferenceFrame
The reference frame that the rows of the matrix correspond to.
Returns matrix : ImmutableMatrix, shape(3,1)
The matrix that gives the 1D vector.

Examples

>>> from sympy import symbols

>>> from sympy.physics.vector import ReferenceFrame
>>> from sympy.physics.mechanics.functions import inertia
>>> a, b, c = symbols('a, b, c')
>>> N = ReferenceFrame('N')
>>> vector = a * N.x + b * N.y + c * N.z
>>> vector.to_matrix(N)
Matrix([
[a],
[b],
[c]])
>>> beta = symbols('beta')
>>> A = N.orientnew('A', 'Axis', (beta, N.x))
>>> vector.to_matrix(A)
Matrix([
[ a],
[ b*cos(beta) + c*sin(beta)],
[-b*sin(beta) + c*cos(beta)]])

Dyadic

class sympy.physics.vector.dyadic.Dyadic(inlist)
A Dyadic object.
See: http://en.wikipedia.org/wiki/Dyadic_tensor Kane, T., Levinson, D. Dynamics Theory
and Applications. 1985 McGraw-Hill

5.40. Physics Module 1603

SymPy Documentation, Release 1.3

A more powerful way to represent a rigid body’s inertia. While it is more complex, by
choosing Dyadic components to be in body fixed basis vectors, the resulting matrix is
equivalent to the inertia tensor.
applyfunc(f)
Apply a function to each component of a Dyadic.
cross(other)
For a cross product in the form: Dyadic x Vector.
Parameters other : Vector
The Vector that we are crossing this Dyadic with

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer, cross

>>> N = ReferenceFrame('N')
>>> d = outer(N.x, N.x)
>>> cross(d, N.y)
(N.x|N.z)

doit(**hints)
Calls .doit() on each term in the Dyadic
dot(other)
The inner product operator for a Dyadic and a Dyadic or Vector.
Parameters other : Dyadic or Vector
The other Dyadic or Vector to take the inner product with

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer

>>> N = ReferenceFrame('N')
>>> D1 = outer(N.x, N.y)
>>> D2 = outer(N.y, N.y)
>>> D1.dot(D2)
(N.x|N.y)
>>> D1.dot(N.y)
N.x

dt(frame)
Take the time derivative of this Dyadic in a frame.
This function calls the global time_derivative method
Parameters frame : ReferenceFrame
The frame to take the time derivative in

Examples

1604 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.vector import ReferenceFrame, outer, dynamicsymbols

>>> N = ReferenceFrame('N')
>>> q = dynamicsymbols('q')
>>> B = N.orientnew('B', 'Axis', [q, N.z])
>>> d = outer(N.x, N.x)
>>> d.dt(B)
- q'*(N.y|N.x) - q'*(N.x|N.y)

express(frame1, frame2=None)
Expresses this Dyadic in alternate frame(s)
The first frame is the list side expression, the second frame is the right side; if Dyadic
is in form A.x|B.y, you can express it in two different frames. If no second frame is
given, the Dyadic is expressed in only one frame.
Calls the global express function
Parameters frame1 : ReferenceFrame
The frame to express the left side of the Dyadic in
frame2 : ReferenceFrame
If provided, the frame to express the right side of the Dyadic in

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer, dynamicsymbols

>>> N = ReferenceFrame('N')
>>> q = dynamicsymbols('q')
>>> B = N.orientnew('B', 'Axis', [q, N.z])
>>> d = outer(N.x, N.x)
>>> d.express(B, N)
cos(q)*(B.x|N.x) - sin(q)*(B.y|N.x)

simplify()
Returns a simplified Dyadic.
subs(*args, **kwargs)
Substitution on the Dyadic.

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy import Symbol
>>> N = ReferenceFrame('N')
>>> s = Symbol('s')
>>> a = s * (N.x|N.x)
>>> a.subs({s: 2})
2*(N.x|N.x)

to_matrix(reference_frame, second_reference_frame=None)
Returns the matrix form of the dyadic with respect to one or two reference frames.
Parameters reference_frame : ReferenceFrame

5.40. Physics Module 1605

SymPy Documentation, Release 1.3

The reference frame that the rows and columns of the matrix corre-
spond to. If a second reference frame is provided, this only corre-
sponds to the rows of the matrix.
second_reference_frame : ReferenceFrame, optional, default=None
The reference frame that the columns of the matrix correspond to.
Returns matrix : ImmutableMatrix, shape(3,3)
The matrix that gives the 2D tensor form.

Examples

>>> from sympy import symbols

>>> from sympy.physics.vector import ReferenceFrame, Vector
>>> Vector.simp = True
>>> from sympy.physics.mechanics import inertia
>>> Ixx, Iyy, Izz, Ixy, Iyz, Ixz = symbols('Ixx, Iyy, Izz, Ixy, Iyz, Ixz')
>>> N = ReferenceFrame('N')
>>> inertia_dyadic = inertia(N, Ixx, Iyy, Izz, Ixy, Iyz, Ixz)
>>> inertia_dyadic.to_matrix(N)
Matrix([
[Ixx, Ixy, Ixz],
[Ixy, Iyy, Iyz],
[Ixz, Iyz, Izz]])
>>> beta = symbols('beta')
>>> A = N.orientnew('A', 'Axis', (beta, N.x))
>>> inertia_dyadic.to_matrix(A)
Matrix([
[ Ixx, ␣
,→Ixy*cos(beta) + Ixz*sin(beta), -
,→Ixy*sin(beta) + Ixz*cos(beta)],

[ Ixy*cos(beta) + Ixz*sin(beta), Iyy*cos(2*beta)/2 + Iyy/2 + Iyz*sin(2*beta) -

,→ Izz*cos(2*beta)/2 + Izz/2, -Iyy*sin(2*beta)/2 +␣
,→Iyz*cos(2*beta) + Izz*sin(2*beta)/2],

[-Ixy*sin(beta) + Ixz*cos(beta), -Iyy*sin(2*beta)/2 +␣

,→Iyz*cos(2*beta) + Izz*sin(2*beta)/2, -Iyy*cos(2*beta)/2 + Iyy/2 -␣

,→Iyz*sin(2*beta) + Izz*cos(2*beta)/2 + Izz/2]])

Kinematics (Docstrings)

Point

class sympy.physics.vector.point.Point(name)
This object represents a point in a dynamic system.
It stores the: position, velocity, and acceleration of a point. The position is a vector
defined as the vector distance from a parent point to this point.
a1pt_theory(otherpoint, outframe, interframe)
Sets the acceleration of this point with the 1-point theory.
The 1-point theory for point acceleration looks like this:
^N a^P = ^B a^P + ^N a^O + ^N alpha^B x r^OP + ^N omega^B x (^N
omega^B x r^OP) + 2 ^N omega^B x ^B v^P

1606 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

where O is a point fixed in B, P is a point moving in B, and B is rotating in frame N.

Parameters otherpoint : Point
The first point of the 1-point theory (O)
outframe : ReferenceFrame
The frame we want this point’s acceleration defined in (N)
fixedframe : ReferenceFrame
The intermediate frame in this calculation (B)

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> from sympy.physics.vector import Vector, dynamicsymbols
>>> q = dynamicsymbols('q')
>>> q2 = dynamicsymbols('q2')
>>> qd = dynamicsymbols('q', 1)
>>> q2d = dynamicsymbols('q2', 1)
>>> N = ReferenceFrame('N')
>>> B = ReferenceFrame('B')
>>> B.set_ang_vel(N, 5 * B.y)
>>> O = Point('O')
>>> P = O.locatenew('P', q * B.x)
>>> P.set_vel(B, qd * B.x + q2d * B.y)
>>> O.set_vel(N, 0)
>>> P.a1pt_theory(O, N, B)
(-25*q + q'')*B.x + q2''*B.y - 10*q'*B.z

a2pt_theory(otherpoint, outframe, fixedframe)

Sets the acceleration of this point with the 2-point theory.
The 2-point theory for point acceleration looks like this:
^N a^P = ^N a^O + ^N alpha^B x r^OP + ^N omega^B x (^N omega^B x r^OP)
where O and P are both points fixed in frame B, which is rotating in frame N.
Parameters otherpoint : Point
The first point of the 2-point theory (O)
outframe : ReferenceFrame
The frame we want this point’s acceleration defined in (N)
fixedframe : ReferenceFrame
The frame in which both points are fixed (B)

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame, dynamicsymbols

>>> q = dynamicsymbols('q')
>>> qd = dynamicsymbols('q', 1)
>>> N = ReferenceFrame('N')
(continues on next page)

5.40. Physics Module 1607

SymPy Documentation, Release 1.3

(continued from previous page)

>>> B = N.orientnew('B', 'Axis', [q, N.z])
>>> O = Point('O')
>>> P = O.locatenew('P', 10 * B.x)
>>> O.set_vel(N, 5 * N.x)
>>> P.a2pt_theory(O, N, B)
- 10*q'**2*B.x + 10*q''*B.y

acc(frame)
The acceleration Vector of this Point in a ReferenceFrame.
Parameters frame : ReferenceFrame
The frame in which the returned acceleration vector will be defined
in

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p1.set_acc(N, 10 * N.x)
>>> p1.acc(N)
10*N.x

locatenew(name, value)
Creates a new point with a position defined from this point.
Parameters name : str
The name for the new point
value : Vector
The position of the new point relative to this point

Examples

>>> from sympy.physics.vector import ReferenceFrame, Point

>>> N = ReferenceFrame('N')
>>> P1 = Point('P1')
>>> P2 = P1.locatenew('P2', 10 * N.x)

partial_velocity(frame, *gen_speeds)
Returns the partial velocities of the linear velocity vector of this point in the given
frame with respect to one or more provided generalized speeds.
Parameters frame : ReferenceFrame
The frame with which the velocity is defined in.
gen_speeds : functions of time
The generalized speeds.
Returns partial_velocities : tuple of Vector

1608 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The partial velocity vectors corresponding to the provided general-

ized speeds.

Examples

>>> from sympy.physics.vector import ReferenceFrame, Point

>>> from sympy.physics.vector import dynamicsymbols
>>> N = ReferenceFrame('N')
>>> A = ReferenceFrame('A')
>>> p = Point('p')
>>> u1, u2 = dynamicsymbols('u1, u2')
>>> p.set_vel(N, u1 * N.x + u2 * A.y)
>>> p.partial_velocity(N, u1)
N.x
>>> p.partial_velocity(N, u1, u2)
(N.x, A.y)

pos_from(otherpoint)
Returns a Vector distance between this Point and the other Point.
Parameters otherpoint : Point
The otherpoint we are locating this one relative to

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p2 = Point('p2')
>>> p1.set_pos(p2, 10 * N.x)
>>> p1.pos_from(p2)
10*N.x

set_acc(frame, value)
Used to set the acceleration of this Point in a ReferenceFrame.
Parameters frame : ReferenceFrame
The frame in which this point’s acceleration is defined
value : Vector
The vector value of this point’s acceleration in the frame

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p1.set_acc(N, 10 * N.x)
>>> p1.acc(N)
10*N.x

5.40. Physics Module 1609

SymPy Documentation, Release 1.3

set_pos(otherpoint, value)
Used to set the position of this point w.r.t. another point.
Parameters otherpoint : Point
The other point which this point’s location is defined relative to
value : Vector
The vector which defines the location of this point

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p2 = Point('p2')
>>> p1.set_pos(p2, 10 * N.x)
>>> p1.pos_from(p2)
10*N.x

set_vel(frame, value)
Sets the velocity Vector of this Point in a ReferenceFrame.
Parameters frame : ReferenceFrame
The frame in which this point’s velocity is defined
value : Vector
The vector value of this point’s velocity in the frame

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p1.set_vel(N, 10 * N.x)
>>> p1.vel(N)
10*N.x

v1pt_theory(otherpoint, outframe, interframe)

Sets the velocity of this point with the 1-point theory.
The 1-point theory for point velocity looks like this:
^N v^P = ^B v^P + ^N v^O + ^N omega^B x r^OP
where O is a point fixed in B, P is a point moving in B, and B is rotating in frame N.
Parameters otherpoint : Point
The first point of the 2-point theory (O)
outframe : ReferenceFrame
The frame we want this point’s velocity defined in (N)
interframe : ReferenceFrame
The intermediate frame in this calculation (B)

1610 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> from sympy.physics.vector import Vector, dynamicsymbols
>>> q = dynamicsymbols('q')
>>> q2 = dynamicsymbols('q2')
>>> qd = dynamicsymbols('q', 1)
>>> q2d = dynamicsymbols('q2', 1)
>>> N = ReferenceFrame('N')
>>> B = ReferenceFrame('B')
>>> B.set_ang_vel(N, 5 * B.y)
>>> O = Point('O')
>>> P = O.locatenew('P', q * B.x)
>>> P.set_vel(B, qd * B.x + q2d * B.y)
>>> O.set_vel(N, 0)
>>> P.v1pt_theory(O, N, B)
q'*B.x + q2'*B.y - 5*q*B.z

v2pt_theory(otherpoint, outframe, fixedframe)

Sets the velocity of this point with the 2-point theory.
The 2-point theory for point velocity looks like this:
^N v^P = ^N v^O + ^N omega^B x r^OP
where O and P are both points fixed in frame B, which is rotating in frame N.
Parameters otherpoint : Point
The first point of the 2-point theory (O)
outframe : ReferenceFrame
The frame we want this point’s velocity defined in (N)
fixedframe : ReferenceFrame
The frame in which both points are fixed (B)

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame, dynamicsymbols

>>> q = dynamicsymbols('q')
>>> qd = dynamicsymbols('q', 1)
>>> N = ReferenceFrame('N')
>>> B = N.orientnew('B', 'Axis', [q, N.z])
>>> O = Point('O')
>>> P = O.locatenew('P', 10 * B.x)
>>> O.set_vel(N, 5 * N.x)
>>> P.v2pt_theory(O, N, B)
5*N.x + 10*q'*B.y

vel(frame)
The velocity Vector of this Point in the ReferenceFrame.
Parameters frame : ReferenceFrame
The frame in which the returned velocity vector will be defined in

5.40. Physics Module 1611

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> N = ReferenceFrame('N')
>>> p1 = Point('p1')
>>> p1.set_vel(N, 10 * N.x)
>>> p1.vel(N)
10*N.x

kinematic_equations

sympy.physics.vector.functions.kinematic_equations(speeds, coords, rot_type,

rot_order=”)
Gives equations relating the qdot’s to u’s for a rotation type.
Supply rotation type and order as in orient. Speeds are assumed to be body-fixed; if we
are defining the orientation of B in A using by rot_type, the angular velocity of B in A is
assumed to be in the form: speed[0]*B.x + speed[1]*B.y + speed[2]*B.z
Parameters speeds : list of length 3
The body fixed angular velocity measure numbers.
coords : list of length 3 or 4
The coordinates used to define the orientation of the two frames.
rot_type : str
The type of rotation used to create the equations. Body, Space, or
Quaternion only
rot_order : str
If applicable, the order of a series of rotations.

Examples

>>> from sympy.physics.vector import dynamicsymbols

>>> from sympy.physics.vector import kinematic_equations, vprint
>>> u1, u2, u3 = dynamicsymbols('u1 u2 u3')
>>> q1, q2, q3 = dynamicsymbols('q1 q2 q3')
>>> vprint(kinematic_equations([u1,u2,u3], [q1,q2,q3], 'body', '313'),
... order=None)
[-(u1*sin(q3) + u2*cos(q3))/sin(q2) + q1', -u1*cos(q3) + u2*sin(q3) + q2',␣
,→(u1*sin(q3) + u2*cos(q3))*cos(q2)/sin(q2) - u3 + q3']

sympy.physics.vector.functions.partial_velocity(vel_vecs, gen_speeds, frame)

Returns a list of partial velocities with respect to the provided generalized speeds in the
given reference frame for each of the supplied velocity vectors.
The output is a list of lists. The outer list has a number of elements equal to the number
of supplied velocity vectors. The inner lists are, for each velocity vector, the partial
derivatives of that velocity vector with respect to the generalized speeds supplied.
Parameters vel_vecs : iterable
An iterable of velocity vectors (angular or linear).

1612 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

gen_speeds : iterable
An iterable of generalized speeds.
frame : ReferenceFrame
The reference frame that the partial derivatives are going to be taken
in.

Examples

>>> from sympy.physics.vector import Point, ReferenceFrame

>>> from sympy.physics.vector import dynamicsymbols
>>> from sympy.physics.vector import partial_velocity
>>> u = dynamicsymbols('u')
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, u * N.x)
>>> vel_vecs = [P.vel(N)]
>>> gen_speeds = [u]
>>> partial_velocity(vel_vecs, gen_speeds, N)
[[N.x]]

sympy.physics.vector.functions.get_motion_params(frame, **kwargs)
Returns the three motion parameters - (acceleration, velocity, and position) as vectorial
functions of time in the given frame.
If a higher order differential function is provided, the lower order functions are used
as boundary conditions. For example, given the acceleration, the velocity and position
parameters are taken as boundary conditions.
The values of time at which the boundary conditions are specified are taken from
timevalue1(for position boundary condition) and timevalue2(for velocity boundary con-
dition).
If any of the boundary conditions are not provided, they are taken to be zero by default
(zero vectors, in case of vectorial inputs). If the boundary conditions are also functions
of time, they are converted to constants by substituting the time values in the dynamic-
symbols._t time Symbol.
This function can also be used for calculating rotational motion parameters. Have a look
at the Parameters and Examples for more clarity.
Parameters frame : ReferenceFrame
The frame to express the motion parameters in
acceleration : Vector
Acceleration of the object/frame as a function of time
velocity : Vector
Velocity as function of time or as boundary condition of velocity at
time = timevalue1
position : Vector
Velocity as function of time or as boundary condition of velocity at
time = timevalue1

5.40. Physics Module 1613

SymPy Documentation, Release 1.3

timevalue1 : sympyfiable
Value of time for position boundary condition
timevalue2 : sympyfiable
Value of time for velocity boundary condition

Examples

>>> from sympy.physics.vector import ReferenceFrame, get_motion_params,␣

,→dynamicsymbols

>>> from sympy import symbols

>>> R = ReferenceFrame('R')
>>> v1, v2, v3 = dynamicsymbols('v1 v2 v3')
>>> v = v1*R.x + v2*R.y + v3*R.z
>>> get_motion_params(R, position = v)
(v1''*R.x + v2''*R.y + v3''*R.z, v1'*R.x + v2'*R.y + v3'*R.z, v1*R.x + v2*R.y +␣
,→v3*R.z)

>>> a, b, c = symbols('a b c')

>>> v = a*R.x + b*R.y + c*R.z
>>> get_motion_params(R, velocity = v)
(0, a*R.x + b*R.y + c*R.z, a*t*R.x + b*t*R.y + c*t*R.z)
>>> parameters = get_motion_params(R, acceleration = v)
>>> parameters[1]
a*t*R.x + b*t*R.y + c*t*R.z
>>> parameters[2]
a*t**2/2*R.x + b*t**2/2*R.y + c*t**2/2*R.z

Printing (Docstrings)

init_printing

sympy.physics.vector.printing.init_printing(pretty_print=True, or-
der=None, use_unicode=None,
use_latex=None, wrap_line=None,
num_columns=None,
no_global=False, ip=None, eu-
ler=False, forecolor=’Black’,
backcolor=’Transparent’,
fontsize=’10pt’, la-
tex_mode=’equation*’,
print_builtin=True,
str_printer=None,
pretty_printer=None, la-
tex_printer=None, **settings)
Initializes pretty-printer depending on the environment.
Parameters pretty_print: boolean
If True, use pretty_print to stringify or the provided pretty printer; if
False, use sstrrepr to stringify or the provided string printer.
order: string or None

1614 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

There are a few different settings for this parameter: lex (default),
which is lexographic order; grlex, which is graded lexographic order;
grevlex, which is reversed graded lexographic order; old, which is
used for compatibility reasons and for long expressions; None, which
sets it to lex.
use_unicode: boolean or None
If True, use unicode characters; if False, do not use unicode charac-
ters.
use_latex: string, boolean, or None
If True, use default latex rendering in GUI interfaces (png and math-
jax); if False, do not use latex rendering; if ‘png’, enable latex ren-
dering with an external latex compiler, falling back to matplotlib if
external compilation fails; if ‘matplotlib’, enable latex rendering with
matplotlib; if ‘mathjax’, enable latex text generation, for example
MathJax rendering in IPython notebook or text rendering in LaTeX
documents
wrap_line: boolean
If True, lines will wrap at the end; if False, they will not wrap but
continue as one line. This is only relevant if prettyp rint is True.
num_columns: int or None
If int, number of columns before wrapping is set to num_columns; if
None, number of columns before wrapping is set to terminal width.
This is only relevant if prettyp rint is True.
no_global: boolean
If True, the settings become system wide; if False, use just for this
console/session.
ip: An interactive console
This can either be an instance of IPython, or a class that derives from
code.InteractiveConsole.
euler: boolean, optional, default=False
Loads the euler package in the LaTeX preamble for handwritten style
fonts (http://www.ctan.org/pkg/euler).
forecolor: string, optional, default=’Black’
DVI setting for foreground color.
backcolor: string, optional, default=’Transparent’
DVI setting for background color.
fontsize: string, optional, default=‘10pt’
A font size to pass to the LaTeX documentclass function in the pream-
ble.
latex_mode: string, optional, default=’equation*’
The mode used in the LaTeX printer. Can be one of: {‘in-
line’|’plain’|’equation’|’equation*’}.

5.40. Physics Module 1615

SymPy Documentation, Release 1.3

print_builtin: boolean, optional, default=True

If true then floats and integers will be printed. If false the printer will
only print SymPy types.
str_printer: function, optional, default=None
A custom string printer function. This should mimic
sympy.printing.sstrrepr().
pretty_printer: function, optional, default=None
A custom pretty printer. This should mimic sympy.printing.pretty().
latex_printer: function, optional, default=None
A custom LaTeX printer. This should mimic sympy.printing.latex().

Examples

>>> from sympy.interactive import init_printing

>>> from sympy import Symbol, sqrt
>>> from sympy.abc import x, y
>>> sqrt(5)
sqrt(5)
>>> init_printing(pretty_print=True) # doctest: +SKIP
>>> sqrt(5) # doctest: +SKIP
___
\/ 5
>>> theta = Symbol('theta') # doctest: +SKIP
>>> init_printing(use_unicode=True) # doctest: +SKIP
>>> theta # doctest: +SKIP
\u03b8
>>> init_printing(use_unicode=False) # doctest: +SKIP
>>> theta # doctest: +SKIP
theta
>>> init_printing(order='lex') # doctest: +SKIP
>>> str(y + x + y**2 + x**2) # doctest: +SKIP
x**2 + x + y**2 + y
>>> init_printing(order='grlex') # doctest: +SKIP
>>> str(y + x + y**2 + x**2) # doctest: +SKIP
x**2 + x + y**2 + y
>>> init_printing(order='grevlex') # doctest: +SKIP
>>> str(y * x**2 + x * y**2) # doctest: +SKIP
x**2*y + x*y**2
>>> init_printing(order='old') # doctest: +SKIP
>>> str(x**2 + y**2 + x + y) # doctest: +SKIP
x**2 + x + y**2 + y
>>> init_printing(num_columns=10) # doctest: +SKIP
>>> x**2 + x + y**2 + y # doctest: +SKIP
x + y +
x**2 + y**2

vprint

sympy.physics.vector.printing.vprint(expr, **settings)
Function for printing of expressions generated in the sympy.physics vector package.

1616 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Extends SymPy’s StrPrinter, takes the same setting accepted by SymPy’s sstr(), and is
equivalent to print(sstr(f oo)).
Parameters expr : valid SymPy object
SymPy expression to print.
settings : args
Same as the settings accepted by SymPy’s sstr().

Examples

>>> from sympy.physics.vector import vprint, dynamicsymbols

>>> u1 = dynamicsymbols('u1')
>>> print(u1)
u1(t)
>>> vprint(u1)
u1

vpprint

sympy.physics.vector.printing.vpprint(expr, **settings)
Function for pretty printing of expressions generated in the sympy.physics vector pack-
age.
Mainly used for expressions not inside a vector; the output of running scripts and gen-
erating equations of motion. Takes the same options as SymPy’s pretty_print(); see that
function for more information.
Parameters expr : valid SymPy object
SymPy expression to pretty print
settings : args
Same as those accepted by SymPy’s pretty_print.

vlatex

sympy.physics.vector.printing.vlatex(expr, **settings)
Function for printing latex representation of sympy.physics.vector objects.
For latex representation of Vectors, Dyadics, and dynamicsymbols. Takes the same op-
tions as SymPy’s latex(); see that function for more information;
Parameters expr : valid SymPy object
SymPy expression to represent in LaTeX form
settings : args
Same as latex()

5.40. Physics Module 1617

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.vector import vlatex, ReferenceFrame, dynamicsymbols

>>> N = ReferenceFrame('N')
>>> q1, q2 = dynamicsymbols('q1 q2')
>>> q1d, q2d = dynamicsymbols('q1 q2', 1)
>>> q1dd, q2dd = dynamicsymbols('q1 q2', 2)
>>> vlatex(N.x + N.y)
'\\mathbf{\\hat{n}_x} + \\mathbf{\\hat{n}_y}'
>>> vlatex(q1 + q2)
'q_{1} + q_{2}'
>>> vlatex(q1d)
'\\dot{q}_{1}'
>>> vlatex(q1 * q2d)
'q_{1} \\dot{q}_{2}'
>>> vlatex(q1dd * q1 / q1d)
'\\frac{q_{1} \\ddot{q}_{1}}{\\dot{q}_{1}}'

Essential Functions (Docstrings)

dynamicsymbols

sympy.physics.vector.dynamicsymbols(names, level=0)
Uses symbols and Function for functions of time.
Creates a SymPy UndefinedFunction, which is then initialized as a function of a variable,
the default being Symbol(‘t’).
Parameters names : str
Names of the dynamic symbols you want to create; works the same
way as inputs to symbols
level : int
Level of differentiation of the returned function; d/dt once of t, twice
of t, etc.

Examples

>>> from sympy.physics.vector import dynamicsymbols

>>> from sympy import diff, Symbol
>>> q1 = dynamicsymbols('q1')
>>> q1
q1(t)
>>> diff(q1, Symbol('t'))
Derivative(q1(t), t)

dot

sympy.physics.vector.functions.dot(vec1, vec2)
Dot product convenience wrapper for Vector.dot(): Dot product of two vectors.

1618 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Returns a scalar, the dot product of the two Vectors

Parameters other : Vector

The Vector which we are dotting with

Examples

>>> from sympy.physics.vector import ReferenceFrame, dot

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = ReferenceFrame('N')
>>> dot(N.x, N.x)
1
>>> dot(N.x, N.y)
0
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> dot(N.y, A.y)
cos(q1)

cross

sympy.physics.vector.functions.cross(vec1, vec2)
Cross product convenience wrapper for Vector.cross(): The cross product operator for
two Vectors.
Returns a Vector, expressed in the same ReferenceFrames as self.

Parameters other : Vector

The Vector which we are crossing with

Examples

>>> from sympy.physics.vector import ReferenceFrame, Vector

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = ReferenceFrame('N')
>>> N.x ^ N.y
N.z
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> A.x ^ N.y
N.z
>>> N.y ^ A.x
- sin(q1)*A.y - cos(q1)*A.z

outer

sympy.physics.vector.functions.outer(vec1, vec2)
Outer product convenience wrapper for Vector.outer(): Outer product between two Vec-
tors.

5.40. Physics Module 1619

SymPy Documentation, Release 1.3

A rank increasing operation, which returns a Dyadic from two Vectors

Parameters other : Vector

The Vector to take the outer product with

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer

>>> N = ReferenceFrame('N')
>>> outer(N.x, N.x)
(N.x|N.x)

express

sympy.physics.vector.functions.express(expr, frame, frame2=None, vari-

ables=False)
Global function for ‘express’ functionality.
Re-expresses a Vector, scalar(sympyfiable) or Dyadic in given frame.
Refer to the local methods of Vector and Dyadic for details. If ‘variables’ is True, then
the coordinate variables (CoordinateSym instances) of other frames present in the vec-
tor/scalar field or dyadic expression are also substituted in terms of the base scalars of
this frame.
Parameters expr : Vector/Dyadic/scalar(sympyfiable)
The expression to re-express in ReferenceFrame ‘frame’
frame: ReferenceFrame
The reference frame to express expr in
frame2 : ReferenceFrame
The other frame required for re-expression(only for Dyadic expr)
variables : boolean
Specifies whether to substitute the coordinate variables present in
expr, in terms of those of frame

Examples

>>> from sympy.physics.vector import ReferenceFrame, outer, dynamicsymbols

>>> N = ReferenceFrame('N')
>>> q = dynamicsymbols('q')
>>> B = N.orientnew('B', 'Axis', [q, N.z])
>>> d = outer(N.x, N.x)
>>> from sympy.physics.vector import express
>>> express(d, B, N)
cos(q)*(B.x|N.x) - sin(q)*(B.y|N.x)
>>> express(B.x, N)
cos(q)*N.x + sin(q)*N.y
(continues on next page)

1620 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> express(N[0], B, variables=True)
B_x*cos(q(t)) - B_y*sin(q(t))

time_derivative

sympy.physics.vector.functions.time_derivative(expr, frame, order=1)

Calculate the time derivative of a vector/scalar field function or dyadic expression in
given frame.
Parameters expr : Vector/Dyadic/sympifyable
The expression whose time derivative is to be calculated
frame : ReferenceFrame
The reference frame to calculate the time derivative in
order : integer
The order of the derivative to be calculated

References

http://en.wikipedia.org/wiki/Rotating_reference_frame#Time_derivatives_in_the_two_
frames

Examples

>>> from sympy.physics.vector import ReferenceFrame, dynamicsymbols

>>> from sympy import Symbol
>>> q1 = Symbol('q1')
>>> u1 = dynamicsymbols('u1')
>>> N = ReferenceFrame('N')
>>> A = N.orientnew('A', 'Axis', [q1, N.x])
>>> v = u1 * N.x
>>> A.set_ang_vel(N, 10*A.x)
>>> from sympy.physics.vector import time_derivative
>>> time_derivative(v, N)
u1'*N.x
>>> time_derivative(u1*A[0], N)
N_x*Derivative(u1(t), t)
>>> B = N.orientnew('B', 'Axis', [u1, N.z])
>>> from sympy.physics.vector import outer
>>> d = outer(N.x, N.x)
>>> time_derivative(d, B)
- u1'*(N.y|N.x) - u1'*(N.x|N.y)

Docstrings for basic field functions

5.40. Physics Module 1621

SymPy Documentation, Release 1.3

Field operation functions

These functions implement some basic operations pertaining to fields in general.

curl

sympy.physics.vector.fieldfunctions.curl(vect, frame)
Returns the curl of a vector field computed wrt the coordinate symbols of the given
frame.
Parameters vect : Vector
The vector operand
frame : ReferenceFrame
The reference frame to calculate the curl in

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import curl
>>> R = ReferenceFrame('R')
>>> v1 = R[1]*R[2]*R.x + R[0]*R[2]*R.y + R[0]*R[1]*R.z
>>> curl(v1, R)
0
>>> v2 = R[0]*R[1]*R[2]*R.x
>>> curl(v2, R)
R_x*R_y*R.y - R_x*R_z*R.z

divergence

sympy.physics.vector.fieldfunctions.divergence(vect, frame)
Returns the divergence of a vector field computed wrt the coordinate symbols of the
given frame.
Parameters vect : Vector
The vector operand
frame : ReferenceFrame
The reference frame to calculate the divergence in

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import divergence
>>> R = ReferenceFrame('R')
>>> v1 = R[0]*R[1]*R[2] * (R.x+R.y+R.z)
>>> divergence(v1, R)
R_x*R_y + R_x*R_z + R_y*R_z
(continues on next page)

1622 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> v2 = 2*R[1]*R[2]*R.y
>>> divergence(v2, R)
2*R_z

gradient

sympy.physics.vector.fieldfunctions.gradient(scalar, frame)
Returns the vector gradient of a scalar field computed wrt the coordinate symbols of the
given frame.
Parameters scalar : sympifiable
The scalar field to take the gradient of
frame : ReferenceFrame
The frame to calculate the gradient in

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import gradient
>>> R = ReferenceFrame('R')
>>> s1 = R[0]*R[1]*R[2]
>>> gradient(s1, R)
R_y*R_z*R.x + R_x*R_z*R.y + R_x*R_y*R.z
>>> s2 = 5*R[0]**2*R[2]
>>> gradient(s2, R)
10*R_x*R_z*R.x + 5*R_x**2*R.z

scalar_potential

sympy.physics.vector.fieldfunctions.scalar_potential(field, frame)
Returns the scalar potential function of a field in a given frame (without the added inte-
gration constant).
Parameters field : Vector
The vector field whose scalar potential function is to be calculated
frame : ReferenceFrame
The frame to do the calculation in

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import scalar_potential, gradient
>>> R = ReferenceFrame('R')
>>> scalar_potential(R.z, R) == R[2]
True
(continues on next page)

5.40. Physics Module 1623

SymPy Documentation, Release 1.3

(continued from previous page)

>>> scalar_field = 2*R[0]**2*R[1]*R[2]
>>> grad_field = gradient(scalar_field, R)
>>> scalar_potential(grad_field, R)
2*R_x**2*R_y*R_z

scalar_potential_difference

sympy.physics.vector.fieldfunctions.scalar_potential_difference(field,
frame,
point1,
point2,
origin)
Returns the scalar potential difference between two points in a certain frame, wrt a given
field.
If a scalar field is provided, its values at the two points are considered. If a conservative
vector field is provided, the values of its scalar potential function at the two points are
used.
Returns (potential at position 2) - (potential at position 1)
Parameters field : Vector/sympyfiable
The field to calculate wrt
frame : ReferenceFrame
The frame to do the calculations in
point1 : Point
The initial Point in given frame
position2 : Point
The second Point in the given frame
origin : Point
The Point to use as reference point for position vector calculation

Examples

>>> from sympy.physics.vector import ReferenceFrame, Point

>>> from sympy.physics.vector import scalar_potential_difference
>>> R = ReferenceFrame('R')
>>> O = Point('O')
>>> P = O.locatenew('P', R[0]*R.x + R[1]*R.y + R[2]*R.z)
>>> vectfield = 4*R[0]*R[1]*R.x + 2*R[0]**2*R.y
>>> scalar_potential_difference(vectfield, R, O, P, O)
2*R_x**2*R_y
>>> Q = O.locatenew('O', 3*R.x + R.y + 2*R.z)
>>> scalar_potential_difference(vectfield, R, P, Q, O)
-2*R_x**2*R_y + 18

1624 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Checking the type of vector field

is_conservative

sympy.physics.vector.fieldfunctions.is_conservative(field)
Checks if a field is conservative.
Parameters field : Vector
The field to check for conservative property

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import is_conservative
>>> R = ReferenceFrame('R')
>>> is_conservative(R[1]*R[2]*R.x + R[0]*R[2]*R.y + R[0]*R[1]*R.z)
True
>>> is_conservative(R[2] * R.y)
False

is_solenoidal

sympy.physics.vector.fieldfunctions.is_solenoidal(field)
Checks if a field is solenoidal.
Parameters field : Vector
The field to check for solenoidal property

Examples

>>> from sympy.physics.vector import ReferenceFrame

>>> from sympy.physics.vector import is_solenoidal
>>> R = ReferenceFrame('R')
>>> is_solenoidal(R[1]*R[2]*R.x + R[0]*R[2]*R.y + R[0]*R[1]*R.z)
True
>>> is_solenoidal(R[1] * R.y)
False

Classical Mechanics

Abstract

In this documentation many components of the physics/mechanics module will be discussed.

mechanics has been written to allow for creation of symbolic equations of motion for com-
plicated multibody systems.

5.40. Physics Module 1625

SymPy Documentation, Release 1.3

Vector

This module derives the vector-related abilities and related functionalities from physics.
vector. Please have a look at the documentation of physics.vector and its necessary API
to understand the vector capabilities of mechanics.

Mechanics

In physics, mechanics describes conditions of rest (statics) or motion (dynamics). There are a
few common steps to all mechanics problems. First, an idealized representation of a system is
described. Next, we use physical laws to generate equations that define the system’s behavior.
Then, we solve these equations, sometimes analytically but usually numerically. Finally, we
extract information from these equations and solutions. The current scope of the module is
multi-body dynamics: the motion of systems of multiple particles and/or rigid bodies. For
example, this module could be used to understand the motion of a double pendulum, planets,
robotic manipulators, bicycles, and any other system of rigid bodies that may fascinate us.
Often, the objective in multi-body dynamics is to obtain the trajectory of a system of rigid
bodies through time. The challenge for this task is to first formulate the equations of motion
of the system. Once they are formulated, they must be solved, that is, integrated forward in
time. When digital computers came around, solving became the easy part of the problem.
Now, we can tackle more complicated problems, which leaves the challenge of formulating
the equations.
The term “equations of motion” is used to describe the application of Newton’s second law to
multi-body systems. The form of the equations of motion depends on the method used to gen-
erate them. This package implements two of these methods: Kane’s method and Lagrange’s
method. This module facilitates the formulation of equations of motion, which can then be
solved (integrated) using generic ordinary differential equation (ODE) solvers.
The approach to a particular class of dynamics problems, that of forward dynamics, has the
following steps:
1. describing the system’s geometry and configuration,
2. specifying the way the system can move, including constraints on its motion
3. describing the external forces and moments on the system,
4. combining the above information according to Newton’s second law (F = ma), and
5. organizing the resulting equations so that they can be integrated to obtain the system’s
trajectory through time.
Together with the rest of SymPy, this module performs steps 4 and 5, provided that the user
can perform 1 through 3 for the module. That is to say, the user must provide a complete
representation of the free body diagrams that themselves represent the system, with which
this code can provide equations of motion in a form amenable to numerical integration. Step
5 above amounts to arduous algebra for even fairly simple multi-body systems. Thus, it is
desirable to use a symbolic math package, such as Sympy, to perform this step. It is for
this reason that this module is a part of Sympy. Step 4 amounts to this specific module,
sympy.physics.mechanics.

Guide to Mechanics

1626 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Masses, Inertias, Particles and Rigid Bodies in Physics/Mechanics

This document will describe how to represent masses and inertias in mechanics and use of
the RigidBody and Particle classes.
It is assumed that the reader is familiar with the basics of these topics, such as finding the
center of mass for a system of particles, how to manipulate an inertia tensor, and the definition
of a particle and rigid body. Any advanced dynamics text can provide a reference for these
details.

Mass

The only requirement for a mass is that it needs to be a sympify-able expression. Keep in
mind that masses can be time varying.

Particle

Particles are created with the class Particle in mechanics. A Particle object has an asso-
ciated point and an associated mass which are the only two attributes of the object.:

>>> from sympy.physics.mechanics import Particle, Point

>>> from sympy import Symbol
>>> m = Symbol('m')
>>> po = Point('po')
>>> # create a particle container
>>> pa = Particle('pa', po, m)

The associated point contains the position, velocity and acceleration of the particle. mechan-
ics allows one to perform kinematic analysis of points separate from their association with
masses.

Inertia

See the Inertia (Dyadics) section in ‘Advanced Topics’ part of physics/vector docs.

Rigid Body

Rigid bodies are created in a similar fashion as particles. The RigidBody class generates
objects with four attributes: mass, center of mass, a reference frame, and an inertia tuple:

>>> from sympy import Symbol

>>> from sympy.physics.mechanics import ReferenceFrame, Point, RigidBody
>>> from sympy.physics.mechanics import outer
>>> m = Symbol('m')
>>> A = ReferenceFrame('A')
>>> P = Point('P')
>>> I = outer(A.x, A.x)
>>> # create a rigid body
>>> B = RigidBody('B', P, A, m, (I, P))

5.40. Physics Module 1627

SymPy Documentation, Release 1.3

The mass is specified exactly as is in a particle. Similar to the Particle’s .point, the Rigid-
Body’s center of mass, .masscenter must be specified. The reference frame is stored in an
analogous fashion and holds information about the body’s orientation and angular velocity.
Finally, the inertia for a rigid body needs to be specified about a point. In mechanics, you are
allowed to specify any point for this. The most common is the center of mass, as shown in the
above code. If a point is selected which is not the center of mass, ensure that the position
between the point and the center of mass has been defined. The inertia is specified as a tuple
of length two with the first entry being a Dyadic and the second entry being a Point of which
the inertia dyadic is defined about.

Dyadic

In mechanics, dyadics are used to represent inertia ([Kane1985], [WikiDyadics],

[WikiDyadicProducts]). A dyadic is a linear polynomial of component unit dyadics, similar
to a vector being a linear polynomial of component unit vectors. A dyadic is the outer product
between two vectors which returns a new quantity representing the juxtaposition of these
two vectors. For example:

ax ⊗ ^
^ ax = ^
ax^
ax
ax ⊗ ^
^ ay = ^
ax^
ay

Where ^ax^
ax and ^ax^
ay are the outer products obtained by multiplying the left side as a column
vector by the right side as a row vector. Note that the order is significant.
Some additional properties of a dyadic are:

(xv) ⊗ w = v ⊗ (xw) = x(v ⊗ w)

v ⊗ (w + u) = v ⊗ w + v ⊗ u
(v + w) ⊗ u = v ⊗ u + w ⊗ u
 
a
A vector in a reference frame can be represented as  b  or a^
i + b^
j + c^
k. Similarly, a dyadic can
c
be represented in tensor form:
 
a11 a12 a13
a21 a22 a23 
a31 a32 a33

or in dyadic form:

a11^
ax^
ax + a12^
ax^
ay + a13^
ax^
az + a21^
ay^
ax + a22^
ay^
ay + a23^
ay^
az + a31^
az^
ax + a32^
az^
ay + a33^
az^
az

Just as with vectors, the later representation makes it possible to keep track of which frames
the dyadic is defined with respect to. Also, the two components of each term in the dyadic
need not be in the same frame. The following is valid:

ax ⊗ ^
^ ax^
by = ^ by

1628 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Dyadics can also be crossed and dotted with vectors; again, order matters:
^ ax · ^
ax^ ax = ^
ax
^ ax · ^
ay^ ax = ^
ay
^ ay · ^
ax^ ax = 0
ax · ^
^ ax^
ax = ^
ax
ax · ^
^ ax^
ay = ^
ay
ax · ^
^ ay^
ax = 0
ax × ^
^ ay^
ax = ^
az^ax
ax × ^
^ ax^
ax = 0
^ ax × ^
ay^ az = −^ay^
ay
One can also take the time derivative of dyadics or express them in different frames, just like
with vectors.

Linear Momentum

The linear momentum of a particle P is defined as:

LP = mv
where m is the mass of the particle P and v is the velocity of the particle in the inertial
frame.[Likins1973]_.
Similarly the linear momentum of a rigid body is defined as:
LB = mv∗
where m is the mass of the rigid body, B, and v∗ is the velocity of the mass center of B in the
inertial frame.

Angular Momentum

The angular momentum of a particle P about an arbitrary point O in an inertial frame N is

defined as:
N
HP /O = r × mv
where r is a position vector from point O to the particle of mass m and v is the velocity of the
particle in the inertial frame.
Similarly the angular momentum of a rigid body B about a point O in an inertial frame N is
defined as:
∗ ∗
N
HB/O =N HB/B +N HB /O

where the angular momentum of the body about it’s mass center is:
∗
N
HB/B = I∗ · ω
and the angular momentum of the mass center about O is:
∗
N
HB /O
= r∗ × mv∗
where I∗ is the central inertia dyadic of rigid body B, ω is the inertial angular velocity of B,
r∗ is a position vector from point O to the mass center of B, m is the mass of B and v∗ is the
velocity of the mass center in the inertial frame.

5.40. Physics Module 1629

SymPy Documentation, Release 1.3

Using momenta functions in Mechanics

The following example shows how to use the momenta functions in mechanics.
One begins by creating the requisite symbols to describe the system. Then the reference
frame is created and the kinematics are done.

>> from sympy import symbols

>> from sympy.physics.mechanics import dynamicsymbols, ReferenceFrame
>> from sympy.physics.mechanics import RigidBody, Particle, Point, outer
>> from sympy.physics.mechanics import linear_momentum, angular_momentum
>> m, M, l1 = symbols('m M l1')
>> q1d = dynamicsymbols('q1d')
>> N = ReferenceFrame('N')
>> O = Point('O')
>> O.set_vel(N, 0 * N.x)
>> Ac = O.locatenew('Ac', l1 * N.x)
>> P = Ac.locatenew('P', l1 * N.x)
>> a = ReferenceFrame('a')
>> a.set_ang_vel(N, q1d * N.z)
>> Ac.v2pt_theory(O, N, a)
>> P.v2pt_theory(O, N, a)

Finally, the bodies that make up the system are created. In this case the system consists of a
particle Pa and a RigidBody A.

>> Pa = Particle('Pa', P, m)
>> I = outer(N.z, N.z)
>> A = RigidBody('A', Ac, a, M, (I, Ac))

Then one can either choose to evaluate the momenta of individual components of the system
or of the entire system itself.

>> linear_momentum(N,A)
M*l1*q1d*N.y
>> angular_momentum(O, N, Pa)
4*l1**2*m*q1d*N.z
>> linear_momentum(N, A, Pa)
(M*l1*q1d + 2*l1*m*q1d)*N.y
>> angular_momentum(O, N, A, Pa)
(4*l1**2*m*q1d + q1d)*N.z

It should be noted that the user can determine either momenta in any frame in mechanics as
the user is allowed to specify the reference frame when calling the function. In other words
the user is not limited to determining just inertial linear and angular momenta. Please refer
to the docstrings on each function to learn more about how each function works precisely.

Kinetic Energy

The kinetic energy of a particle P is defined as

1
TP = mv2
2
where m is the mass of the particle P and v is the velocity of the particle in the inertial frame.

1630 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Similarly the kinetic energy of a rigid body B is defined as

TB = Tt + Tr

where the translational kinetic energy is given by:

1
Tt = mv∗ · v∗
2
and the rotational kinetic energy is given by:
1
Tr = ω · I∗ · ω
2
where m is the mass of the rigid body, v∗ is the velocity of the mass center in the inertial
frame, ω is the inertial angular velocity of the body and I∗ is the central inertia dyadic.

Potential Energy

Potential energy is defined as the energy possessed by a body or system by virtue of its position
or arrangement.
Since there are a variety of definitions for potential energy, this is not discussed further here.
One can learn more about this in any elementary text book on dynamics.

Lagrangian

The Lagrangian of a body or a system of bodies is defined as:

L=T −V

where T and V are the kinetic and potential energies respectively.

Using energy functions in Mechanics

The following example shows how to use the energy functions in mechanics.
As was discussed above in the momenta functions, one first creates the system by going
through an identical procedure.
>> from sympy import symbols
>> from sympy.physics.mechanics import dynamicsymbols, ReferenceFrame, outer
>> from sympy.physics.mechanics import RigidBody, Particle, mechanics_printing
>> from symp.physics.mechanics import kinetic_energy, potential_energy, Point
>> mechanics_printing()
>> m, M, l1, g, h, H = symbols('m M l1 g h H')
>> omega = dynamicsymbols('omega')
>> N = ReferenceFrame('N')
>> O = Point('O')
>> O.set_vel(N, 0 * N.x)
>> Ac = O.locatenew('Ac', l1 * N.x)
>> P = Ac.locatenew('P', l1 * N.x)
>> a = ReferenceFrame('a')
>> a.set_ang_vel(N, omega * N.z)
(continues on next page)

5.40. Physics Module 1631

SymPy Documentation, Release 1.3

(continued from previous page)

>> Ac.v2pt_theory(O, N, a)
>> P.v2pt_theory(O, N, a)
>> Pa = Particle('Pa', P, m)
>> I = outer(N.z, N.z)
>> A = RigidBody('A', Ac, a, M, (I, Ac))

The user can then determine the kinetic energy of any number of entities of the system:
>> kinetic_energy(N, Pa)
2*l1**2*m*q1d**2
>> kinetic_energy(N, Pa, A)
M*l1**2*q1d**2/2 + 2*l1**2*m*q1d**2 + q1d**2/2

It should be noted that the user can determine either kinetic energy relative to any frame in
mechanics as the user is allowed to specify the reference frame when calling the function. In
other words the user is not limited to determining just inertial kinetic energy.
For potential energies, the user must first specify the potential energy of every entity of the
system using the potential_energy property. The potential energy of any number of entities
comprising the system can then be determined:
>> Pa.potential_energy = m * g * h
>> A.potential_energy = M * g * H
>> potential_energy(A, Pa)
H*M*g + g*h*m

One can also determine the Lagrangian for this system:

>> Lagrangian(Pa, A)
-H*M*g + M*l1**2*q1d**2/2 - g*h*m + 2*l1**2*m*q1d**2 + q1d**2/2

Please refer to the docstrings to learn more about each function.

Kane’s Method in Physics/Mechanics

mechanics provides functionality for deriving equations of motion using Kane’s method
[Kane1985]. This document will describe Kane’s method as used in this module, but not
how the equations are actually derived.

Structure of Equations

In mechanics we are assuming there are 5 basic sets of equations needed to describe a system.
They are: holonomic constraints, non-holonomic constraints, kinematic differential equations,
dynamic equations, and differentiated non-holonomic equations.
fh (q, t) = 0
knh (q, t)u + fnh (q, t) = 0
kkq_ (q, t)q̇ + kku (q, t)u + fk (q, t) = 0
kd (q, t)u̇ + fd (q, q̇, u, t) = 0
kdnh (q, t)u̇ + fdnh (q, q̇, u, t) = 0
In mechanics holonomic constraints are only used for the linearization process; it is assumed
that they will be too complicated to solve for the dependent coordinate(s). If you are able to

1632 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

easily solve a holonomic constraint, you should consider redefining your problem in terms of
a smaller set of coordinates. Alternatively, the time-differentiated holonomic constraints can
be supplied.
Kane’s method forms two expressions, Fr and Fr∗ , whose sum is zero. In this module, these
expressions are rearranged into the following form:
M(q, t)u̇ = f(q, q̇, u, t)
For a non-holonomic system with o total speeds and m motion constraints, we will get o - m
equations. The mass-matrix/forcing equations are then augmented in the following fashion:
[ ]
kd (q, t)
M(q, t) =
kdnh (q, t)
[ ]
−fd (q, q̇, u, t)
(q, q̇, u, t) =
(forcing)
−fdnh (q, q̇, u, t)

Kane’s Method in Physics/Mechanics

The formulation of the equations of motion in mechanics starts with creation of a KanesMethod
object. Upon initialization of the KanesMethod object, an inertial reference frame needs to be
supplied. along with some basic system information, such as coordinates and speeds

>>> from sympy.physics.mechanics import *

>>> N = ReferenceFrame('N')
>>> q1, q2, u1, u2 = dynamicsymbols('q1 q2 u1 u2')
>>> q1d, q2d, u1d, u2d = dynamicsymbols('q1 q2 u1 u2', 1)
>>> KM = KanesMethod(N, [q1, q2], [u1, u2])

It is also important to supply the order of coordinates and speeds properly if there are de-
pendent coordinates and speeds. They must be supplied after independent coordinates and
speeds or as a keyword argument; this is shown later.

>>> q1, q2, q3, q4 = dynamicsymbols('q1 q2 q3 q4')

>>> u1, u2, u3, u4 = dynamicsymbols('u1 u2 u3 u4')
>>> # Here we will assume q2 is dependent, and u2 and u3 are dependent
>>> # We need the constraint equations to enter them though
>>> KM = KanesMethod(N, [q1, q3, q4], [u1, u4])

Additionally, if there are auxiliary speeds, they need to be identified here. See the examples
for more information on this. In this example u4 is the auxiliary speed.

>>> KM = KanesMethod(N, [q1, q3, q4], [u1, u2, u3], u_auxiliary=[u4])

Kinematic differential equations must also be supplied; there are to be provided as a list of
expressions which are each equal to zero. A trivial example follows:

>>> kd = [q1d - u1, q2d - u2]

Turning on mechanics_printing() makes the expressions significantly shorter and is recom-

mended. Alternatively, the mprint and mpprint commands can be used.
If there are non-holonomic constraints, dependent speeds need to be specified (and so do
dependent coordinates, but they only come into play when linearizing the system). The con-
straints need to be supplied in a list of expressions which are equal to zero, trivial motion and
configuration constraints are shown below:

5.40. Physics Module 1633

SymPy Documentation, Release 1.3

>>> N = ReferenceFrame('N')
>>> q1, q2, q3, q4 = dynamicsymbols('q1 q2 q3 q4')
>>> q1d, q2d, q3d, q4d = dynamicsymbols('q1 q2 q3 q4', 1)
>>> u1, u2, u3, u4 = dynamicsymbols('u1 u2 u3 u4')
>>> #Here we will assume q2 is dependent, and u2 and u3 are dependent
>>> speed_cons = [u2 - u1, u3 - u1 - u4]
>>> coord_cons = [q2 - q1]
>>> q_ind = [q1, q3, q4]
>>> q_dep = [q2]
>>> u_ind = [u1, u4]
>>> u_dep = [u2, u3]
>>> kd = [q1d - u1, q2d - u2, q3d - u3, q4d - u4]
>>> KM = KanesMethod(N, q_ind, u_ind, kd,
... q_dependent=q_dep,
... configuration_constraints=coord_cons,
... u_dependent=u_dep,
... velocity_constraints=speed_cons)

A dictionary returning the solved q̇’s can also be solved for:

>>> mechanics_printing(pretty_print=False)
>>> KM.kindiffdict()
{q1': u1, q2': u2, q3': u3, q4': u4}

The final step in forming the equations of motion is supplying a list of bodies and particles, and
a list of 2-tuples of the form (Point, Vector) or (ReferenceFrame, Vector) to represent
applied forces and torques.
>>> N = ReferenceFrame('N')
>>> q, u = dynamicsymbols('q u')
>>> qd, ud = dynamicsymbols('q u', 1)
>>> P = Point('P')
>>> P.set_vel(N, u * N.x)
>>> Pa = Particle('Pa', P, 5)
>>> BL = [Pa]
>>> FL = [(P, 7 * N.x)]
>>> KM = KanesMethod(N, [q], [u], [qd - u])
>>> (fr, frstar) = KM.kanes_equations(BL, FL)
>>> KM.mass_matrix
Matrix([[5]])
>>> KM.forcing
Matrix([[7]])

When there are motion constraints, the mass matrix is augmented by the kdnh (q, t) matrix, and
the forcing vector by the fdnh (q, q̇, u, t) vector.
There are also the “full” mass matrix and “full” forcing vector terms, these include the kine-
matic differential equations; the mass matrix is of size (n + o) x (n + o), or square and the
size of all coordinates and speeds.
>>> KM.mass_matrix_full
Matrix([
[1, 0],
[0, 5]])
>>> KM.forcing_full
Matrix([
[u],
[7]])

1634 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Exploration of the provided examples is encouraged in order to gain more understanding of

the KanesMethod object.

Lagrange’s Method in Physics/Mechanics

mechanics provides functionality for deriving equations of motion using Lagrange’s method.
This document will describe Lagrange’s method as used in this module, but not how the
equations are actually derived.

Structure of Equations

In mechanics we are assuming there are 3 basic sets of equations needed to describe a sys-
tem; the constraint equations, the time differentiated constraint equations and the dynamic
equations.

mc (q, t)q̇ + fc (q, t) = 0

mdc (q̇, q, t)q̈ + fdc (q̇, q, t) = 0
md (q̇, q, t)q̈ + c (q, t)λ + fd (q̇, q, t) = 0

In this module, the expressions formed by using Lagrange’s equations of the second kind are
rearranged into the following form:
M(q, t)x = f(q, q̇, t)
where in the case of a system without constraints:
x = q̈
For a constrained system with n generalized speeds and m constraints, we will get n - m
equations. The mass-matrix/forcing equations are then augmented in the following fashion:
[ ]
q̈
x=
λ
[ ]
M(q, t) = md (q, t) c (q, t)
[ ]
F(q̇, q, t) = fd (q, q̇, t)

Lagrange’s Method in Physics/Mechanics

The formulation of the equations of motion in mechanics using Lagrange’s Method starts
with the creation of generalized coordinates and a Lagrangian. The Lagrangian can either
be created with the Lagrangian function or can be a user supplied function. In this case we
will supply the Lagrangian.

>>> from sympy.physics.mechanics import *

>>> q1, q2 = dynamicsymbols('q1 q2')
>>> q1d, q2d = dynamicsymbols('q1 q2', 1)
>>> L = q1d**2 + q2d**2

To formulate the equations of motion we create a LagrangesMethod object. The Lagrangian

and generalized coordinates need to be supplied upon initialization.

5.40. Physics Module 1635

SymPy Documentation, Release 1.3

>>> LM = LagrangesMethod(L, [q1, q2])

With that the equations of motion can be formed.

>>> mechanics_printing(pretty_print=False)
>>> LM.form_lagranges_equations()
Matrix([
[2*q1''],
[2*q2'']])

It is possible to obtain the mass matrix and the forcing vector.

>>> LM.mass_matrix
Matrix([
[2, 0],
[0, 2]])

>>> LM.forcing
Matrix([
[0],
[0]])

If there are any holonomic or non-holonomic constraints, they must be supplied as keyword
arguments (hol_coneqs and nonhol_coneqs respectively) in a list of expressions which are
equal to zero. Modifying the example above, the equations of motion can then be generated:

>>> LM = LagrangesMethod(L, [q1, q2], hol_coneqs=[q1 - q2])

When the equations of motion are generated in this case, the Lagrange multipliers are intro-
duced; they are represented by lam1 in this case. In general, there will be as many multipliers
as there are constraint equations.

>>> LM.form_lagranges_equations()
Matrix([
[ lam1 + 2*q1''],
[-lam1 + 2*q2'']])

Also in the case of systems with constraints, the ‘full’ mass matrix is augmented by the kdc (q, t)
matrix, and the forcing vector by the fdc (q, q̇, t) vector. The ‘full’ mass matrix is of size (2n +
o) x (2n + o), i.e. it’s a square matrix.

>>> LM.mass_matrix_full
Matrix([
[1, 0, 0, 0, 0],
[0, 1, 0, 0, 0],
[0, 0, 2, 0, -1],
[0, 0, 0, 2, 1],
[0, 0, 1, -1, 0]])
>>> LM.forcing_full
Matrix([
[q1'],
[q2'],
[ 0],
[ 0],
[ 0]])

If there are any non-conservative forces or moments acting on the system, they must also

1636 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

be supplied as keyword arguments in a list of 2-tuples of the form (Point, Vector) or

(ReferenceFrame, Vector) where the Vector represents the non-conservative forces and
torques. Along with this 2-tuple, the inertial frame must also be specified as a keyword argu-
ment. This is shown below by modifying the example above:
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, q1d * N.x)
>>> FL = [(P, 7 * N.x)]
>>> LM = LagrangesMethod(L, [q1, q2], forcelist=FL, frame=N)
>>> LM.form_lagranges_equations()
Matrix([
[2*q1'' - 7],
[ 2*q2'']])

Exploration of the provided examples is encouraged in order to gain more understanding of

the LagrangesMethod object.

Symbolic Systems in Physics/Mechanics

The SymbolicSystem class in physics/mechanics is a location for the pertinent information of a

multibody dynamic system. In its most basic form it contains the equations of motion for the
dynamic system, however, it can also contain information regarding the loads that the system
is subject to, the bodies that the system is comprised of and any additional equations the user
feels is important for the system. The goal of this class is to provide a unified output format
for the equations of motion that numerical analysis code can be designed around.

SymbolicSystem Example Usage

This code will go over the manual input of the equations of motion for the simple pen-
dulum that uses the Cartesian location of the mass as the generalized coordinates into
SymbolicSystem.
The equations of motion are formed in the physics/mechanics/examples. In that spot the
variables q1 and q2 are used in place of x and y and the reference frame is rotated 90 degrees.
>>> from sympy import atan, symbols, Matrix
>>> from sympy.physics.mechanics import (dynamicsymbols, ReferenceFrame,
... Particle, Point)
>>> import sympy.physics.mechanics.system as system

The first step will be to initialize all of the dynamic and constant symbols.
>>> x, y, u, v, lam = dynamicsymbols('x y u v lambda')
>>> m, l, g = symbols('m l g')

Next step is to define the equations of motion in multiple forms:

[1] Explicit form where the kinematics and dynamics are combined x’ =
F_1(x, t, r, p)
[2] Implicit form where the kinematics and dynamics are combined M_2(x,
p) x’ = F_2(x, t, r, p)
[3] Implicit form where the kinematics and dynamics are separate M_3(q,
p) u’ = F_3(q, u, t, r, p) q’ = G(q, u, t, r, p)

5.40. Physics Module 1637

SymPy Documentation, Release 1.3

where
x : states, e.g. [q, u] t : time r : specified (exogenous) inputs p : constants q :
generalized coordinates u : generalized speeds F_1 : right hand side of the com-
bined equations in explicit form F_2 : right hand side of the combined equations
in implicit form F_3 : right hand side of the dynamical equations in implicit form
M_2 : mass matrix of the combined equations in implicit form M_3 : mass matrix
of the dynamical equations in implicit form G : right hand side of the kinematical
differential equations
>>> dyn_implicit_mat = Matrix([[1, 0, -x/m],
... [0, 1, -y/m],
... [0, 0, l**2/m]])
>>> dyn_implicit_rhs = Matrix([0, 0, u**2 + v**2 - g*y])
>>> comb_implicit_mat = Matrix([[1, 0, 0, 0, 0],
... [0, 1, 0, 0, 0],
... [0, 0, 1, 0, -x/m],
... [0, 0, 0, 1, -y/m],
... [0, 0, 0, 0, l**2/m]])
>>> comb_implicit_rhs = Matrix([u, v, 0, 0, u**2 + v**2 - g*y])
>>> kin_explicit_rhs = Matrix([u, v])
>>> comb_explicit_rhs = comb_implicit_mat.LUsolve(comb_implicit_rhs)

Now the reference frames, points and particles will be set up so this information can be passed
into system.SymbolicSystem in the form of a bodies and loads iterable.
>>> theta = atan(x/y)
>>> omega = dynamicsymbols('omega')
>>> N = ReferenceFrame('N')
>>> A = N.orientnew('A', 'Axis', [theta, N.z])
>>> A.set_ang_vel(N, omega * N.z)
>>> O = Point('O')
>>> O.set_vel(N, 0)
>>> P = O.locatenew('P', l * A.x)
>>> P.v2pt_theory(O, N, A)
l*omega*A.y
>>> Pa = Particle('Pa', P, m)

Now the bodies and loads iterables need to be initialized.

>>> bodies = [Pa]
>>> loads = [(P, g * m * N.x)]

The equations of motion are in the form of a differential algebraic equation (DAE) and DAE
solvers need to know which of the equations are the algebraic expressions. This information
is passed into SymbolicSystem as a list specifying which rows are the algebraic equations. In
this example it is a different row based on the chosen equations of motion format. The row
index should always correspond to the mass matrix that is being input to the SymbolicSystem
class but will always correspond to the row index of the combined dynamics and kinematics
when being accessed from the SymbolicSystem class.
>>> alg_con = [2]
>>> alg_con_full = [4]

An iterable containing the states now needs to be created for the system. The SymbolicSystem
class can determine which of the states are considered coordinates or speeds by passing in
the indexes of the coordinates and speeds. If these indexes are not passed in the object will
not be able to differentiate between coordinates and speeds.

1638 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> states = (x, y, u, v, lam)

>>> coord_idxs = (0, 1)
>>> speed_idxs = (2, 3)

Now the equations of motion instances can be created using the above mentioned equations
of motion formats.

>>> symsystem1 = system.SymbolicSystem(states, comb_explicit_rhs,

... alg_con=alg_con_full, bodies=bodies,
... loads=loads)
>>> symsystem2 = system.SymbolicSystem(states, comb_implicit_rhs,
... mass_matrix=comb_implicit_mat,
... alg_con=alg_con_full,
... coord_idxs=coord_idxs)
>>> symsystem3 = system.SymbolicSystem(states, dyn_implicit_rhs,
... mass_matrix=dyn_implicit_mat,
... coordinate_derivatives=kin_explicit_rhs,
... alg_con=alg_con,
... coord_idxs=coord_idxs,
... speed_idxs=speed_idxs)

Like coordinates and speeds, the bodies and loads attributes can only be
accessed if they are specified during initialization of the `SymbolicSystem`
class. Lastly here are some attributes accessible from the `SymbolicSystem`
class. ::

>>> symsystem1.states
Matrix([
[ x(t)],
[ y(t)],
[ u(t)],
[ v(t)],
[lambda(t)]])
>>> symsystem2.coordinates
Matrix([
[x(t)],
[y(t)]])
>>> symsystem3.speeds
Matrix([
[u(t)],
[v(t)]])
>>> symsystem1.comb_explicit_rhs
Matrix([
[ u(t)],
[ v(t)],
[(-g*y(t) + u(t)**2 + v(t)**2)*x(t)/l**2],
[(-g*y(t) + u(t)**2 + v(t)**2)*y(t)/l**2],
[ m*(-g*y(t) + u(t)**2 + v(t)**2)/l**2]])
>>> symsystem2.comb_implicit_rhs
Matrix([
[ u(t)],
[ v(t)],
[ 0],
[ 0],
[-g*y(t) + u(t)**2 + v(t)**2]])
>>> symsystem2.comb_implicit_mat
Matrix([
(continues on next page)

5.40. Physics Module 1639

SymPy Documentation, Release 1.3

(continued from previous page)

[1, 0, 0, 0, 0],
[0, 1, 0, 0, 0],
[0, 0, 1, 0, -x(t)/m],
[0, 0, 0, 1, -y(t)/m],
[0, 0, 0, 0, l**2/m]])
>>> symsystem3.dyn_implicit_rhs
Matrix([
[ 0],
[ 0],
[-g*y(t) + u(t)**2 + v(t)**2]])
>>> symsystem3.dyn_implicit_mat
Matrix([
[1, 0, -x(t)/m],
[0, 1, -y(t)/m],
[0, 0, l**2/m]])
>>> symsystem3.kin_explicit_rhs
Matrix([
[u(t)],
[v(t)]])
>>> symsystem1.alg_con
[4]
>>> symsystem1.bodies
(Pa,)
>>> symsystem1.loads
((P, g*m*N.x),)

Linearization in Physics/Mechanics

mechanics includes methods for linearizing the generated equations of motion (EOM) about
an operating point (also known as the trim condition). Note that this operating point doesn’t
have to be an equilibrium position, it just needs to satisfy the equations of motion.
Linearization is accomplished by taking the first order Taylor expansion of the EOM about
the operating point. When there are no dependent coordinates or speeds this is simply the
jacobian of the right hand side about q and u. However, in the presence of constraints more
care needs to be taken. The linearization methods provided here handle these constraints
correctly.

Background

In mechanics we assume all systems can be represented in the following general form:

fc (q, t) = 0l×1
fv (q, u, t) = 0m×1
fa (q, q̇, u, u̇, t) = 0m×1
f0 (q, q̇, t) + f1 (q, u, t) = 0n×1
f2 (q, u, u̇, t) + f3 (q, q̇, u, r, t) + f4 (q, λ, t) = 0(o−m+k)×1

1640 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

where
q, q̇ ∈ Rn
u, u̇ ∈ Ro
r ∈ Rs
λ ∈ Rk

In this form,
• fc represents the configuration constraint equations
• fv represents the velocity constraint equations
• fa represents the acceleration constraint equations
• f0 and f1 form the kinematic differential equations
• f2 , f3 , and f4 form the dynamic differential equations
• q and q̇ are the generalized coordinates and their derivatives
• u and u̇ are the generalized speeds and their derivatives
• r is the system inputs
• λ is the Lagrange multipliers
This generalized form is held inside the Linearizer class, which performs the actual lin-
earization. Both KanesMethod and LagrangesMethod objects have methods for forming the
linearizer using the to_linearizer class method.

A Note on Dependent Coordinates and Speeds

If the system being linearized contains constraint equations, this results in not all gener-
alized coordinates being independent (i.e. q1 may depend on q2 ). With l configuration con-
straints, and m velocity constraints, there are l dependent coordinates and m dependent
speeds.
In general, you may pick any of the coordinates and speeds to be dependent, but in practice
some choices may result in undesirable singularites. Methods for deciding which coordi-
nates/speeds to make dependent is behind the scope of this guide. For more information,
please see [Blajer1994].

Once the system is coerced into the generalized form, the linearized EOM can be solved for.
The methods provided in mechanics allow for two different forms of the linearized EOM:
M , A, and B In this form, the forcing matrix is linearized into two separate matrices A and
B. This is the default form of the linearized EOM. The resulting equations are:
 
δ q̇ [ ]
δqi [ ]
M δ u̇ = A + B δr
δui
δλ

where

M ∈ R(n+o+k)×(n+o+k)
A ∈ R(n+o+k)×(n−l+o−m)
B ∈ R(n+o+k)×s

5.40. Physics Module 1641

SymPy Documentation, Release 1.3

Note that qi and ui are just the independent coordinates and speeds, while q and u con-
tains both the independent and dependent coordinates and speeds.
A and B In this form, the linearized EOM are brought into explicit first order form, in terms of
just the independent coordinates and speeds. This form is often used in stability analysis
or control theory. The resulting equations are:
[ ] [ ]
δ q˙i δqi [ ]
=A + B δr
δ u̇i δui

where

A ∈ R(n−l+o−m)×(n−l+o−m)
B ∈ R(n−l+o−m)×s

To use this form set A_and_B=True in the linearize class method.

Linearizing Kane’s Equations

After initializing the KanesMethod object and forming Fr and Fr∗ using the kanes_equations
class method, linearization can be accomplished in a couple ways. The different methods will
be demonstrated with a simple pendulum system:

>>> from sympy import symbols, Matrix

>>> from sympy.physics.mechanics import *
>>> q1 = dynamicsymbols('q1') # Angle of pendulum
>>> u1 = dynamicsymbols('u1') # Angular velocity
>>> q1d = dynamicsymbols('q1', 1)
>>> L, m, t, g = symbols('L, m, t, g')

>>> # Compose world frame

>>> N = ReferenceFrame('N')
>>> pN = Point('N*')
>>> pN.set_vel(N, 0)

>>> # A.x is along the pendulum

>>> A = N.orientnew('A', 'axis', [q1, N.z])
>>> A.set_ang_vel(N, u1*N.z)

>>> # Locate point P relative to the origin N*

>>> P = pN.locatenew('P', L*A.x)
>>> vel_P = P.v2pt_theory(pN, N, A)
>>> pP = Particle('pP', P, m)

>>> # Create Kinematic Differential Equations

>>> kde = Matrix([q1d - u1])

>>> # Input the force resultant at P

>>> R = m*g*N.x

>>> # Solve for eom with kanes method

>>> KM = KanesMethod(N, q_ind=[q1], u_ind=[u1], kd_eqs=kde)
>>> fr, frstar = KM.kanes_equations([pP], [(P, R)])

1642 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

1. Using the Linearizer class directly:

A linearizer object can be created using the to_linearizer class method. This coerces the
representation found in the KanesMethod object into the generalized form described above.
As the independent and dependent coordinates and speeds are specified upon creation of the
KanesMethod object, there is no need to specify them here.
>>> linearizer = KM.to_linearizer()

The linearized EOM can then be formed with the linearize method of the Linearizer object:
>>> M, A, B = linearizer.linearize()
>>> M
Matrix([
[1, 0],
[0, -L**2*m]])
>>> A
Matrix([
[ 0, 1],
[L*g*m*cos(q1(t)), 0]])
>>> B
Matrix(0, 0, [])

Alternatively, the A and B form can be generated instead by specifying A_and_B=True:

>>> A, B = linearizer.linearize(A_and_B=True)
>>> A
Matrix([
[ 0, 1],
[-g*cos(q1(t))/L, 0]])
>>> B
Matrix(0, 0, [])

An operating point can also be specified as a dictionary or an iterable of dictionaries. This

will evaluate the linearized form at the specified point before returning the matrices:
>>> op_point = {q1: 0, u1: 0}
>>> A_op, B_op = linearizer.linearize(A_and_B=True, op_point=op_point)
>>> A_op
Matrix([
[ 0, 1],
[-g/L, 0]])

Note that the same effect can be had by applying msubs to the matrices generated without
the op_point kwarg:
>>> assert msubs(A, op_point) == A_op

Sometimes the returned matrices may not be in the most simplified form. Simplification can
be performed after the fact, or the Linearizer object can be made to perform simplification
internally by setting the simplify kwarg to True.

2. Using the linearize class method:

The linearize method of the KanesMethod class is provided as a nice wrapper that calls
to_linearizer internally, performs the linearization, and returns the result. Note that all

5.40. Physics Module 1643

SymPy Documentation, Release 1.3

the kwargs available in the linearize method described above are also available here:

>>> A, B, inp_vec = KM.linearize(A_and_B=True, op_point=op_point, new_method=True)

>>> A
Matrix([
[ 0, 1],
[-g/L, 0]])

The additional output inp_vec is a vector containing all found dynamicsymbols not included
in the generalized coordinate or speed vectors. These are assumed to be inputs to the system,
forming the r vector described in the background above. In this example there are no inputs,
so the vector is empty:

>>> inp_vec
Matrix(0, 0, [])

What’s with the new_method kwarg?

Previous releases of SymPy contained a linearization method for KanesM ethod objects. This
method is deprecated, and will be removed from future releases. Until then, you must set
new_method=True in all calls to KanesMethod.linearize. After the old method is removed,
this kwarg will no longer be needed.

Linearizing Lagrange’s Equations

Linearization of Lagrange’s equations proceeds much the same as that of Kane’s equations.
As before, the process will be demonstrated with a simple pendulum system:

>>> # Redefine A and P in terms of q1d, not u1

>>> A = N.orientnew('A', 'axis', [q1, N.z])
>>> A.set_ang_vel(N, q1d*N.z)
>>> P = pN.locatenew('P', L*A.x)
>>> vel_P = P.v2pt_theory(pN, N, A)
>>> pP = Particle('pP', P, m)

>>> # Solve for eom with Lagrange's method

>>> Lag = Lagrangian(N, pP)
>>> LM = LagrangesMethod(Lag, [q1], forcelist=[(P, R)], frame=N)
>>> lag_eqs = LM.form_lagranges_equations()

1. Using the Linearizer class directly:

A Linearizer object can be formed from a LagrangesMethod object using the to_linearizer
class method. The only difference between this process and that of the KanesMethod class is
that the LagrangesMethod object doesn’t already have its independent and dependent coordi-
nates and speeds specified internally. These must be specified in the call to to_linearizer.
In this example there are no dependent coordinates and speeds, but if there were they would
be included in the q_dep and qd_dep kwargs:

>>> linearizer = LM.to_linearizer(q_ind=[q1], qd_ind=[q1d])

1644 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Once in this form, everything is the same as it was before with the KanesMethod example:

>>> A, B = linearizer.linearize(A_and_B=True, op_point=op_point)

>>> A
Matrix([
[ 0, 1],
[-g/L, 0]])

2. Using the linearize class method:

Similar to KanesMethod, the LagrangesMethod class also provides a linearize method as a

nice wrapper that calls to_linearizer internally, performs the linearization, and returns the
result. As before, the only difference is that the independent and dependent coordinates and
speeds must be specified in the call as well:

>>> A, B, inp_vec = LM.linearize(q_ind=[q1], qd_ind=[q1d], A_and_B=True, op_point=op_

,→point)

>>> A
Matrix([
[ 0, 1],
[-g/L, 0]])

Potential Issues

While the Linearizer class should be able to linearize all systems, there are some potential
issues that could occur. These are discussed below, along with some troubleshooting tips for
solving them.

1. Symbolic linearization with A_and_B=True is slow

This could be due to a number of things, but the most likely one is that solving a large linear
system symbolically is an expensive operation. Specifying an operating point will reduce
the expression size and speed this up. If a purely symbolic solution is desired though (for
application of many operating points at a later period, for example) a way to get around
this is to evaluate with A_and_B=False, and then solve manually after applying the operating
point:

>>> M, A, B = linearizer.linearize()
>>> M_op = msubs(M, op_point)
>>> A_op = msubs(A, op_point)
>>> perm_mat = linearizer.perm_mat
>>> A_lin = perm_mat.T * M_op.LUsolve(A_op)
>>> A_lin
Matrix([
[ 0, 1],
[-g/L, 0]])

The fewer symbols in A and M before solving, the faster this solution will be. Thus, for large
expressions, it may be to your benefit to delay conversion to the A and B form until most
symbols are subbed in for their numeric values.

5.40. Physics Module 1645

SymPy Documentation, Release 1.3

2. The linearized form has nan, zoo, or oo as matrix elements

There are two potential causes for this. The first (and the one you should check first) is that
some choices of dependent coordinates will result in singularities at certain operating points.
Coordinate partitioning in a systemic manner to avoid this is beyond the scope of this guide;
see [Blajer1994] for more information.
The other potential cause for this is that the matrices may not have been in the most reduced
form before the operating point was substituted in. A simple example of this behavior is:

>>> from sympy import sin, tan

>>> expr = sin(q1)/tan(q1)
>>> op_point = {q1: 0}
>>> expr.subs(op_point)
nan

Note that if this expression was simplified before substitution, the correct value results:

>>> expr.simplify().subs(op_point)
1

A good way of avoiding this hasn’t been found yet. For expressions of reasonable size, using
msubs with smart=True will apply an algorithm that tries to avoid these conditions. For large
expressions though this is extremely time consuming.

>>> msubs(expr, op_point, smart=True)

1

Further Examples

The pendulum example used above was simple, but didn’t include any dependent coordinates
or speeds. For a more thorough example, the same pendulum was linearized with dependent
coordinates using both Kane’s and Lagrange’s methods:

Nonminimal Coordinates Pendulum

In this example we demonstrate the use of the functionality provided in mechanics for deriving
the equations of motion (EOM) for a pendulum with a nonminimal set of coordinates. As the
pendulum is a one degree of freedom system, it can be described using one coordinate and
one speed (the pendulum angle, and the angular velocity respectively). Choosing instead to
describe the system using the x and y coordinates of the mass results in a need for constraints.
The system is shown below:

1646 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Ay
Ny
Ax
Nx g

q1 L

q2 u2
m
u1
The system will be modeled using both Kane’s and Lagrange’s methods, and the resulting
EOM linearized. While this is a simple problem, it should illustrate the use of the linearization
methods in the presence of constraints.

Kane’s Method

First we need to create the dynamicsymbols needed to describe the system as shown in the
above diagram. In this case, the generalized coordinates q1 and q2 represent the mass x and
y coordinates in the inertial N frame. Likewise, the generalized speeds u1 and u2 represent
the velocities in these directions. We also create some symbols to represent the length and
mass of the pendulum, as well as gravity and time.

>>> from sympy.physics.mechanics import *

>>> from sympy import symbols, atan, Matrix, solve
>>> # Create generalized coordinates and speeds for this non-minimal realization
>>> # q1, q2 = N.x and N.y coordinates of pendulum
>>> # u1, u2 = N.x and N.y velocities of pendulum
>>> q1, q2 = dynamicsymbols('q1:3')
>>> q1d, q2d = dynamicsymbols('q1:3', level=1)
>>> u1, u2 = dynamicsymbols('u1:3')
>>> u1d, u2d = dynamicsymbols('u1:3', level=1)
>>> L, m, g, t = symbols('L, m, g, t')

Next, we create a world coordinate frame N , and its origin point N ∗ . The velocity of the origin
is set to 0. A second coordinate frame A is oriented such that its x-axis is along the pendulum

5.40. Physics Module 1647

SymPy Documentation, Release 1.3

(as shown in the diagram above).

>>> # Compose world frame

>>> N = ReferenceFrame('N')
>>> pN = Point('N*')
>>> pN.set_vel(N, 0)

>>> # A.x is along the pendulum

>>> theta1 = atan(q2/q1)
>>> A = N.orientnew('A', 'axis', [theta1, N.z])

Locating the pendulum mass is then as easy as specifying its location with in terms of its x
and y coordinates in the world frame. A Particle object is then created to represent the
mass at this location.

>>> # Locate the pendulum mass

>>> P = pN.locatenew('P1', q1*N.x + q2*N.y)
>>> pP = Particle('pP', P, m)

The kinematic differential equations (KDEs) relate the derivatives of the generalized coor-
dinates to the generalized speeds. In this case the speeds are the derivatives, so these are
simple. A dictionary is also created to map q̇ to u:

>>> # Calculate the kinematic differential equations

>>> kde = Matrix([q1d - u1,
... q2d - u2])
>>> dq_dict = solve(kde, [q1d, q2d])

The velocity of the mass is then the time derivative of the position from the origin N ∗ :

>>> # Set velocity of point P

>>> P.set_vel(N, P.pos_from(pN).dt(N).subs(dq_dict))

As this system has more coordinates than degrees of freedom, constraints are needed. The
configuration constraints relate the coordinates to each other. In this case the constraint is
that the distance from the origin to the mass is always the length L (the pendulum doesn’t
get longer). Likewise, the velocity constraint is that the mass velocity in the A.x direction is
always 0 (no radial velocity).

>>> f_c = Matrix([P.pos_from(pN).magnitude() - L])

>>> f_v = Matrix([P.vel(N).express(A).dot(A.x)])
>>> f_v.simplify()

The force on the system is just gravity, at point P.

>>> # Input the force resultant at P

>>> R = m*g*N.x

With the problem setup, the equations of motion can be generated using the KanesMethod
class. As there are constraints, dependent and independent coordinates need to be provided
to the class. In this case we’ll use q2 and u2 as the independent coordinates and speeds:

>>> # Derive the equations of motion using the KanesMethod class.

>>> KM = KanesMethod(N, q_ind=[q2], u_ind=[u2], q_dependent=[q1],
... u_dependent=[u1], configuration_constraints=f_c,
... velocity_constraints=f_v, kd_eqs=kde)
>>> (fr, frstar) = KM.kanes_equations([pP],[(P, R)])

1648 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

For linearization, operating points can be specified on the call, or be substituted in after-
wards. In this case we’ll provide them in the call, supplied in a list. The A_and_B=True kwarg
indicates to solve invert the M matrix and solve for just the explicit linearized A and B ma-
trices. The simplify=True kwarg indicates to simplify inside the linearize call, and return
the presimplified matrices. The cost of doing this is small for simple systems, but for larger
systems this can be a costly operation, and should be avoided.

>>> # Set the operating point to be straight down, and non-moving

>>> q_op = {q1: L, q2: 0}
>>> u_op = {u1: 0, u2: 0}
>>> ud_op = {u1d: 0, u2d: 0}
>>> # Perform the linearization
>>> A, B, inp_vec = KM.linearize(op_point=[q_op, u_op, ud_op], A_and_B=True,
... new_method=True, simplify=True)
>>> A
Matrix([
[ 0, 1],
[-g/L, 0]])
>>> B
Matrix(0, 0, [])

The resulting A matrix has dimensions 2 x 2, while the number of total states is len(q) +
len(u) = 2 + 2 = 4. This is because for constrained systems the resulting A_and_B form has
a partitioned state vector only containing the independent coordinates and speeds. Written
out mathematically, the system linearized about this point would be written as:
[ ] [ ][ ]
q˙2 0 1 q2
= −g
u˙2 L 0 u2

Lagrange’s Method

The derivation using Lagrange’s method is very similar to the approach using Kane’s method
described above. As before, we first create the dynamicsymbols needed to describe the sys-
tem. In this case, the generalized coordinates q1 and q2 represent the mass x and y coordinates
in the inertial N frame. This results in the time derivatives q˙1 and q˙2 representing the veloc-
ities in these directions. We also create some symbols to represent the length and mass of
the pendulum, as well as gravity and time.

>>> from sympy.physics.mechanics import *

>>> from sympy import symbols, atan, Matrix
>>> q1, q2 = dynamicsymbols('q1:3')
>>> q1d, q2d = dynamicsymbols('q1:3', level=1)
>>> L, m, g, t = symbols('L, m, g, t')

Next, we create a world coordinate frame N , and its origin point N ∗ . The velocity of the origin
is set to 0. A second coordinate frame A is oriented such that its x-axis is along the pendulum
(as shown in the diagram above).

>>> # Compose World Frame

>>> N = ReferenceFrame('N')
>>> pN = Point('N*')
>>> pN.set_vel(N, 0)
>>> # A.x is along the pendulum
>>> theta1 = atan(q2/q1)
>>> A = N.orientnew('A', 'axis', [theta1, N.z])

5.40. Physics Module 1649

SymPy Documentation, Release 1.3

Locating the pendulum mass is then as easy as specifying its location with in terms of its x
and y coordinates in the world frame. A Particle object is then created to represent the
mass at this location.

>>> # Create point P, the pendulum mass

>>> P = pN.locatenew('P1', q1*N.x + q2*N.y)
>>> P.set_vel(N, P.pos_from(pN).dt(N))
>>> pP = Particle('pP', P, m)

As this system has more coordinates than degrees of freedom, constraints are needed. In this
case only a single holonomic constraints is needed: the distance from the origin to the mass
is always the length L (the pendulum doesn’t get longer).

>>> # Holonomic Constraint Equations

>>> f_c = Matrix([q1**2 + q2**2 - L**2])

The force on the system is just gravity, at point P.

>>> # Input the force resultant at P

>>> R = m*g*N.x

With the problem setup, the Lagrangian can be calculated, and the equations of motion
formed. Note that the call to LagrangesMethod includes the Lagrangian, the generalized
coordinates, the constraints (specified by hol_coneqs or nonhol_coneqs), the list of (body,
force) pairs, and the inertial frame. In contrast to the KanesMethod initializer, independent
and dependent coordinates are not partitioned inside the LagrangesMethod object. Such a
partition is supplied later.

>>> # Calculate the lagrangian, and form the equations of motion

>>> Lag = Lagrangian(N, pP)
>>> LM = LagrangesMethod(Lag, [q1, q2], hol_coneqs=f_c, forcelist=[(P, R)], frame=N)
>>> lag_eqs = LM.form_lagranges_equations()

Next, we compose the operating point dictionary, set in the hanging at rest position:

>>> # Compose operating point

>>> op_point = {q1: L, q2: 0, q1d: 0, q2d: 0, q1d.diff(t): 0, q2d.diff(t): 0}

As there are constraints in the formulation, there will be corresponding Lagrange Multipliers.
These may appear inside the linearized form as well, and thus should also be included inside
the operating point dictionary. Fortunately, the LagrangesMethod class provides an easy way
of solving for the multipliers at a given operating point using the solve_multipliers method.

>>> # Solve for multiplier operating point

>>> lam_op = LM.solve_multipliers(op_point=op_point)

With this solution, linearization can be completed. Note that in contrast to the KanesMethod
approach, the LagrangesMethod.linearize method also requires the partitioning of the gen-
eralized coordinates and their time derivatives into independent and dependent vectors. This
is the same as what was passed into the KanesMethod constructor above:

>>> op_point.update(lam_op)
>>> # Perform the Linearization
>>> A, B, inp_vec = LM.linearize([q2], [q2d], [q1], [q1d],
... op_point=op_point, A_and_B=True)
>>> A
(continues on next page)

1650 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

Matrix([
[ 0, 1],
[-g/L, 0]])
>>> B
Matrix(0, 0, [])

The resulting A matrix has dimensions 2 x 2, while the number of total states is 2*len(q)
= 4. This is because for constrained systems the resulting A_and_B form has a partitioned
state vector only containing the independent coordinates and their derivatives. Written out
mathematically, the system linearized about this point would be written as:
[ ] [ ][ ]
q˙2 0 1 q2
= −g
q¨2 L 0 q˙2

Examples for Physics/Mechanics

Here are some examples that illustrate how one typically uses this module. We have ordered
the examples roughly according to increasing difficulty. If you have used this module to do
something others might find useful or interesting, consider adding it here!

A rolling disc

The disc is assumed to be infinitely thin, in contact with the ground at only 1 point, and it is
rolling without slip on the ground. See the image below.

nz
N ny

R
rz
ry

rx

nx
We model the rolling disc in three different ways, to show more of the functionality of this
module.

5.40. Physics Module 1651

SymPy Documentation, Release 1.3

A rolling disc, with Kane’s method

Here the definition of the rolling disc’s kinematics is formed from the contact point up, remov-
ing the need to introduce generalized speeds. Only 3 configuration and three speed variables
are need to describe this system, along with the disc’s mass and radius, and the local gravity
(note that mass will drop out).

>>> from sympy import symbols, sin, cos, tan

>>> from sympy.physics.mechanics import *
>>> q1, q2, q3, u1, u2, u3 = dynamicsymbols('q1 q2 q3 u1 u2 u3')
>>> q1d, q2d, q3d, u1d, u2d, u3d = dynamicsymbols('q1 q2 q3 u1 u2 u3', 1)
>>> r, m, g = symbols('r m g')
>>> mechanics_printing(pretty_print=False)

The kinematics are formed by a series of simple rotations. Each simple rotation creates a new
frame, and the next rotation is defined by the new frame’s basis vectors. This example uses a
3-1-2 series of rotations, or Z, X, Y series of rotations. Angular velocity for this is defined using
the second frame’s basis (the lean frame); it is for this reason that we defined intermediate
frames, rather than using a body-three orientation.

>>> N = ReferenceFrame('N')
>>> Y = N.orientnew('Y', 'Axis', [q1, N.z])
>>> L = Y.orientnew('L', 'Axis', [q2, Y.x])
>>> R = L.orientnew('R', 'Axis', [q3, L.y])
>>> w_R_N_qd = R.ang_vel_in(N)
>>> R.set_ang_vel(N, u1 * L.x + u2 * L.y + u3 * L.z)

This is the translational kinematics. We create a point with no velocity in N; this is the contact
point between the disc and ground. Next we form the position vector from the contact point
to the disc’s center of mass. Finally we form the velocity and acceleration of the disc.

>>> C = Point('C')
>>> C.set_vel(N, 0)
>>> Dmc = C.locatenew('Dmc', r * L.z)
>>> Dmc.v2pt_theory(C, N, R)
r*u2*L.x - r*u1*L.y

This is a simple way to form the inertia dyadic. The inertia of the disc does not change within
the lean frame as the disc rolls; this will make for simpler equations in the end.

>>> I = inertia(L, m / 4 * r**2, m / 2 * r**2, m / 4 * r**2)

>>> mprint(I)
m*r**2/4*(L.x|L.x) + m*r**2/2*(L.y|L.y) + m*r**2/4*(L.z|L.z)

Kinematic differential equations; how the generalized coordinate time derivatives relate to
generalized speeds.

>>> kd = [dot(R.ang_vel_in(N) - w_R_N_qd, uv) for uv in L]

Creation of the force list; it is the gravitational force at the center of mass of the disc. Then
we create the disc by assigning a Point to the center of mass attribute, a ReferenceFrame to
the frame attribute, and mass and inertia. Then we form the body list.

>>> ForceList = [(Dmc, - m * g * Y.z)]

>>> BodyD = RigidBody('BodyD', Dmc, R, m, (I, Dmc))
>>> BodyList = [BodyD]

1652 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Finally we form the equations of motion, using the same steps we did before. Specify inertial
frame, supply generalized coordinates and speeds, supply kinematic differential equation dic-
tionary, compute Fr from the force list and Fr* from the body list, compute the mass matrix
and forcing terms, then solve for the u dots (time derivatives of the generalized speeds).
>>> KM = KanesMethod(N, q_ind=[q1, q2, q3], u_ind=[u1, u2, u3], kd_eqs=kd)
>>> (fr, frstar) = KM.kanes_equations(BodyList, ForceList)
>>> MM = KM.mass_matrix
>>> forcing = KM.forcing
>>> rhs = MM.inv() * forcing
>>> kdd = KM.kindiffdict()
>>> rhs = rhs.subs(kdd)
>>> rhs.simplify()
>>> mprint(rhs)
Matrix([
[(4*g*sin(q2) + 6*r*u2*u3 - r*u3**2*tan(q2))/(5*r)],
[ -2*u1*u3/3],
[ (-2*u2 + u3*tan(q2))*u1]])

A rolling disc, with Kane’s method and constraint forces

We will now revisit the rolling disc example, except this time we are bringing the non-
contributing (constraint) forces into evidence. See [Kane1985] for a more thorough expla-
nation of this. Here, we will turn on the automatic simplifcation done when doing vector
operations. It makes the outputs nicer for small problems, but can cause larger vector oper-
ations to hang.
>>> from sympy import symbols, sin, cos, tan
>>> from sympy.physics.mechanics import *
>>> mechanics_printing(pretty_print=False)
>>> q1, q2, q3, u1, u2, u3 = dynamicsymbols('q1 q2 q3 u1 u2 u3')
>>> q1d, q2d, q3d, u1d, u2d, u3d = dynamicsymbols('q1 q2 q3 u1 u2 u3', 1)
>>> r, m, g = symbols('r m g')

These two lines introduce the extra quantities needed to find the constraint forces.
>>> u4, u5, u6, f1, f2, f3 = dynamicsymbols('u4 u5 u6 f1 f2 f3')

Most of the main code is the same as before.

>>> N = ReferenceFrame('N')
>>> Y = N.orientnew('Y', 'Axis', [q1, N.z])
>>> L = Y.orientnew('L', 'Axis', [q2, Y.x])
>>> R = L.orientnew('R', 'Axis', [q3, L.y])
>>> w_R_N_qd = R.ang_vel_in(N)
>>> R.set_ang_vel(N, u1 * L.x + u2 * L.y + u3 * L.z)

The definition of rolling without slip necessitates that the velocity of the contact point is zero;
as part of bringing the constraint forces into evidence, we have to introduce speeds at this
point, which will by definition always be zero. They are normal to the ground, along the path
which the disc is rolling, and along the ground in a perpendicular direction.
>>> C = Point('C')
>>> C.set_vel(N, u4 * L.x + u5 * (Y.z ^ L.x) + u6 * Y.z)
>>> Dmc = C.locatenew('Dmc', r * L.z)
(continues on next page)

5.40. Physics Module 1653

SymPy Documentation, Release 1.3

(continued from previous page)

>>> vel = Dmc.v2pt_theory(C, N, R)
>>> I = inertia(L, m / 4 * r**2, m / 2 * r**2, m / 4 * r**2)
>>> kd = [dot(R.ang_vel_in(N) - w_R_N_qd, uv) for uv in L]

Just as we previously introduced three speeds as part of this process, we also introduce three
forces; they are in the same direction as the speeds, and represent the constraint forces in
those directions.

>>> ForceList = [(Dmc, - m * g * Y.z), (C, f1 * L.x + f2 * (Y.z ^ L.x) + f3 * Y.z)]

>>> BodyD = RigidBody('BodyD', Dmc, R, m, (I, Dmc))
>>> BodyList = [BodyD]

>>> KM = KanesMethod(N, q_ind=[q1, q2, q3], u_ind=[u1, u2, u3], kd_eqs=kd,

... u_auxiliary=[u4, u5, u6])
>>> (fr, frstar) = KM.kanes_equations(BodyList, ForceList)
>>> MM = KM.mass_matrix
>>> forcing = KM.forcing
>>> rhs = MM.inv() * forcing
>>> kdd = KM.kindiffdict()
>>> rhs = rhs.subs(kdd)
>>> rhs.simplify()
>>> mprint(rhs)
Matrix([
[(4*g*sin(q2) + 6*r*u2*u3 - r*u3**2*tan(q2))/(5*r)],
[ -2*u1*u3/3],
[ (-2*u2 + u3*tan(q2))*u1]])
>>> from sympy import trigsimp, signsimp, collect, factor_terms
>>> def simplify_auxiliary_eqs(w):
... return signsimp(trigsimp(collect(collect(factor_terms(w), f2), m*r)))
>>> mprint(KM.auxiliary_eqs.applyfunc(simplify_auxiliary_eqs))
Matrix([
[ -m*r*(u1*u3 + u2') + f1],
[-m*r*u1**2*sin(q2) - m*r*u2*u3/cos(q2) + m*r*cos(q2)*u1' + f2],
[ -g*m + m*r*(u1**2*cos(q2) + sin(q2)*u1') + f3]])

A rolling disc using Lagrange’s Method

Here the rolling disc is formed from the contact point up, removing the need to introduce
generalized speeds. Only 3 configuration and 3 speed variables are needed to describe this
system, along with the disc’s mass and radius, and the local gravity.

>>> from sympy import symbols, cos, sin

>>> from sympy.physics.mechanics import *
>>> mechanics_printing(pretty_print=False)
>>> q1, q2, q3 = dynamicsymbols('q1 q2 q3')
>>> q1d, q2d, q3d = dynamicsymbols('q1 q2 q3', 1)
>>> r, m, g = symbols('r m g')

The kinematics are formed by a series of simple rotations. Each simple rotation creates a new
frame, and the next rotation is defined by the new frame’s basis vectors. This example uses
a 3-1-2 series of rotations, or Z, X, Y series of rotations. Angular velocity for this is defined
using the second frame’s basis (the lean frame).

1654 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> N = ReferenceFrame('N')
>>> Y = N.orientnew('Y', 'Axis', [q1, N.z])
>>> L = Y.orientnew('L', 'Axis', [q2, Y.x])
>>> R = L.orientnew('R', 'Axis', [q3, L.y])

This is the translational kinematics. We create a point with no velocity in N; this is the contact
point between the disc and ground. Next we form the position vector from the contact point
to the disc’s center of mass. Finally we form the velocity and acceleration of the disc.
>>> C = Point('C')
>>> C.set_vel(N, 0)
>>> Dmc = C.locatenew('Dmc', r * L.z)
>>> Dmc.v2pt_theory(C, N, R)
r*(sin(q2)*q1' + q3')*L.x - r*q2'*L.y

Forming the inertia dyadic.

>>> I = inertia(L, m / 4 * r**2, m / 2 * r**2, m / 4 * r**2)
>>> mprint(I)
m*r**2/4*(L.x|L.x) + m*r**2/2*(L.y|L.y) + m*r**2/4*(L.z|L.z)
>>> BodyD = RigidBody('BodyD', Dmc, R, m, (I, Dmc))

We then set the potential energy and determine the Lagrangian of the rolling disc.
>>> BodyD.potential_energy = - m * g * r * cos(q2)
>>> Lag = Lagrangian(N, BodyD)

Then the equations of motion are generated by initializing the LagrangesMethod object. Fi-
nally we solve for the generalized accelerations(q double dots) with the rhs method.
>>> q = [q1, q2, q3]
>>> l = LagrangesMethod(Lag, q)
>>> le = l.form_lagranges_equations()
>>> le = le.simplify()
>>> le
Matrix([
[m*r**2*(6*sin(q2)*q3'' + 5*sin(2*q2)*q1'*q2' + 6*cos(q2)*q2'*q3' - 5*cos(2*q2)*q1''/
,→2 + 7*q1''/2)/4],

[ m*r*(4*g*sin(q2) - 5*r*sin(2*q2)*q1'**2/2 - 6*r*cos(q2)*q1'*q3

,→' + 5*r*q2'')/4],

[ 3*m*r**2*(sin(q2)*q1'' + cos(q2)*q1
,→'*q2' + q3'')/2]])

>>> lrhs = l.rhs().simplify()

>>> lrhs
Matrix([
[ q1'],
[ q2'],
[ q3'],
[ -2*(2*tan(q2)*q1' + 3*q3'/cos(q2))*q2'],
[-4*g*sin(q2)/(5*r) + sin(2*q2)*q1'**2/2 + 6*cos(q2)*q1'*q3'/5],
[ (-5*cos(q2)*q1' + 6*tan(q2)*q3' + 4*q1'/cos(q2))*q2']])

A bicycle

The bicycle is an interesting system in that it has multiple rigid bodies, non-holonomic con-
straints, and a holonomic constraint. The linearized equations of motion are presented in

5.40. Physics Module 1655

SymPy Documentation, Release 1.3

[Meijaard2007]. This example will go through construction of the equations of motion in

mechanics.
>>> from sympy import *
>>> from sympy.physics.mechanics import *
>>> print('Calculation of Linearized Bicycle \”A\” Matrix, '
... 'with States: Roll, Steer, Roll Rate, Steer Rate')
Calculation of Linearized Bicycle ”A” Matrix, with States: Roll, Steer, Roll Rate,␣
,→Steer Rate

Note that this code has been crudely ported from Autolev, which is the reason for some of the
unusual naming conventions. It was purposefully as similar as possible in order to aid initial
porting & debugging. We set Vector.simp to False (in case it has been set True elsewhere),
since it slows down the computations:
>>> Vector.simp = False
>>> mechanics_printing(pretty_print=False)

Declaration of Coordinates & Speeds: A simple definition for qdots, qd = u,is used in this
code. Speeds are: yaw frame ang. rate, roll frame ang. rate, rear wheel frame ang. rate
(spinning motion), frame ang. rate (pitching motion), steering frame ang. rate, and front
wheel ang. rate (spinning motion). Wheel positions are ignorable coordinates, so they are
not introduced.
>>> q1, q2, q3, q4, q5 = dynamicsymbols('q1 q2 q3 q4 q5')
>>> q1d, q2d, q4d, q5d = dynamicsymbols('q1 q2 q4 q5', 1)
>>> u1, u2, u3, u4, u5, u6 = dynamicsymbols('u1 u2 u3 u4 u5 u6')
>>> u1d, u2d, u3d, u4d, u5d, u6d = dynamicsymbols('u1 u2 u3 u4 u5 u6', 1)

Declaration of System’s Parameters: The below symbols should be fairly self-explanatory.

>>> WFrad, WRrad, htangle, forkoffset = symbols('WFrad WRrad htangle forkoffset')
>>> forklength, framelength, forkcg1 = symbols('forklength framelength forkcg1')
>>> forkcg3, framecg1, framecg3, Iwr11 = symbols('forkcg3 framecg1 framecg3 Iwr11')
>>> Iwr22, Iwf11, Iwf22, Iframe11 = symbols('Iwr22 Iwf11 Iwf22 Iframe11')
>>> Iframe22, Iframe33, Iframe31, Ifork11 = \
... symbols('Iframe22 Iframe33 Iframe31 Ifork11')
>>> Ifork22, Ifork33, Ifork31, g = symbols('Ifork22 Ifork33 Ifork31 g')
>>> mframe, mfork, mwf, mwr = symbols('mframe mfork mwf mwr')

Set up reference frames for the system: N - inertial Y - yaw R - roll WR - rear wheel, rotation
angle is ignorable coordinate so not oriented Frame - bicycle frame TempFrame - statically
rotated frame for easier reference inertia definition Fork - bicycle fork TempFork - statically
rotated frame for easier reference inertia definition WF - front wheel, again posses an ignor-
able coordinate
>>> N = ReferenceFrame('N')
>>> Y = N.orientnew('Y', 'Axis', [q1, N.z])
>>> R = Y.orientnew('R', 'Axis', [q2, Y.x])
>>> Frame = R.orientnew('Frame', 'Axis', [q4 + htangle, R.y])
>>> WR = ReferenceFrame('WR')
>>> TempFrame = Frame.orientnew('TempFrame', 'Axis', [-htangle, Frame.y])
>>> Fork = Frame.orientnew('Fork', 'Axis', [q5, Frame.x])
>>> TempFork = Fork.orientnew('TempFork', 'Axis', [-htangle, Fork.y])
>>> WF = ReferenceFrame('WF')

Kinematics of the Bicycle: First block of code is forming the positions of the relevant points
rear wheel contact -> rear wheel’s center of mass -> frame’s center of mass + frame/fork

1656 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

connection -> fork’s center of mass + front wheel’s center of mass -> front wheel contact
point.

>>> WR_cont = Point('WR_cont')

>>> WR_mc = WR_cont.locatenew('WR_mc', WRrad * R.z)
>>> Steer = WR_mc.locatenew('Steer', framelength * Frame.z)
>>> Frame_mc = WR_mc.locatenew('Frame_mc', -framecg1 * Frame.x + framecg3 * Frame.z)
>>> Fork_mc = Steer.locatenew('Fork_mc', -forkcg1 * Fork.x + forkcg3 * Fork.z)
>>> WF_mc = Steer.locatenew('WF_mc', forklength * Fork.x + forkoffset * Fork.z)
>>> WF_cont = WF_mc.locatenew('WF_cont', WFrad*(dot(Fork.y, Y.z)*Fork.y - \
... Y.z).normalize())

Set the angular velocity of each frame: Angular accelerations end up being calculated auto-
matically by differentiating the angular velocities when first needed. :: u1 is yaw rate u2 is
roll rate u3 is rear wheel rate u4 is frame pitch rate u5 is fork steer rate u6 is front wheel
rate

>>> Y.set_ang_vel(N, u1 * Y.z)

>>> R.set_ang_vel(Y, u2 * R.x)
>>> WR.set_ang_vel(Frame, u3 * Frame.y)
>>> Frame.set_ang_vel(R, u4 * Frame.y)
>>> Fork.set_ang_vel(Frame, u5 * Fork.x)
>>> WF.set_ang_vel(Fork, u6 * Fork.y)

Form the velocities of the points, using the 2-point theorem. Accelerations again are calcu-
lated automatically when first needed.

>>> WR_cont.set_vel(N, 0)
>>> WR_mc.v2pt_theory(WR_cont, N, WR)
WRrad*(u1*sin(q2) + u3 + u4)*R.x - WRrad*u2*R.y
>>> Steer.v2pt_theory(WR_mc, N, Frame)
WRrad*(u1*sin(q2) + u3 + u4)*R.x - WRrad*u2*R.y + framelength*(u1*sin(q2) + u4)*Frame.
,→x - framelength*(-u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4))*Frame.y

>>> Frame_mc.v2pt_theory(WR_mc, N, Frame)

WRrad*(u1*sin(q2) + u3 + u4)*R.x - WRrad*u2*R.y + framecg3*(u1*sin(q2) + u4)*Frame.x␣
,→+ (-framecg1*(u1*cos(htangle + q4)*cos(q2) + u2*sin(htangle + q4)) - framecg3*(-

,→u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4)))*Frame.y +␣

,→framecg1*(u1*sin(q2) + u4)*Frame.z

>>> Fork_mc.v2pt_theory(Steer, N, Fork)

WRrad*(u1*sin(q2) + u3 + u4)*R.x - WRrad*u2*R.y + framelength*(u1*sin(q2) + u4)*Frame.
,→x - framelength*(-u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4))*Frame.y +␣

,→forkcg3*((sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2))*u1 + u2*sin(htangle␣

,→+ q4)*sin(q5) + u4*cos(q5))*Fork.x + (-forkcg1*((-sin(q2)*sin(q5) + cos(htangle +␣

,→q4)*cos(q2)*cos(q5))*u1 + u2*sin(htangle + q4)*cos(q5) - u4*sin(q5)) - forkcg3*(-

,→u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4) + u5))*Fork.y +␣

,→forkcg1*((sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2))*u1 + u2*sin(htangle␣

,→+ q4)*sin(q5) + u4*cos(q5))*Fork.z

>>> WF_mc.v2pt_theory(Steer, N, Fork)

WRrad*(u1*sin(q2) + u3 + u4)*R.x - WRrad*u2*R.y + framelength*(u1*sin(q2) + u4)*Frame.
,→x - framelength*(-u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4))*Frame.y +␣

,→forkoffset*((sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2))*u1 +␣

,→u2*sin(htangle + q4)*sin(q5) + u4*cos(q5))*Fork.x + (forklength*((-sin(q2)*sin(q5)␣

,→+ cos(htangle + q4)*cos(q2)*cos(q5))*u1 + u2*sin(htangle + q4)*cos(q5) -␣

,→u4*sin(q5)) - forkoffset*(-u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4) +␣

,→u5))*Fork.y - forklength*((sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2))*u1␣

,→+ u2*sin(htangle + q4)*sin(q5) + u4*cos(q5))*Fork.z

>>> WF_cont.v2pt_theory(WF_mc, N, WF)

(continues on next page)

5.40. Physics Module 1657

SymPy Documentation, Release 1.3

(continued from previous page)

- WFrad*((-sin(q2)*sin(q5)*cos(htangle + q4) + cos(q2)*cos(q5))*u6 + u4*cos(q2) +␣
,→u5*sin(htangle + q4)*sin(q2))/sqrt((-sin(q2)*cos(q5) - sin(q5)*cos(htangle +␣

,→q4)*cos(q2))*(sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2)) + 1)*Y.x +␣

,→WFrad*(u2 + u5*cos(htangle + q4) + u6*sin(htangle + q4)*sin(q5))/sqrt((-

,→sin(q2)*cos(q5) - sin(q5)*cos(htangle + q4)*cos(q2))*(sin(q2)*cos(q5) +␣

,→sin(q5)*cos(htangle + q4)*cos(q2)) + 1)*Y.y + WRrad*(u1*sin(q2) + u3 + u4)*R.x -␣

,→WRrad*u2*R.y + framelength*(u1*sin(q2) + u4)*Frame.x - framelength*(-u1*sin(htangle␣

,→+ q4)*cos(q2) + u2*cos(htangle + q4))*Frame.y + (-WFrad*(sin(q2)*cos(q5) +␣

,→sin(q5)*cos(htangle + q4)*cos(q2))*((-sin(q2)*sin(q5) + cos(htangle +␣

,→q4)*cos(q2)*cos(q5))*u1 + u2*sin(htangle + q4)*cos(q5) - u4*sin(q5))/sqrt((-

,→sin(q2)*cos(q5) - sin(q5)*cos(htangle + q4)*cos(q2))*(sin(q2)*cos(q5) +␣

,→sin(q5)*cos(htangle + q4)*cos(q2)) + 1) + forkoffset*((sin(q2)*cos(q5) +␣

,→sin(q5)*cos(htangle + q4)*cos(q2))*u1 + u2*sin(htangle + q4)*sin(q5) +␣

,→u4*cos(q5)))*Fork.x + (forklength*((-sin(q2)*sin(q5) + cos(htangle +␣

,→q4)*cos(q2)*cos(q5))*u1 + u2*sin(htangle + q4)*cos(q5) - u4*sin(q5)) - forkoffset*(-

,→u1*sin(htangle + q4)*cos(q2) + u2*cos(htangle + q4) + u5))*Fork.y +␣

,→(WFrad*(sin(q2)*cos(q5) + sin(q5)*cos(htangle + q4)*cos(q2))*(-u1*sin(htangle +␣

,→q4)*cos(q2) + u2*cos(htangle + q4) + u5)/sqrt((-sin(q2)*cos(q5) -␣

,→sin(q5)*cos(htangle + q4)*cos(q2))*(sin(q2)*cos(q5) + sin(q5)*cos(htangle +␣

,→q4)*cos(q2)) + 1) - forklength*((sin(q2)*cos(q5) + sin(q5)*cos(htangle +␣

,→q4)*cos(q2))*u1 + u2*sin(htangle + q4)*sin(q5) + u4*cos(q5)))*Fork.z

Sets the inertias of each body. Uses the inertia frame to construct the inertia dyadics. Wheel
inertias are only defined by principal moments of inertia, and are in fact constant in the frame
and fork reference frames; it is for this reason that the orientations of the wheels does not
need to be defined. The frame and fork inertias are defined in the ‘Temp’ frames which are
fixed to the appropriate body frames; this is to allow easier input of the reference values of
the benchmark paper. Note that due to slightly different orientations, the products of inertia
need to have their signs flipped; this is done later when entering the numerical value.

>>> Frame_I = (inertia(TempFrame, Iframe11, Iframe22, Iframe33, 0, 0,

... Iframe31), Frame_mc)
>>> Fork_I = (inertia(TempFork, Ifork11, Ifork22, Ifork33, 0, 0, Ifork31), Fork_mc)
>>> WR_I = (inertia(Frame, Iwr11, Iwr22, Iwr11), WR_mc)
>>> WF_I = (inertia(Fork, Iwf11, Iwf22, Iwf11), WF_mc)

Declaration of the RigidBody containers.

>>> BodyFrame = RigidBody('BodyFrame', Frame_mc, Frame, mframe, Frame_I)

>>> BodyFork = RigidBody('BodyFork', Fork_mc, Fork, mfork, Fork_I)
>>> BodyWR = RigidBody('BodyWR', WR_mc, WR, mwr, WR_I)
>>> BodyWF = RigidBody('BodyWF', WF_mc, WF, mwf, WF_I)

>>> print('Before Forming the List of Nonholonomic Constraints.')

Before Forming the List of Nonholonomic Constraints.

The kinematic differential equations; they are defined quite simply. Each entry in this list is
equal to zero.

>>> kd = [q1d - u1, q2d - u2, q4d - u4, q5d - u5]

The nonholonomic constraints are the velocity of the front wheel contact point dotted into the
X, Y, and Z directions; the yaw frame is used as it is “closer” to the front wheel (1 less DCM
connecting them). These constraints force the velocity of the front wheel contact point to be
0 in the inertial frame; the X and Y direction constraints enforce a “no-slip” condition, and the
Z direction constraint forces the front wheel contact point to not move away from the ground

1658 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

frame, essentially replicating the holonomic constraint which does not allow the frame pitch
to change in an invalid fashion.
>>> conlist_speed = [WF_cont.vel(N) & Y.x,
... WF_cont.vel(N) & Y.y,
... WF_cont.vel(N) & Y.z]

The holonomic constraint is that the position from the rear wheel contact point to the front
wheel contact point when dotted into the normal-to-ground plane direction must be zero;
effectively that the front and rear wheel contact points are always touching the ground plane.
This is actually not part of the dynamic equations, but instead is necessary for the linearization
process.
>>> conlist_coord = [WF_cont.pos_from(WR_cont) & Y.z]

The force list; each body has the appropriate gravitational force applied at its center of mass.
>>> FL = [(Frame_mc, -mframe * g * Y.z), (Fork_mc, -mfork * g * Y.z),
... (WF_mc, -mwf * g * Y.z), (WR_mc, -mwr * g * Y.z)]
>>> BL = [BodyFrame, BodyFork, BodyWR, BodyWF]

The N frame is the inertial frame, coordinates are supplied in the order of independent, de-
pendent coordinates. The kinematic differential equations are also entered here. Here the
independent speeds are specified, followed by the dependent speeds, along with the non-
holonomic constraints. The dependent coordinate is also provided, with the holonomic con-
straint. Again, this is only comes into play in the linearization process, but is necessary for
the linearization to correctly work.
>>> KM = KanesMethod(N, q_ind=[q1, q2, q5],
... q_dependent=[q4], configuration_constraints=conlist_coord,
... u_ind=[u2, u3, u5],
... u_dependent=[u1, u4, u6], velocity_constraints=conlist_speed,
... kd_eqs=kd)
>>> print('Before Forming Generalized Active and Inertia Forces, Fr and Fr*')
Before Forming Generalized Active and Inertia Forces, Fr and Fr*
>>> (fr, frstar) = KM.kanes_equations(BL, FL)
>>> print('Base Equations of Motion Computed')
Base Equations of Motion Computed

This is the start of entering in the numerical values from the benchmark paper to validate the
eigenvalues of the linearized equations from this model to the reference eigenvalues. Look
at the aforementioned paper for more information. Some of these are intermediate values,
used to transform values from the paper into the coordinate systems used in this model.
>>> PaperRadRear = 0.3
>>> PaperRadFront = 0.35
>>> HTA = evalf.N(pi/2-pi/10)
>>> TrailPaper = 0.08
>>> rake = evalf.N(-(TrailPaper*sin(HTA)-(PaperRadFront*cos(HTA))))
>>> PaperWb = 1.02
>>> PaperFrameCgX = 0.3
>>> PaperFrameCgZ = 0.9
>>> PaperForkCgX = 0.9
>>> PaperForkCgZ = 0.7
>>> FrameLength = evalf.N(PaperWb*sin(HTA) - (rake - \
... (PaperRadFront - PaperRadRear)*cos(HTA)))
>>> FrameCGNorm = evalf.N((PaperFrameCgZ - PaperRadRear - \
(continues on next page)

5.40. Physics Module 1659

SymPy Documentation, Release 1.3

(continued from previous page)

... (PaperFrameCgX/sin(HTA))*cos(HTA))*sin(HTA))
>>> FrameCGPar = evalf.N((PaperFrameCgX / sin(HTA) + \
... (PaperFrameCgZ - PaperRadRear - \
... PaperFrameCgX / sin(HTA) * cos(HTA)) * cos(HTA)))
>>> tempa = evalf.N((PaperForkCgZ - PaperRadFront))
>>> tempb = evalf.N((PaperWb-PaperForkCgX))
>>> tempc = evalf.N(sqrt(tempa**2 + tempb**2))
>>> PaperForkL = evalf.N((PaperWb*cos(HTA) - \
... (PaperRadFront - PaperRadRear)*sin(HTA)))
>>> ForkCGNorm = evalf.N(rake + (tempc * sin(pi/2 - \
... HTA - acos(tempa/tempc))))
>>> ForkCGPar = evalf.N(tempc * cos((pi/2 - HTA) - \
... acos(tempa/tempc)) - PaperForkL)

Here is the final assembly of the numerical values. The symbol ‘v’ is the forward speed of the
bicycle (a concept which only makes sense in the upright, static equilibrium case?). These
are in a dictionary which will later be substituted in. Again the sign on the product of inertia
values is flipped here, due to different orientations of coordinate systems.

>>> v = Symbol('v')
>>> val_dict = {
... WFrad: PaperRadFront,
... WRrad: PaperRadRear,
... htangle: HTA,
... forkoffset: rake,
... forklength: PaperForkL,
... framelength: FrameLength,
... forkcg1: ForkCGPar,
... forkcg3: ForkCGNorm,
... framecg1: FrameCGNorm,
... framecg3: FrameCGPar,
... Iwr11: 0.0603,
... Iwr22: 0.12,
... Iwf11: 0.1405,
... Iwf22: 0.28,
... Ifork11: 0.05892,
... Ifork22: 0.06,
... Ifork33: 0.00708,
... Ifork31: 0.00756,
... Iframe11: 9.2,
... Iframe22: 11,
... Iframe33: 2.8,
... Iframe31: -2.4,
... mfork: 4,
... mframe: 85,
... mwf: 3,
... mwr: 2,
... g: 9.81,
... q1: 0,
... q2: 0,
... q4: 0,
... q5: 0,
... u1: 0,
... u2: 0,
... u3: v/PaperRadRear,
... u4: 0,
(continues on next page)

1660 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

... u5: 0,
... u6: v/PaperRadFront}
>>> kdd = KM.kindiffdict()
>>> print('Before Linearization of the \”Forcing\” Term')
Before Linearization of the ”Forcing” Term

Linearizes the forcing vector; the equations are set up as MM udot = forcing, where MM is the
mass matrix, udot is the vector representing the time derivatives of the generalized speeds,
and forcing is a vector which contains both external forcing terms and internal forcing terms,
such as centripetal or Coriolis forces. This actually returns a matrix with as many rows as total
coordinates and speeds, but only as many columns as independent coordinates and speeds.
(Note that below this is commented out, as it takes a few minutes to run, which is not good
when performing the doctests)

>>> # forcing_lin = KM.linearize()[0].subs(sub_dict)

As mentioned above, the size of the linearized forcing terms is expanded to include both q’s
and u’s, so the mass matrix must have this done as well. This will likely be changed to be part
of the linearized process, for future reference.

>>> MM_full = (KM._k_kqdot).row_join(zeros(4, 6)).col_join(

... (zeros(6, 4)).row_join(KM.mass_matrix))
>>> print('Before Substitution of Numerical Values')
Before Substitution of Numerical Values

I think this is pretty self explanatory. It takes a really long time though. I’ve experimented with
using evalf with substitution, this failed due to maximum recursion depth being exceeded; I
also tried lambdifying this, and it is also not successful. (again commented out due to speed)

>>> # MM_full = MM_full.subs(val_dict)

>>> # forcing_lin = forcing_lin.subs(val_dict)
>>> # print('Before .evalf() call')

>>> # MM_full = MM_full.evalf()

>>> # forcing_lin = forcing_lin.evalf()

Finally, we construct an “A” matrix for the form xdot = A x (x being the state vector, although
in this case, the sizes are a little off). The following line extracts only the minimum entries
required for eigenvalue analysis, which correspond to rows and columns for lean, steer, lean
rate, and steer rate. (this is all commented out due to being dependent on the above code,
which is also commented out):

>>> # Amat = MM_full.inv() * forcing_lin

>>> # A = Amat.extract([1,2,4,6],[1,2,3,5])
>>> # print(A)
>>> # print('v = 1')
>>> # print(A.subs(v, 1).eigenvals())
>>> # print('v = 2')
>>> # print(A.subs(v, 2).eigenvals())
>>> # print('v = 3')
>>> # print(A.subs(v, 3).eigenvals())
>>> # print('v = 4')
>>> # print(A.subs(v, 4).eigenvals())
>>> # print('v = 5')
>>> # print(A.subs(v, 5).eigenvals())

5.40. Physics Module 1661

SymPy Documentation, Release 1.3

Upon running the above code yourself, enabling the commented out lines, compare the com-
puted eigenvalues to those is the referenced paper. This concludes the bicycle example.

Potential Issues/Advanced Topics/Future Features in Physics/Mechanics

This document will describe some of the more advanced functionality that this module offers
but which is not part of the “official” interface. Here, some of the features that will be im-
plemented in the future will also be covered, along with unanswered questions about proper
functionality. Also, common problems will be discussed, along with some solutions.

Common Issues

Here issues with numerically integrating code, choice of dynamicsymbols for coordinate and
speed representation, printing, differentiating, and substitution will occur.

Numerically Integrating Code

See Future Features: Code Output

Differentiating

Differentiation of very large expressions can take some time in SymPy; it is possible for large
expressions to take minutes for the derivative to be evaluated. This will most commonly come
up in linearization.

Choice of Coordinates and Speeds

The Kane object is set up with the assumption that the generalized speeds are not the same
symbol as the time derivatives of the generalized coordinates. This isn’t to say that they can’t
be the same, just that they have to have a different symbol. If you did this:

>> KM.coords([q1, q2, q3])

>> KM.speeds([q1d, q2d, q3d])

Your code would not work. Currently, kinematic differential equations are required to be
provided. It is at this point that we hope the user will discover they should not attempt the
behavior shown in the code above.
This behavior might not be true for other methods of forming the equations of motion though.

Printing

The default printing options are to use sorting for Vector and Dyad measure numbers, and
have unsorted output from the mprint, mpprint, and mlatex functions. If you are printing
something large, please use one of those functions, as the sorting can increase printing time
from seconds to minutes.

1662 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Substitution

There are two common issues with substitution in mechanics:

• When subbing in expressions for dynamicsymbols, sympy’s normal subs will substitute
in for derivatives of the dynamic symbol as well:

>>> from sympy.physics.mechanics import dynamicsymbols

>>> x = dynamicsymbols('x')
>>> expr = x.diff() + x
>>> sub_dict = {x: 1}
>>> expr.subs(sub_dict)
Derivative(1, t) + 1

In this case, x was replaced with 1 inside the Derivative as well, which is undesired.
• Substitution into large expressions can be slow.
If your substitution is simple (direct replacement of expressions with other expressions, such
as when evaluating at an operating point) it is recommended to use the provided msubs func-
tion, as it is significantly faster, and handles the derivative issue appropriately:

>>> from sympy.physics.mechanics import msubs

>>> msubs(expr, sub_dict)
Derivative(x(t), t) + 1

Linearization

Currently, the linearization methods don’t support cases where there are non-coordinate, non-
speed dynamic symbols outside of the “dynamic equations”. It also does not support cases
where time derivatives of these types of dynamic symbols show up. This means if you have
kinematic differential equations which have a non-coordinate, non-speed dynamic symbol, it
will not work. It also means if you have defined a system parameter (say a length or distance
or mass) as a dynamic symbol, its time derivative is likely to show up in the dynamic equations,
and this will prevent linearization.

Acceleration of Points

At a minimum, points need to have their velocities defined, as the acceleration can be calcu-
lated by taking the time derivative of the velocity in the same frame. If the 1 point or 2 point
theorems were used to compute the velocity, the time derivative of the velocity expression
will most likely be more complex than if you were to use the acceleration level 1 point and 2
point theorems. Using the acceleration level methods can result in shorted expressions at this
point, which will result in shorter expressions later (such as when forming Kane’s equations).

Advanced Interfaces

Advanced Functionality

Remember that the Kane object supports bodies which have time-varying masses and inertias,
although this functionality isn’t completely compatible with the linearization method.

5.40. Physics Module 1663

SymPy Documentation, Release 1.3

Operators were discussed earlier as a potential way to do mathematical operations on Vector

and Dyad objects. The majority of the code in this module is actually coded with them, as it
can (subjectively) result in cleaner, shorter, more readable code. If using this interface in
your code, remember to take care and use parentheses; the default order of operations in
Python results in addition occurring before some of the vector products, so use parentheses
liberally.

Future Features

This will cover the planned features to be added to this submodule.

Code Output

A function for generating code output for numerical integration is the highest priority feature
to implement next. There are a number of considerations here.
Code output for C (using the GSL libraries), Fortran 90 (using LSODA), MATLAB, and SciPy
is the goal. Things to be considered include: use of cse on large expressions for MATLAB and
SciPy, which are interpretive. It is currently unclear whether compiled languages will benefit
from common subexpression elimination, especially considering that it is a common part of
compiler optimization, and there can be a significant time penalty when calling cse.
Care needs to be taken when constructing the strings for these expressions, as well as han-
dling of input parameters, and other dynamic symbols. How to deal with output quantities
when integrating also needs to be decided, with the potential for multiple options being con-
sidered.

References for Physics/Mechanics

Autolev Parser

Introduction

Autolev (now superseded by MotionGenesis) is a domain specific language used for symbolic
multibody dynamics. The SymPy mechanics module now has enough power and functionality
to be a fully featured symbolic dynamics module. This parser parses Autolev (version 4.1)
code to SymPy code by making use of SymPy’s math libraries and the mechanics module.
The parser has been built using the ANTLR framework and its main purpose is to help former
users of Autolev to get familiarized with multibody dynamics in SymPy.
The sections below shall discuss details of the parser like usage, gotchas, issues and future
improvements. For a detailed comparison of Autolev and SymPy Mechanics you might want
to look at the SymPy Mechanics for Autolev Users guide (page 1673).

Usage

We first start with an Autolev code file.

Let us take this example (Comments % have been included to show the Autolev responses):

1664 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

% double_pendulum.al
%-------------------
MOTIONVARIABLES' Q{2}', U{2}'
CONSTANTS L,M,G
NEWTONIAN N
FRAMES A,B
SIMPROT(N, A, 3, Q1)
% -> N_A = [COS(Q1), -SIN(Q1), 0; SIN(Q1), COS(Q1), 0; 0, 0, 1]
SIMPROT(N, B, 3, Q2)
% -> N_B = [COS(Q2), -SIN(Q2), 0; SIN(Q2), COS(Q2), 0; 0, 0, 1]
W_A_N>=U1*N3>
% -> W_A_N> = U1*N3>
W_B_N>=U2*N3>
% -> W_B_N> = U2*N3>
POINT O
PARTICLES P,R
P_O_P> = L*A1>
% -> P_O_P> = L*A1>
P_P_R> = L*B1>
% -> P_P_R> = L*B1>
V_O_N> = 0>
% -> V_O_N> = 0>
V2PTS(N, A, O, P)
% -> V_P_N> = L*U1*A2>
V2PTS(N, B, P, R)
% -> V_R_N> = L*U1*A2> + L*U2*B2>
MASS P=M, R=M
Q1' = U1
Q2' = U2
GRAVITY(G*N1>)
% -> FORCE_P> = G*M*N1>
% -> FORCE_R> = G*M*N1>
ZERO = FR() + FRSTAR()
% -> ZERO[1] = -L*M*(2*G*SIN(Q1)+L*(U2^2*SIN(Q1-Q2)+2*U1'+COS(Q1-Q2)*U2'))
% -> ZERO[2] = -L*M*(G*SIN(Q2)-L*(U1^2*SIN(Q1-Q2)-U2'-COS(Q1-Q2)*U1'))
KANE()
INPUT M=1,G=9.81,L=1
INPUT Q1=.1,Q2=.2,U1=0,U2=0
INPUT TFINAL=10, INTEGSTP=.01
CODE DYNAMICS() some_filename.c

The parser can be used as follows:

>>> from sympy.parsing.autolev import parse_autolev

>>> sympy_code = parse_autolev(open('double_pendulum.al'), include_numeric=True)

# The include_pydy flag is False by default. Setting it to True will

# enable PyDy simulation code to be outputed if applicable.

>>> print(sympy_code)
import sympy.physics.mechanics as me
import sympy as sm
import math as m
import numpy as np

q1, q2, u1, u2 = me.dynamicsymbols('q1 q2 u1 u2')

q1d, q2d, u1d, u2d = me.dynamicsymbols('q1 q2 u1 u2', 1)
(continues on next page)

5.40. Physics Module 1665

SymPy Documentation, Release 1.3

(continued from previous page)

l, m, g=sm.symbols('l m g', real=True)
frame_n=me.ReferenceFrame('n')
frame_a=me.ReferenceFrame('a')
frame_b=me.ReferenceFrame('b')
frame_a.orient(frame_n, 'Axis', [q1, frame_n.z])
# print(frame_n.dcm(frame_a))
frame_b.orient(frame_n, 'Axis', [q2, frame_n.z])
# print(frame_n.dcm(frame_b))
frame_a.set_ang_vel(frame_n, u1*frame_n.z)
# print(frame_a.ang_vel_in(frame_n))
frame_b.set_ang_vel(frame_n, u2*frame_n.z)
# print(frame_b.ang_vel_in(frame_n))
point_o=me.Point('o')
particle_p=me.Particle('p', me.Point('p_pt'), sm.Symbol('m'))
particle_r=me.Particle('r', me.Point('r_pt'), sm.Symbol('m'))
particle_p.point.set_pos(point_o, l*frame_a.x)
# print(particle_p.point.pos_from(point_o))
particle_r.point.set_pos(particle_p.point, l*frame_b.x)
# print(particle_p.point.pos_from(particle_r.point))
point_o.set_vel(frame_n, 0)
# print(point_o.vel(frame_n))
particle_p.point.v2pt_theory(point_o,frame_n,frame_a)
# print(particle_p.point.vel(frame_n))
particle_r.point.v2pt_theory(particle_p.point,frame_n,frame_b)
# print(particle_r.point.vel(frame_n))
particle_p.mass = m
particle_r.mass = m
force_p = particle_p.mass*(g*frame_n.x)
# print(force_p)
force_r = particle_r.mass*(g*frame_n.x)
# print(force_r)
kd_eqs = [q1d - u1, q2d - u2]
forceList = [(particle_p.point,particle_p.mass*(g*frame_n.x)), (particle_r.point,
,→particle_r.mass*(g*frame_n.x))]

kane = me.KanesMethod(frame_n, q_ind=[q1,q2], u_ind=[u1, u2], kd_eqs = kd_eqs)

fr, frstar = kane.kanes_equations([particle_p, particle_r], forceList)
zero = fr+frstar
# print(zero)
#---------PyDy code for integration----------
from pydy.system import System
sys = System(kane, constants = {l:1, m:1, g:9.81},
specifieds={},
initial_conditions={q1:.1, q2:.2, u1:0, u2:0},
times = np.linspace(0.0, 10, 10/.01))

y=sys.integrate()

The commented code is not part of the output code. The print statements demonstrate how
to get responses similar to the ones in the Autolev file. Note that we need to use SymPy func-
tions like .ang_vel_in(), .dcm() etc in many cases unlike directly printing out the variables
like zero. If you are completely new to SymPy mechanics, the SymPy Mechanics for Autolev
Users guide (page 1673) guide should help. You might also have to use basic SymPy simplifi-
cations and manipulations like trigsimp(), expand(), evalf() etc for getting outputs similar
to Autolev. Refer to the SymPy Tutorial to know more about these.

1666 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Gotchas

• Don’t use variable names that conflict with Python’s reserved words. This is one example
where this is violated:

%Autolev Code
%------------
LAMBDA = EIG(M)

#SymPy Code
#----------
lambda = sm.Matrix([i.evalf() for i in (m).eigenvals().keys()])

• Make sure that the names of vectors and scalars are different. Autolev treats these
differently but these will get overwritten in Python. The parser currently allows the
names of bodies and scalars/vectors to coincide but doesn’t do this between scalars and
vectors. This should probably be changed in the future.

%Autolev Code
%------------
VARIABLES X,Y
FRAMES A
A> = X*A1> + Y*A2>
A = X+Y

#SymPy Code
#----------
x, y = me.dynamicsymbols('x y')
frame_a = me.ReferenceFrame('a')
a = x*frame_a.x + y*frame_a.y
a = x + y
# Note how frame_a is named differently so it doesn't cause a problem.
# On the other hand, 'a' gets rewritten from a scalar to a vector.
# This should be changed in the future.

• When dealing with Matrices returned by functions, one must check the order of the val-
ues as they may not be the same as in Autolev. This is especially the case for eigenvalues
and eigenvectors.

%Autolev Code
%------------
EIG(M, E1, E2)
% -> [5; 14; 13]
E2ROW = ROWS(E2, 1)
EIGVEC> = VECTOR(A, E2ROW)

#SymPy Code
#----------
e1 = sm.Matrix([i.evalf() for i in m.eigenvals().keys()])
# sm.Matrix([5;13;14]) different order
e2 = sm.Matrix([i[2][0].evalf() for i in m.eigenvects()]).reshape(m.shape[0], m.
,→shape[1])

(continues on next page)

5.40. Physics Module 1667

SymPy Documentation, Release 1.3

(continued from previous page)

e2row = e2.row(0)
# This result depends on the order of the vectors in the eigenvecs.
eigenvec = e2row[0]*a.x + e2row[1]*a.y + e2row[2]*a.y

• When using EVALUATE, use something like 90*UNITS(deg,rad) for angle substitutions
as radians are the default in SymPy. You could also add np.deg2rad() directly in the
SymPy code.
This need not be done for the output code (generated on parsing the CODE commands)
as the parser takes care of this when deg units are given in the INPUT declarations.
The DEGREES setting, on the other hand, works only in some cases like in SIMPROT where
an angle is expected.
%Autolev Code
%------------
A> = Q1*A1> + Q2*A2>
B> = EVALUATE(A>, Q1:30*UNITS(DEG,RAD))

#SymPy Code
#----------
a = q1*a.frame_a.x + q2*frame_a.y
b = a.subs({q1:30*0.0174533})
# b = a.subs({q1:np.deg2rad(30)}

• Most of the Autolev settings have not been parsed and have no effect on the parser.
The only ones that work somewhat are COMPLEX and DEGREES. It is advised to look into
alternatives to these in SymPy and Python.

• The REPRESENT command is not supported. Use the MATRIX, VECTOR or DYADIC commands
instead. Autolev 4.1 suggests these over REPRESENT as well while still allowing it but the
parser doesn’t parse it.

• Do not use variables declarations of the type WO{3}RD{2,4}. The parser can only handle
one variable name followed by one pair of curly braces and any number of ' s. You would
have to declare all the cases manually if you want to achieve something like WO{3}RD{2,
4}.

• The parser can handle normal versions of most commands but it may not parse functions
with Matrix arguments properly in most cases. Eg:
M=COEF([E1;E2],[U1,U2,U3])
This would compute the coefficients of U1, U2 and U3 in E1 and E2. It is preferable to
manually construct a Matrix using the regular versions of these commands.
%Autolev Code
%------------
% COEF([E1;E2],[U1,U2,U3])
M = [COEF(E1,U1),COEF(E1,U2),COEF(E1,U3) &
;COEF(E2,U1),COEF(E2,U2),COEF(E2,U3)]

1668 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

• MOTIONVARIABLE declarations must be used for the generalized coordinates and speeds
and all other variables must be declared in regular VARIABLE declarations. The parser
requires this to distinguish between them to pass the correct parameters to the Kane’s
method object.
It is also preferred to always declare the speeds corresponding to the coordinates and
to pass in the kinematic differential equations. The parser is able to handle some cases
where this isn’t the case by introducing some dummy variables of its own but SymPy on
its own does require them.
Also note that older Autolev declarations like VARIABLES U{3}' are not supported either.
%Autolev Code
%------------
MOTIONVARIABLES' Q{2}', U{2}'
% ----- OTHER LINES ----
Q1' = U1
Q2' = U2
----- OTHER LINES ----
ZERO = FR() + FRSTAR()

#SymPy Code
#----------
q1, q2, u1, u2 = me.dynamicsymbols('q1 q2 u1 u2')
q1d, q2d, u1d, u2d = me.dynamicsymbols('q1 q2 u1 u2', 1)

# ------- other lines -------

kd_eqs = [q1d - u1, q2d - u2]

kane = me.KanesMethod(frame_n, q_ind=[q1,q2], u_ind=[u1, u2], kd_eqs = kd_eqs)
fr, frstar = kane.kanes_equations([particle_p, particle_r], forceList)
zero = fr+frstar

• Need to change me.dynamicsymbols._t to me.dynamicsymbols('t') for all occurrences

of it in the Kane’s equations. For example have a look at line 10 of this spring damper
example. This equation is used in forming the Kane’s equations so we need to change
me.dynamicsymbols._t to me.dynamicsymbols('t') in this case.
The main reason that this needs to be done is because PyDy requires time dependent
specifieds to be explicitly laid out while Autolev simply takes care of the stray time vari-
ables in the equations by itself.
The problem is that PyDy’s System class does not accept dynamicsymbols._t as a spec-
ified. Refer to issue #396. This change is not actually ideal so a better solution should
be figured out in the future.

• The parser creates SymPy symbols and dynamicsymbols by parsing variable declarations
in the Autolev Code.
For intermediate expressions which are directly initialized the parser does not create
SymPy symbols. It just assigns them to the expression.
On the other hand, when a declared variable is assigned to an expression, the parser
stores the expression against the variable in a dictionary so as to not reassign it to a

5.40. Physics Module 1669

SymPy Documentation, Release 1.3

completely different entity. This constraint is due to the inherent nature of Python and
how it differs from a language like Autolev.
Also, Autolev seems to be able to assume whether to use a variable or the rhs expression
that variable has been assigned to in equations even without an explicit RHS() call in
some cases. For the parser to work correctly however, it is better to use RHS() wherever
a variable’s rhs expression is meant to be used.

%Autolev Code
%------------
VARIABLES X, Y
E = X + Y
X = 2*Y

RHS_X = RHS(X)

I1 = X
I2 = Y
I3 = X + Y

INERTIA B,I1,I2,I3
% -> I_B_BO>> = I1*B1>*B1> + I2*B2>*B2> + I3*B3>*B3>

#SymPy Code
#----------
x,y = me.dynamicsymbols('x y')
e = x + y # No symbol is made out of 'e'

# an entry like {x:2*y} is stored in an rhs dictionary

rhs_x = 2*y

i1 = x # again these are not made into SymPy symbols

i2 = y
i3 = x + y

body_b.inertia = (me.inertia(body_b_f, i1, i2, i3), b_cm)

# This prints as:
# x*b_f.x*b_f.x + y*b_f.y*b_f.y + (x+y)*b_f.z*b_f.z
# while Autolev's output has I1,I2 and I3 in it.
# Autolev however seems to know when to use the RHS of I1,I2 and I3
# based on the context.

• This is how the SOLVE command is parsed:

%Autolev Code
%------------
SOLVE(ZERO,X,Y)
A = RHS(X)*2 + RHS(Y)

#SymPy Code
#----------
print(sm.solve(zero,x,y))
# Behind the scenes the rhs of x
# is set to sm.solve(zero,x,y)[x].
a = sm.solve(zero,x,y)[x]*2 + sm.solve(zero,x,y)[y]

1670 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The indexing like [x] and [y] doesn’t always work so you might want to look at the
underlying dictionary that solve returns and index it correctly.

• Inertia declarations and Inertia functions work somewhat differently in the context of
the parser. This might be hard to understand at first but this had to be done to bridge
the gap due to the differences in SymPy and Autolev. Here are some points about them:
1. Inertia declarations (INERTIA B,I1,I2,I3) set the inertias of rigid bodies.
2. Inertia setters of the form I_C_D>> = expr however, set the inertias only when C is a
body. If C is a particle then I_C_D>> = expr simply parses to i_c_d = expr and i_c_d
acts like a regular variable.
3. When it comes to inertia getters (I_C_D>> used in an expression or INERTIA com-
mands), these MUST be used with the EXPRESS command to specify the frame as SymPy
needs this information to compute the inertia dyadic.
%Autolev Code
%------------
INERTIA B,I1,I2,I3
I_B_BO>> = X*A1>*A1> + Y*A2>*A2> % Parser will set the inertia of B
I_P_Q>> = X*A1>*A1> + Y^2*A2>*A2> % Parser just parses it as i_p_q = expr

E1 = 2*EXPRESS(I_B_O>>,A)
E2 = I_P_Q>>
E3 = EXPRESS(I_P_O>>,A)
E4 = EXPRESS(INERTIA(O),A)

% In E1 we are using the EXPRESS command with I_B_O>> which makes

% the parser and SymPy compute the inertia of Body B about point O.

% In E2 we are just using the dyadic object I_P_Q>> (as I_P_Q>> = expr
% doesn't act as a setter) defined above and not asking the parser
% or SymPy to compute anything.

% E3 asks the parser to compute the inertia of P about point O.

% E4 asks the parser to compute the inertias of all bodies wrt about O.

• In an inertia declaration of a body, if the inertia is being set about a point other than the
center of mass, one needs to make sure that the position vector setter for that point and
the center of mass appears before the inertia declaration as SymPy will throw an error
otherwise.
%Autolev Code
%------------
P_SO_O> = X*A1>
INERTIA S_(O) I1,I2,I3

• Note that all Autolev commands have not been implemented. The parser now covers the
important ones in their basic forms. If you are doubtful whether a command is included
or not, please have a look at this file in the source code. Search for “<command>” to
verify this. Looking at the code for the specific command will also give an idea about
what form it is expected to work in.

5.40. Physics Module 1671

SymPy Documentation, Release 1.3

Limitations and Issues

• A lot of the issues have already been discussed in the Gotchas section. Some of these
are:
– Vector names coinciding with scalar names are overwritten in Python.
– Some convenient variable declarations aren’t parsed.
– Some convenient forms of functions to return matrices aren’t parsed.
– Settings aren’t parsed.
– symbols and rhs expressions work very differently in Python which might cause un-
desirable results.
– Dictionary indexing for the parsed code of the SOLVE command is not proper in many
cases.
– Need to change dynamicsymbols._t to dynamicsymbols('t') for the PyDy simula-
tion code to work properly.
Here are some other ones:
• Eigenvectors do not seem to work as expected. The values in Autolev and SymPy are not
the same in many cases.
• Block matrices aren’t parsed by the parser. It would actually be easier to make a change
in SymPy to allow matrices to accept other matrices for arguments.
• The SymPy equivalent of the TAYLOR command .series() does not work with dynamic-
symbols().
• Only DEPENDENT constraints are currently parsed. Need to parse AUXILIARY constraints
as well. This should be done soon as it isn’t very difficult.
• None of the energy and momentum functions are parsed right now. It would be nice
to get these working as well. Some changes should probably be made to SymPy. For
instance, SymPy doesn’t have a function equivalent to NICHECK().
• The numerical integration parts work properly only in the case of the KANE command
with no arguments. Things like KANE(F1,F2) do not currently work.
• Also, the PyDy numerical simulation code works only for cases where the matrix say ZERO
= FR() + FRSTAR() is solved for. It doesn’t work well when the matrix has some other
equations plugged in as well. One hurdle faced in achieving this was that PyDy’s System
class automatically takes in the forcing_full and mass_matrix_full and solves them
without giving the user the flexibility to specify the equations. It would be nice to add
this functionality to the System class.

Future Improvements

1. Completing Dynamics Online

The parser has been built by referring to and parsing codes from the Autolev Tutorial and
the book Dynamics Online: Theory and Implementation Using Autolev. Basically, the process
involved going through each of these codes, validating the parser results and improving the
rules if required to make sure the codes parsed well.

1672 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The parsed codes of these are available on GitLab here. The repo is private so access needs
to be requested. As of now, most codes till Chapter 4 of Dynamics Online have been parsed.
Completing all the remaining codes of the book (namely, 2-10, 2-11, rest of Ch4, Ch5 and Ch6
(less important) ) would make the parser more complete.

2. Fixing Issues

The second thing to do would be to go about fixing the problems described above in the
Gotchas (page 1667) and Limitations and Issues (page 1672) sections in order of priority and
ease. Many of these require changes in the parser code while some of these are better fixed
by adding some functionality to SymPy.

3. Switching to an AST

The parser is currently built using a kind of Concrete Syntax Tree (CST) using the ANTLR
framework. It would be ideal to switch from a CST to an Abstract Syntax Tree (AST). This
way, the parser code will be independent of the ANTLR grammar which makes it a lot more
flexible. It would also be easier to make changes to the grammar and the rules of the parser.

SymPy Mechanics for Autolev Users

Introduction

Autolev (now superseded by MotionGenesis) is a domain specific programming language

which is used for symbolic multibody dynamics. The SymPy mechanics module now has
enough power and functionality to be a fully featured symbolic dynamics module. The PyDy
package extends the SymPy output to the numerical domain for simulation, analyses and vi-
sualization. Autolev and SymPy Mechanics have a lot in common but there are also many
differences between them. This page shall expand upon their differences. It is meant to be a
go-to reference for Autolev users who want to transition to SymPy Mechanics.
It would be nice to have a basic understanding of SymPy and SymPy Mechanics before going
over this page. If you are completely new to Python, you can check out the official Python
Tutorial. Check out the SymPy Documentation, especially the tutorial to get a feel for SymPy.
For an introduction to Multibody dynamics in Python, this lecture is very helpful.
You might also find the Autolev Parser (page 1664) which is a part of SymPy to be helpful.

5.40. Physics Module 1673

SymPy Documentation, Release 1.3

Some Key Differences

Autolev SymPy Mechanics

Autolev is a domain specific programming SymPy is a library written in the general

language designed to perform multibody purpose language Python. Although
dynamics. Since it is a language of its own, Autolev’s code is more compact, SymPy (by
it has a very rigid language specification. It virtue of being an add on to Python) is
predefines, assumes and computes many more flexible. The users have more control
things based on the input code. Its code is over what they can do. For example, one
a lot cleaner and concise as a result of this. can create a class in their code for let’s say
a type of rigibodies with common
properties. The wide array of scientific
Python libraries available is also a big plus.

Autolev generates Matlab, C, or Fortran SymPy generates numerical Python, C or

code from a small set of symbolic Octave/Matlab code from a large set of
mathematics. symbolic mathematics created with SymPy.
It also builds on the popular scientific
Python stack such as NumPy, SciPy,
IPython, matplotlib, Cython and Theano.

Autolev uses 1 (one) based indexing. The Python uses 0 (zero) based indexing. The
initial element of a sequence is found using initial element of a sequence is found using
a[1]. a[0].

Autolev is case insensitive. SymPy code being Python code is case

sensitive.

One can define their own commands in SymPy code is Python code, so one can
Autolev by making .R and .A files which can define functions in their code. This is a lot
be used in their programs. more convenient.

Autolev is proprietary. SymPy is open source.

Rough Autolev-SymPy Equivalents

The tables below give rough equivalents for some common Autolev expressions. These are
not exact equivalents, but rather should be taken as hints to get you going in the right di-
rection. For more detail read the built-in documentation on SymPy vectors, SymPy mechanics
and PyDy .

1674 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

In the tables below, it is assumed that you have executed the following commands in Python:

import sympy.physics.mechanics as me
import sympy as sm

5.40. Physics Module 1675

SymPy Documentation, Release 1.3

Mathematical Equivalents

Autolev SymPy Notes

Constants A, B a, b = sm.symbols(‘a Note that the names of the

b’, real=True) symbols can be different
from the names of the
variables they are assigned
to. We can define a, b =
symbols(‘b a’) but its
good practice to follow the
convention.

Constants C+ c = sm.symbols(‘c’, Refer to SymPy assumptions

real=True, for more information.
nonnegative=True)

Constants D- d = sm.symbols(‘d’,
real=True,
nonpositive=True)

Constants K{4} k1, k2, k3, k4 =

sm.symbols('k1 k2 k3
k4', real=True)

Constants a{2:4} a2, a3, a4 =

sm.symbols('a2 a3 a4',
real=True)

Constants b{1:2, 1:2} b11, b12, b21, b22 =

sm.symbols('b11 b12 b21
b22', real=True)

Specified Phi phi =

me.dynamicsymbols(‘phi
')

Variables q, s q, s =
me.dynamicsymbols(q, s)

Variables x’’ x = me.

dynamicsymbols(‘x’ )
xd = me.
1676 Chapter
dynamicsymbols(‘x’ , 5. SymPy Modules Reference
1)
xd2 = me.
dynamicsymbols(‘x’ ,
 SymPy Documentation, Release 1.3

Physical Equivalents

Autolev SymPy Notes

Bodies A m =sm.symbols(‘m’) The 4th and 5th arguments
Declares A, its masscenter Ao = sm.symbols(‘Ao’) are for the mass and inertia.
Ao, and orthonormal vectors Af = me. These are specified after the
A1>, A2> and A3> fixed in ReferenceFrame(‘Af’ declaration in Autolev.
A. ) One can pass a dummy for
I = me.outer(Af.x,Af.x) the parameters and use set-
P = me.Point(‘P’) ters A.mass = \_ and A.
A =me.RigidBody(‘A’, inertia = \_ to set them
Ao, Af, m, (I, P)) later.
Af.x, Af.y and Af.z are equiv- For more information refer
alent to A1>, A2> and A3>. to mechanics/masses.
Frames A A = me. For more information refer
V1> = X1*A1> + X2*A2> ReferenceFrame(‘A’ ) to physics/vectors.
v1 = x1*A.x + x2*A.y
Newtonian N N = me. SymPy doesn’t specify that
ReferenceFrame(‘N’ ) a frame is inertial during
declaration. Many functions
such as set_ang_vel() take
the inertial reference frame
as a parameter.
Particles C m = sm.symbols(‘m’) The 2nd and 3rd arguments
Po = me.Point(‘Po’) are for the point and mass.
C = me.Particle(‘C’, In Autolev, these are speci-
Po, m) fied after the declaration.
One can pass a dummy
and use setters (A.point =
\_ and A.mass = \_) to set
them later.
Points P, Q P = me.Point(‘P’)
Q = me.Point(‘Q’)
Mass B=mB mB = symbols(‘mB’)
B.mass = mB
Inertia B, I1, I2, I3, I = me.inertia(Bf, i1, For more information refer
I12, I23, I31 i2, i3, i12, i23, i31) to the mechanics api.
B.inertia = (I, P) where
B is a rigidbody, Bf is the re-
lated frame and P is the cen-
ter of mass of B.
Inertia dyadics can also be
formed using vector outer
products.
I = me.outer(N.x, N.x)
Continued on next page

5.40. Physics Module 1677

SymPy Documentation, Release 1.3

Table 1 – continued from previous page

Autolev SymPy Notes
vec> = P_O_Q>/L vec = (Qo.pos_from(O))/ For more information refer
vec> = u1*N1> + u2*N2> L to physics/vectors.
Cross(a>, b>) vec = u1*N.x + u2*N.y
Dot(a>, b>) cross(a, b)
Mag(v>) dot(a, b)
Unitvec(v>) v.magnitude()
DYAD>> = 3*A1>*A1> + v.normalize()
A2>*A2> + 2*A3>*A3> dyad = 3*me.outer(a.x
,a.x) + me.outer(a.y,
a.y) + 2*me.outer(a.z
,a.z)
P_O_Q> = LA*A1> Q.point = O. For more information refer
P_P_Q> = LA*A1> locatenew(‘Qo’, LA*A.x) to the kinematics api.
where A is a reference All these vector and kine-
frame. matic functions are to be
Q.point = P.point. used on Point objects and
locatenew(‘Qo ’, LA*A. not Particle objects so .
x) point must be used for par-
ticles.
V_O_N> = u3*N.1> + O.set_vel(N, u1*N.x + The getter would be O.
u4*N.2> u2*N.y) vel(N).
Partials(V_O_N>, u3) O.partial_velocity(N ,
u3)
A_O_N> = 0> O.set_acc(N, 0) The getter would be O.
Acceleration of point O in acc(N).
reference frame N.
W_B_N> = qB’*B3> B.set_ang_vel(N, The getter would be B.
Angular velocity of body B in qBd*Bf.z) ang_vel_in(N).
reference frame F. where Bf is the frame associ-
ated with the body B.
ALF_B_N> =Dt(W_B_N>, N) B.set_ang_acc(N, The getter would be B.
Angular acceleration of body diff(B.ang_vel_in(N) ang_acc_in(N).
B in reference frame N. )
Force_O> = F1*N1> + In SymPy one should have
F2*N2> a list which contains all the
Torque_A> = -c*qA’*A3> forces and torques.
fL.append((O, f1*N.x +
f2*N.y))
where fL is the force list.
fl.append((A, -c*qAd*A.
z))
A_B = M where M is a matrix B.orient(A, 'DCM', M)
and A, B are frames. where M is a SymPy Matrix.
D = A_B*2 + 1 D = A.dcm(B)*2 + 1
CM(B) B.masscenter
Mass(A,B,C) A.mass + B.mass + C.
mass
V1pt(A,B,P,Q) Q.v1pt_theory(P, A, B) P and Q are assumed to be
Point objects here. Remem-
ber to use .point for parti-
cles.
Continued on next page

1678 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Table 1 – continued from previous page

Autolev SymPy Notes
V2pts(A,B,P,Q) Q.v2pt_theory(P, A, B)
A1pt(A,B,P,Q) Q.a1pt_theory(P, A, B)
A2pts(A,B,P,Q) Q.a2pt_theory(P, A, B)
Angvel(A,B) B.ang_vel_in(A)
Simprot(A, B, 1, qA) B.orient(A, ‘Axis’, qA,
A.x)
Gravity(G*N1>) fL.extend(gravity( g*N. In SymPy we must use a
x, P1, P2, ...)) forceList (here fL) which
contains tuples of the form
(point, force_vector).
This is passed to the
kanes_equations() method
of the KanesMethod object.
CM(O,P1,R) me.functions.
center_of_mass(o, p1,
r)
Force(P/Q, v>) fL.append((P, -1*v),
(Q, v))
Torque(A/B, v>) fL.append((A, -1*v),
(B, v))
Kindiffs(A, B ...) KM.kindiffdict()
Momentum(option) linear_momentum(N, B1,
B2 ...)
reference frame followed by
one or more bodies
angular_momentum(O, N,
B1, B2 ...)
point, reference frame fol-
lowed by one or more bodies
KE() kinetic_energy(N, B1,
B2 ...)
reference frame followed by
one or more bodies
Constrain(...) velocity_constraints = For more details refer to me-
[...] chanics/kane and the kane
u_dependent = [...] api.
u_auxiliary = [...]
These lists are passed to the
KanesMethod object.
Continued on next page

5.40. Physics Module 1679

SymPy Documentation, Release 1.3

Table 1 – continued from previous page

Autolev SymPy Notes
Fr() FrStar() KM = KanesMethod(f, For more details refer to me-
q_ind, u_ind, kd_eqs, chanics/kane and the kane
q_dependent, configura api.
tion_constraints, u_de
pendent, velocity_cons
traints, acceleration_
constraints, u_auxilia
ry)
The KanesMethod object
takes a reference frame
followed by multiple lists as
arguments.
(fr, frstar) = KM.
kanes_equations(fL,
bL) where fL and bL are
lists of forces and bodies
respectively.

Numerical Evaluation and Visualization

Autolev’s CODE Option() command allows one to generate Matlab, C, or Fortran code for nu-
merical evaluation and visualization. Option can be Dynamics, ODE, Nonlinear or Algebraic.
Numerical evaluation for dynamics can be achieved using PyDy. One can pass in the Kanes-
Method object to the System class along with the values for the constants, specifieds, initial
conditions and time steps. The equations of motion can then be integrated. The plotting is
achieved using matlplotlib. Here is an example from the PyDy Documentation on how it is
done:

from numpy import array, linspace, sin

from pydy.system import System

sys = System(kane,
constants = {mass: 1.0, stiffness: 1.0,
damping: 0.2, gravity: 9.8},
specifieds = {force: lambda x, t: sin(t)},
initial_conditions = {position: 0.1, speed:-1.0},
times = linspace(0.0, 10.0, 1000))

y = sys.integrate()

import matplotlib.pyplot as plt

plt.plot(sys.times, y)
plt.legend((str(position), str(speed)))
plt.show()

For information on all the things PyDy can accomplish refer to the PyDy Documentation.
The tools in the PyDy workflow are :
• SymPy: SymPy is a Python library for symbolic computation. It provides computer
algebra capabilities either as a standalone application, as a library to other applica-
tions, or live on the web as SymPy Live or SymPy Gamma.
• NumPy: NumPy is a library for the Python programming language, adding support

1680 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

for large, multi-dimensional arrays and matrices, along with a large collection of
high-level mathematical functions to operate on these arrays.
• SciPy: SciPy is an open source Python library used for scientific computing and tech-
nical computing. SciPy contains modules for optimization, linear algebra, integra-
tion, interpolation, special functions, FFT, signal and image processing, ODE solvers
and other tasks common in science and engineering.
• IPython: IPython is a command shell for interactive computing in multiple pro-
gramming languages, originally developed for the Python programming language,
that offers introspection, rich media, shell syntax, tab completion, and history.
• Theano: Theano is a numerical computation library for Python. In Theano, computa-
tions are expressed using a NumPy-esque syntax and compiled to run efficiently on
either CPU or GPU architectures
• Cython: Cython is a superset of the Python programming language, designed to
give C-like performance with code that is mostly written in Python. Cython is a
compiled language that generates CPython extension modules.
• matplotlib: matplotlib is a plotting library for the Python programming language and
its numerical mathematics extension NumPy.
One will be able to write code equivalent to the Matlab, C or Fortran code generated by
Autolev using these scientific computing tools. It is recommended to go over these modules
to gain an understanding of scientific computing with Python.

Links

SymPy Tutorial
SymPy Documentation
SymPy Physics Vector Documentation
SymPy Mechanics Documentation
PyDy Documentation
MultiBody Dynamics with Python

Mechanics API

Masses, Inertias & Particles, RigidBodys (Docstrings)

Particle

class sympy.physics.mechanics.particle.Particle(name, point, mass)

A particle.
Particles have a non-zero mass and lack spatial extension; they take up no space.
Values need to be supplied on initialization, but can be changed later.
Parameters name : str
Name of particle
point : Point

5.40. Physics Module 1681

SymPy Documentation, Release 1.3

A physics/mechanics Point which represents the position, velocity,

and acceleration of this Particle
mass : sympifyable
A SymPy expression representing the Particle’s mass

Examples

>>> from sympy.physics.mechanics import Particle, Point

>>> from sympy import Symbol
>>> po = Point('po')
>>> m = Symbol('m')
>>> pa = Particle('pa', po, m)
>>> # Or you could change these later
>>> pa.mass = m
>>> pa.point = po

angular_momentum(point, frame)
Angular momentum of the particle about the point.
The angular momentum H, about some point O of a particle, P, is given by:
H=rxm*v
where r is the position vector from point O to the particle P, m is the mass of the
particle, and v is the velocity of the particle in the inertial frame, N.
Parameters point : Point
The point about which angular momentum of the particle is desired.
frame : ReferenceFrame
The frame in which angular momentum is desired.

Examples

>>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame

>>> from sympy.physics.mechanics import dynamicsymbols
>>> m, v, r = dynamicsymbols('m v r')
>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> A = O.locatenew('A', r * N.x)
>>> P = Particle('P', A, m)
>>> P.point.set_vel(N, v * N.y)
>>> P.angular_momentum(O, N)
m*r*v*N.z

kinetic_energy(frame)
Kinetic energy of the particle
The kinetic energy, T, of a particle, P, is given by
‘T = 1/2 m v^2’
where m is the mass of particle P, and v is the velocity of the particle in the supplied
ReferenceFrame.

1682 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters frame : ReferenceFrame

The Particle’s velocity is typically defined with respect to an inertial
frame but any relevant frame in which the velocity is known can be
supplied.

Examples

>>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame

>>> from sympy import symbols
>>> m, v, r = symbols('m v r')
>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> P = Particle('P', O, m)
>>> P.point.set_vel(N, v * N.y)
>>> P.kinetic_energy(N)
m*v**2/2

linear_momentum(frame)
Linear momentum of the particle.
The linear momentum L, of a particle P, with respect to frame N is given by
L=m*v
where m is the mass of the particle, and v is the velocity of the particle in the frame
N.
Parameters frame : ReferenceFrame
The frame in which linear momentum is desired.

Examples

>>> from sympy.physics.mechanics import Particle, Point, ReferenceFrame

>>> from sympy.physics.mechanics import dynamicsymbols
>>> m, v = dynamicsymbols('m v')
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> A = Particle('A', P, m)
>>> P.set_vel(N, v * N.x)
>>> A.linear_momentum(N)
m*v*N.x

mass
Mass of the particle.
point
Point of the particle.
potential_energy
The potential energy of the Particle.

5.40. Physics Module 1683

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.mechanics import Particle, Point

>>> from sympy import symbols
>>> m, g, h = symbols('m g h')
>>> O = Point('O')
>>> P = Particle('P', O, m)
>>> P.potential_energy = m * g * h
>>> P.potential_energy
g*h*m

RigidBody

class sympy.physics.mechanics.rigidbody.RigidBody(name, masscenter, frame,

mass, inertia)
An idealized rigid body.
This is essentially a container which holds the various components which describe a rigid
body: a name, mass, center of mass, reference frame, and inertia.
All of these need to be supplied on creation, but can be changed afterwards.

Examples

>>> from sympy import Symbol

>>> from sympy.physics.mechanics import ReferenceFrame, Point, RigidBody
>>> from sympy.physics.mechanics import outer
>>> m = Symbol('m')
>>> A = ReferenceFrame('A')
>>> P = Point('P')
>>> I = outer (A.x, A.x)
>>> inertia_tuple = (I, P)
>>> B = RigidBody('B', P, A, m, inertia_tuple)
>>> # Or you could change them afterwards
>>> m2 = Symbol('m2')
>>> B.mass = m2

Attributes

name (string) The body’s name.

masscen- (Point) The point which represents the center of mass of the rigid body.
ter
frame (ReferenceFrame) The ReferenceFrame which the rigid body is fixed in.
mass (Sympifyable) The body’s mass.
inertia ((Dyadic, Point)) The body’s inertia about a point; stored in a tuple as
shown above.

angular_momentum(point, frame)
Returns the angular momentum of the rigid body about a point in the given frame.

1684 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The angular momentum H of a rigid body B about some point O in a frame N is given
by:
H = I·w + r×Mv
where I is the central inertia dyadic of B, w is the angular velocity of body B in the
frame, N, r is the position vector from point O to the mass center of B, and v is the
velocity of the mass center in the frame, N.
Parameters point : Point
The point about which angular momentum is desired.
frame : ReferenceFrame
The frame in which angular momentum is desired.

Examples

>>> from sympy.physics.mechanics import Point, ReferenceFrame, outer

>>> from sympy.physics.mechanics import RigidBody, dynamicsymbols
>>> M, v, r, omega = dynamicsymbols('M v r omega')
>>> N = ReferenceFrame('N')
>>> b = ReferenceFrame('b')
>>> b.set_ang_vel(N, omega * b.x)
>>> P = Point('P')
>>> P.set_vel(N, 1 * N.x)
>>> I = outer(b.x, b.x)
>>> B = RigidBody('B', P, b, M, (I, P))
>>> B.angular_momentum(P, N)
omega*b.x

central_inertia
The body’s central inertia dyadic.
kinetic_energy(frame)
Kinetic energy of the rigid body
The kinetic energy, T, of a rigid body, B, is given by
‘T = 1/2 (I omega^2 + m v^2)’
where I and m are the central inertia dyadic and mass of rigid body B, respectively,
omega is the body’s angular velocity and v is the velocity of the body’s mass center
in the supplied ReferenceFrame.
Parameters frame : ReferenceFrame
The RigidBody’s angular velocity and the velocity of it’s mass center
are typically defined with respect to an inertial frame but any relevant
frame in which the velocities are known can be supplied.

Examples

>>> from sympy.physics.mechanics import Point, ReferenceFrame, outer

>>> from sympy.physics.mechanics import RigidBody
>>> from sympy import symbols
>>> M, v, r, omega = symbols('M v r omega')
(continues on next page)

5.40. Physics Module 1685

SymPy Documentation, Release 1.3

(continued from previous page)

>>> N = ReferenceFrame('N')
>>> b = ReferenceFrame('b')
>>> b.set_ang_vel(N, omega * b.x)
>>> P = Point('P')
>>> P.set_vel(N, v * N.x)
>>> I = outer (b.x, b.x)
>>> inertia_tuple = (I, P)
>>> B = RigidBody('B', P, b, M, inertia_tuple)
>>> B.kinetic_energy(N)
M*v**2/2 + omega**2/2

linear_momentum(frame)
Linear momentum of the rigid body.
The linear momentum L, of a rigid body B, with respect to frame N is given by
L = M * v*
where M is the mass of the rigid body and v* is the velocity of the mass center of B
in the frame, N.
Parameters frame : ReferenceFrame
The frame in which linear momentum is desired.

Examples

>>> from sympy.physics.mechanics import Point, ReferenceFrame, outer

>>> from sympy.physics.mechanics import RigidBody, dynamicsymbols
>>> M, v = dynamicsymbols('M v')
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, v * N.x)
>>> I = outer (N.x, N.x)
>>> Inertia_tuple = (I, P)
>>> B = RigidBody('B', P, N, M, Inertia_tuple)
>>> B.linear_momentum(N)
M*v*N.x

potential_energy
The potential energy of the RigidBody.

Examples

>>> from sympy.physics.mechanics import RigidBody, Point, outer,␣

,→ReferenceFrame

>>> from sympy import symbols

>>> M, g, h = symbols('M g h')
>>> b = ReferenceFrame('b')
>>> P = Point('P')
>>> I = outer (b.x, b.x)
>>> Inertia_tuple = (I, P)
>>> B = RigidBody('B', P, b, M, Inertia_tuple)
>>> B.potential_energy = M * g * h
(continues on next page)

1686 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> B.potential_energy
M*g*h

inertia

sympy.physics.mechanics.functions.inertia(frame, ixx, iyy, izz, ixy=0, iyz=0,

izx=0)
Simple way to create inertia Dyadic object.
If you don’t know what a Dyadic is, just treat this like the inertia tensor. Then, do the
easy thing and define it in a body-fixed frame.
Parameters frame : ReferenceFrame
The frame the inertia is defined in
ixx : Sympifyable
the xx element in the inertia dyadic
iyy : Sympifyable
the yy element in the inertia dyadic
izz : Sympifyable
the zz element in the inertia dyadic
ixy : Sympifyable
the xy element in the inertia dyadic
iyz : Sympifyable
the yz element in the inertia dyadic
izx : Sympifyable
the zx element in the inertia dyadic

Examples

>>> from sympy.physics.mechanics import ReferenceFrame, inertia

>>> N = ReferenceFrame('N')
>>> inertia(N, 1, 2, 3)
(N.x|N.x) + 2*(N.y|N.y) + 3*(N.z|N.z)

inertia_of_point_mass

sympy.physics.mechanics.functions.inertia_of_point_mass(mass, pos_vec,
frame)
Inertia dyadic of a point mass relative to point O.
Parameters mass : Sympifyable
Mass of the point mass
pos_vec : Vector

5.40. Physics Module 1687

SymPy Documentation, Release 1.3

Position from point O to point mass

frame : ReferenceFrame
Reference frame to express the dyadic in

Examples

>>> from sympy import symbols

>>> from sympy.physics.mechanics import ReferenceFrame, inertia_of_point_mass
>>> N = ReferenceFrame('N')
>>> r, m = symbols('r m')
>>> px = r * N.x
>>> inertia_of_point_mass(m, px, N)
m*r**2*(N.y|N.y) + m*r**2*(N.z|N.z)

linear_momentum

sympy.physics.mechanics.functions.linear_momentum(frame, *body)
Linear momentum of the system.
This function returns the linear momentum of a system of Particle’s and/or RigidBody’s.
The linear momentum of a system is equal to the vector sum of the linear momentum of
its constituents. Consider a system, S, comprised of a rigid body, A, and a particle, P. The
linear momentum of the system, L, is equal to the vector sum of the linear momentum
of the particle, L1, and the linear momentum of the rigid body, L2, i.e.
L = L1 + L2
Parameters frame : ReferenceFrame
The frame in which linear momentum is desired.
body1, body2, body3… : Particle and/or RigidBody
The body (or bodies) whose linear momentum is required.

Examples

>>> from sympy.physics.mechanics import Point, Particle, ReferenceFrame

>>> from sympy.physics.mechanics import RigidBody, outer, linear_momentum
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, 10 * N.x)
>>> Pa = Particle('Pa', P, 1)
>>> Ac = Point('Ac')
>>> Ac.set_vel(N, 25 * N.y)
>>> I = outer(N.x, N.x)
>>> A = RigidBody('A', Ac, N, 20, (I, Ac))
>>> linear_momentum(N, A, Pa)
10*N.x + 500*N.y

1688 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

angular_momentum

sympy.physics.mechanics.functions.angular_momentum(point, frame, *body)

Angular momentum of a system
This function returns the angular momentum of a system of Particle’s and/or RigidBody’s.
The angular momentum of such a system is equal to the vector sum of the angular mo-
mentum of its constituents. Consider a system, S, comprised of a rigid body, A, and a
particle, P. The angular momentum of the system, H, is equal to the vector sum of the
angular momentum of the particle, H1, and the angular momentum of the rigid body,
H2, i.e.
H = H1 + H2
Parameters point : Point
The point about which angular momentum of the system is desired.
frame : ReferenceFrame
The frame in which angular momentum is desired.
body1, body2, body3… : Particle and/or RigidBody
The body (or bodies) whose angular momentum is required.

Examples

>>> from sympy.physics.mechanics import Point, Particle, ReferenceFrame

>>> from sympy.physics.mechanics import RigidBody, outer, angular_momentum
>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> O.set_vel(N, 0 * N.x)
>>> P = O.locatenew('P', 1 * N.x)
>>> P.set_vel(N, 10 * N.x)
>>> Pa = Particle('Pa', P, 1)
>>> Ac = O.locatenew('Ac', 2 * N.y)
>>> Ac.set_vel(N, 5 * N.y)
>>> a = ReferenceFrame('a')
>>> a.set_ang_vel(N, 10 * N.z)
>>> I = outer(N.z, N.z)
>>> A = RigidBody('A', Ac, a, 20, (I, Ac))
>>> angular_momentum(O, N, Pa, A)
10*N.z

kinetic_energy

sympy.physics.mechanics.functions.kinetic_energy(frame, *body)
Kinetic energy of a multibody system.
This function returns the kinetic energy of a system of Particle’s and/or RigidBody’s.
The kinetic energy of such a system is equal to the sum of the kinetic energies of its
constituents. Consider a system, S, comprising a rigid body, A, and a particle, P. The
kinetic energy of the system, T, is equal to the vector sum of the kinetic energy of the
particle, T1, and the kinetic energy of the rigid body, T2, i.e.
T = T1 + T2

5.40. Physics Module 1689

SymPy Documentation, Release 1.3

Kinetic energy is a scalar.

Parameters frame : ReferenceFrame
The frame in which the velocity or angular velocity of the body is
defined.
body1, body2, body3… : Particle and/or RigidBody
The body (or bodies) whose kinetic energy is required.

Examples

>>> from sympy.physics.mechanics import Point, Particle, ReferenceFrame

>>> from sympy.physics.mechanics import RigidBody, outer, kinetic_energy
>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> O.set_vel(N, 0 * N.x)
>>> P = O.locatenew('P', 1 * N.x)
>>> P.set_vel(N, 10 * N.x)
>>> Pa = Particle('Pa', P, 1)
>>> Ac = O.locatenew('Ac', 2 * N.y)
>>> Ac.set_vel(N, 5 * N.y)
>>> a = ReferenceFrame('a')
>>> a.set_ang_vel(N, 10 * N.z)
>>> I = outer(N.z, N.z)
>>> A = RigidBody('A', Ac, a, 20, (I, Ac))
>>> kinetic_energy(N, Pa, A)
350

potential_energy

sympy.physics.mechanics.functions.potential_energy(*body)
Potential energy of a multibody system.
This function returns the potential energy of a system of Particle’s and/or RigidBody’s.
The potential energy of such a system is equal to the sum of the potential energy of its
constituents. Consider a system, S, comprising a rigid body, A, and a particle, P. The
potential energy of the system, V, is equal to the vector sum of the potential energy of
the particle, V1, and the potential energy of the rigid body, V2, i.e.
V = V1 + V2
Potential energy is a scalar.
Parameters body1, body2, body3… : Particle and/or RigidBody
The body (or bodies) whose potential energy is required.

Examples

>>> from sympy.physics.mechanics import Point, Particle, ReferenceFrame

>>> from sympy.physics.mechanics import RigidBody, outer, potential_energy
>>> from sympy import symbols
>>> M, m, g, h = symbols('M m g h')
(continues on next page)

1690 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> O.set_vel(N, 0 * N.x)
>>> P = O.locatenew('P', 1 * N.x)
>>> Pa = Particle('Pa', P, m)
>>> Ac = O.locatenew('Ac', 2 * N.y)
>>> a = ReferenceFrame('a')
>>> I = outer(N.z, N.z)
>>> A = RigidBody('A', Ac, a, M, (I, Ac))
>>> Pa.potential_energy = m * g * h
>>> A.potential_energy = M * g * h
>>> potential_energy(Pa, A)
M*g*h + g*h*m

Lagrangian

sympy.physics.mechanics.functions.Lagrangian(frame, *body)
Lagrangian of a multibody system.
This function returns the Lagrangian of a system of Particle’s and/or RigidBody’s. The
Lagrangian of such a system is equal to the difference between the kinetic energies and
potential energies of its constituents. If T and V are the kinetic and potential energies
of a system then it’s Lagrangian, L, is defined as
L=T-V
The Lagrangian is a scalar.
Parameters frame : ReferenceFrame
The frame in which the velocity or angular velocity of the body is
defined to determine the kinetic energy.
body1, body2, body3… : Particle and/or RigidBody
The body (or bodies) whose Lagrangian is required.

Examples

>>> from sympy.physics.mechanics import Point, Particle, ReferenceFrame

>>> from sympy.physics.mechanics import RigidBody, outer, Lagrangian
>>> from sympy import symbols
>>> M, m, g, h = symbols('M m g h')
>>> N = ReferenceFrame('N')
>>> O = Point('O')
>>> O.set_vel(N, 0 * N.x)
>>> P = O.locatenew('P', 1 * N.x)
>>> P.set_vel(N, 10 * N.x)
>>> Pa = Particle('Pa', P, 1)
>>> Ac = O.locatenew('Ac', 2 * N.y)
>>> Ac.set_vel(N, 5 * N.y)
>>> a = ReferenceFrame('a')
>>> a.set_ang_vel(N, 10 * N.z)
>>> I = outer(N.z, N.z)
>>> A = RigidBody('A', Ac, a, 20, (I, Ac))
(continues on next page)

5.40. Physics Module 1691

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Pa.potential_energy = m * g * h
>>> A.potential_energy = M * g * h
>>> Lagrangian(N, Pa, A)
-M*g*h - g*h*m + 350

Kane’s Method & Lagrange’s Method (Docstrings)

KaneMethod

class sympy.physics.mechanics.kane.KanesMethod(frame, q_ind, u_ind,

kd_eqs=None,
q_dependent=None, config-
uration_constraints=None,
u_dependent=None, veloc-
ity_constraints=None, accel-
eration_constraints=None,
u_auxiliary=None)
Kane’s method object.
This object is used to do the “book-keeping” as you go through and form equations of
motion in the way Kane presents in: Kane, T., Levinson, D. Dynamics Theory and Appli-
cations. 1985 McGraw-Hill
The attributes are for equations in the form [M] udot = forcing.

Examples

This is a simple example for a one degree of freedom translational spring-mass-damper.

In this example, we first need to do the kinematics. This involves creating generalized
speeds and coordinates and their derivatives. Then we create a point and set its velocity
in a frame.

>>> from sympy import symbols

>>> from sympy.physics.mechanics import dynamicsymbols, ReferenceFrame
>>> from sympy.physics.mechanics import Point, Particle, KanesMethod
>>> q, u = dynamicsymbols('q u')
>>> qd, ud = dynamicsymbols('q u', 1)
>>> m, c, k = symbols('m c k')
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, u * N.x)

Next we need to arrange/store information in the way that KanesMethod requires. The
kinematic differential equations need to be stored in a dict. A list of forces/torques must
be constructed, where each entry in the list is a (Point, Vector) or (ReferenceFrame,
Vector) tuple, where the Vectors represent the Force or Torque. Next a particle needs
to be created, and it needs to have a point and mass assigned to it. Finally, a list of all
bodies and particles needs to be created.

>>> kd = [qd - u]
>>> FL = [(P, (-k * q - c * u) * N.x)]
(continues on next page)

1692 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> pa = Particle('pa', P, m)
>>> BL = [pa]

Finally we can generate the equations of motion. First we create the KanesMethod object
and supply an inertial frame, coordinates, generalized speeds, and the kinematic differ-
ential equations. Additional quantities such as configuration and motion constraints,
dependent coordinates and speeds, and auxiliary speeds are also supplied here (see the
online documentation). Next we form FR* and FR to complete: Fr + Fr* = 0. We have
the equations of motion at this point. It makes sense to rearrange them though, so we
calculate the mass matrix and the forcing terms, for E.o.M. in the form: [MM] udot =
forcing, where MM is the mass matrix, udot is a vector of the time derivatives of the
generalized speeds, and forcing is a vector representing “forcing” terms.

>>> KM = KanesMethod(N, q_ind=[q], u_ind=[u], kd_eqs=kd)

>>> (fr, frstar) = KM.kanes_equations(BL, FL)
>>> MM = KM.mass_matrix
>>> forcing = KM.forcing
>>> rhs = MM.inv() * forcing
>>> rhs
Matrix([[(-c*u(t) - k*q(t))/m]])
>>> KM.linearize(A_and_B=True)[0]
Matrix([
[ 0, 1],
[-k/m, -c/m]])

Please look at the documentation pages for more information on how to perform lin-
earization and how to deal with dependent coordinates & speeds, and how do deal with
bringing non-contributing forces into evidence.

Attributes

q, u (Matrix) Matrices of the generalized coordinates and speeds

bodylist (iterable) Iterable of Point and RigidBody objects in the system.
forcelist (iterable) Iterable of (Point, vector) or (ReferenceFrame, vector) tuples
describing the forces on the system.
auxiliary (Matrix) If applicable, the set of auxiliary Kane’s equations used to solve
for non-contributing forces.
mass_matrix (Matrix) The system’s mass matrix
forcing (Matrix) The system’s forcing vector
mass_matrix_full
(Matrix) The “mass matrix” for the u’s and q’s
forc- (Matrix) The “forcing vector” for the u’s and q’s
ing_full

auxiliary_eqs
A matrix containing the auxiliary equations.
forcing
The forcing vector of the system.
forcing_full
The forcing vector of the system, augmented by the kinematic differential equations.

5.40. Physics Module 1693

SymPy Documentation, Release 1.3

kanes_equations(bodies, loads=None)
Method to form Kane’s equations, Fr + Fr* = 0.
Returns (Fr, Fr*). In the case where auxiliary generalized speeds are present (say, s
auxiliary speeds, o generalized speeds, and m motion constraints) the length of the
returned vectors will be o - m + s in length. The first o - m equations will be the
constrained Kane’s equations, then the s auxiliary Kane’s equations. These auxiliary
equations can be accessed with the auxiliary_eqs().
Parameters bodies : iterable
An iterable of all RigidBody’s and Particle’s in the system. A system
must have at least one body.
loads : iterable
Takes in an iterable of (Particle, Vector) or (ReferenceFrame, Vector)
tuples which represent the force at a point or torque on a frame. Must
be either a non-empty iterable of tuples or None which corresponds
to a system with no constraints.
kindiffdict()
Returns a dictionary mapping q’ to u.
linearize(**kwargs)
Linearize the equations of motion about a symbolic operating point.
If kwarg A_and_B is False (default), returns M, A, B, r for the linearized form, M*[q’,
u’]^T = A*[q_ind, u_ind]^T + B*r.
If kwarg A_and_B is True, returns A, B, r for the linearized form dx = A*x + B*r, where
x = [q_ind, u_ind]^T. Note that this is computationally intensive if there are many
symbolic parameters. For this reason, it may be more desirable to use the default
A_and_B=False, returning M, A, and B. Values may then be substituted in to these
matrices, and the state space form found as A = P.T*M.inv()*A, B = P.T*M.inv()*B,
where P = Linearizer.perm_mat.
In both cases, r is found as all dynamicsymbols in the equations of motion that are
not part of q, u, q’, or u’. They are sorted in canonical form.
The operating points may be also entered using the op_point kwarg. This takes a
dictionary of {symbol: value}, or a an iterable of such dictionaries. The values may
be numeric or symbolic. The more values you can specify beforehand, the faster this
computation will run.
For more documentation, please see the Linearizer class.
mass_matrix
The mass matrix of the system.
mass_matrix_full
The mass matrix of the system, augmented by the kinematic differential equations.
rhs(inv_method=None)
Returns the system’s equations of motion in first order form. The output is the right
hand side of:

x' = |q'| =: f(q, u, r, p, t)

|u'|

The right hand side is what is needed by most numerical ODE integrators.

1694 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters inv_method : str

The specific sympy inverse matrix calculation method to use. For a
list of valid methods, see inv() (page 771)
to_linearizer()
Returns an instance of the Linearizer class, initiated from the data in the Kanes-
Method class. This may be more desirable than using the linearize class method,
as the Linearizer object will allow more efficient recalculation (i.e. about varying
operating points).

LagrangesMethod

class sympy.physics.mechanics.lagrange.LagrangesMethod(Lagrangian, qs,

forcelist=None,
bodies=None,
frame=None,
hol_coneqs=None,
non-
hol_coneqs=None)
Lagrange’s method object.
This object generates the equations of motion in a two step procedure. The first step in-
volves the initialization of LagrangesMethod by supplying the Lagrangian and the gener-
alized coordinates, at the bare minimum. If there are any constraint equations, they can
be supplied as keyword arguments. The Lagrange multipliers are automatically gener-
ated and are equal in number to the constraint equations. Similarly any non-conservative
forces can be supplied in an iterable (as described below and also shown in the example)
along with a ReferenceFrame. This is also discussed further in the __init__ method.

Examples

This is a simple example for a one degree of freedom translational spring-mass-damper.

In this example, we first need to do the kinematics. This involves creating generalized
coordinates and their derivatives. Then we create a point and set its velocity in a frame.

>>> from sympy.physics.mechanics import LagrangesMethod, Lagrangian

>>> from sympy.physics.mechanics import ReferenceFrame, Particle, Point
>>> from sympy.physics.mechanics import dynamicsymbols, kinetic_energy
>>> from sympy import symbols
>>> q = dynamicsymbols('q')
>>> qd = dynamicsymbols('q', 1)
>>> m, k, b = symbols('m k b')
>>> N = ReferenceFrame('N')
>>> P = Point('P')
>>> P.set_vel(N, qd * N.x)

We need to then prepare the information as required by LagrangesMethod to gener-

ate equations of motion. First we create the Particle, which has a point attached to it.
Following this the lagrangian is created from the kinetic and potential energies. Then,
an iterable of nonconservative forces/torques must be constructed, where each item is
a (Point, Vector) or (ReferenceFrame, Vector) tuple, with the Vectors representing the
nonconservative forces or torques.

5.40. Physics Module 1695

SymPy Documentation, Release 1.3

>>> Pa = Particle('Pa', P, m)
>>> Pa.potential_energy = k * q**2 / 2.0
>>> L = Lagrangian(N, Pa)
>>> fl = [(P, -b * qd * N.x)]

Finally we can generate the equations of motion. First we create the LagrangesMethod
object. To do this one must supply the Lagrangian, and the generalized coordinates.
The constraint equations, the forcelist, and the inertial frame may also be provided,
if relevant. Next we generate Lagrange’s equations of motion, such that: Lagrange’s
equations of motion = 0. We have the equations of motion at this point.

>>> l = LagrangesMethod(L, [q], forcelist = fl, frame = N)

>>> print(l.form_lagranges_equations())
Matrix([[b*Derivative(q(t), t) + 1.0*k*q(t) + m*Derivative(q(t), (t, 2))]])

We can also solve for the states using the ‘rhs’ method.

>>> print(l.rhs())
Matrix([[Derivative(q(t), t)], [(-b*Derivative(q(t), t) - 1.0*k*q(t))/m]])

Please refer to the docstrings on each method for more details.

Attributes

q, u (Matrix) Matrices of the generalized coordinates and speeds

forcelist (iterable) Iterable of (Point, vector) or (ReferenceFrame, vector) tuples
describing the forces on the system.
bodies (iterable) Iterable containing the rigid bodies and particles of the sys-
tem.
mass_matrix (Matrix) The system’s mass matrix
forcing (Matrix) The system’s forcing vector
mass_matrix_full
(Matrix) The “mass matrix” for the qdot’s, qdoubledot’s, and the la-
grange multipliers (lam)
forc- (Matrix) The forcing vector for the qdot’s, qdoubledot’s and lagrange
ing_full multipliers (lam)

forcing
Returns the forcing vector from ‘lagranges_equations’ method.
forcing_full
Augments qdots to the forcing vector above.
form_lagranges_equations()
Method to form Lagrange’s equations of motion.
Returns a vector of equations of motion using Lagrange’s equations of the second
kind.
linearize(q_ind=None, qd_ind=None, q_dep=None, qd_dep=None, **kwargs)
Linearize the equations of motion about a symbolic operating point.
If kwarg A_and_B is False (default), returns M, A, B, r for the linearized form, M*[q’,
u’]^T = A*[q_ind, u_ind]^T + B*r.

1696 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

If kwarg A_and_B is True, returns A, B, r for the linearized form dx = A*x + B*r, where
x = [q_ind, u_ind]^T. Note that this is computationally intensive if there are many
symbolic parameters. For this reason, it may be more desirable to use the default
A_and_B=False, returning M, A, and B. Values may then be substituted in to these
matrices, and the state space form found as A = P.T*M.inv()*A, B = P.T*M.inv()*B,
where P = Linearizer.perm_mat.
In both cases, r is found as all dynamicsymbols in the equations of motion that are
not part of q, u, q’, or u’. They are sorted in canonical form.
The operating points may be also entered using the op_point kwarg. This takes a
dictionary of {symbol: value}, or a an iterable of such dictionaries. The values may
be numberic or symbolic. The more values you can specify beforehand, the faster
this computation will run.
For more documentation, please see the Linearizer class.
mass_matrix
Returns the mass matrix, which is augmented by the Lagrange multipliers, if neces-
sary.
If the system is described by ‘n’ generalized coordinates and there are no constraint
equations then an n X n matrix is returned.
If there are ‘n’ generalized coordinates and ‘m’ constraint equations have been sup-
plied during initialization then an n X (n+m) matrix is returned. The (n + m - 1)th
and (n + m)th columns contain the coefficients of the Lagrange multipliers.
mass_matrix_full
Augments the coefficients of qdots to the mass_matrix.
rhs(inv_method=None, **kwargs)
Returns equations that can be solved numerically
Parameters inv_method : str
The specific sympy inverse matrix calculation method to use. For a
list of valid methods, see inv() (page 771)
solve_multipliers(op_point=None, sol_type=’dict’)
Solves for the values of the lagrange multipliers symbolically at the specified oper-
ating point
Parameters op_point : dict or iterable of dicts, optional
Point at which to solve at. The operating point is specified as a dic-
tionary or iterable of dictionaries of {symbol: value}. The value may
be numeric or symbolic itself.
sol_type : str, optional
Solution return type. Valid options are: - ‘dict’: A dict of {symbol :
value} (default) - ‘Matrix’: An ordered column matrix of the solution
to_linearizer(q_ind=None, qd_ind=None, q_dep=None, qd_dep=None)
Returns an instance of the Linearizer class, initiated from the data in the Lagranges-
Method class. This may be more desirable than using the linearize class method,
as the Linearizer object will allow more efficient recalculation (i.e. about varying
operating points).
Parameters q_ind, qd_ind : array_like, optional
The independent generalized coordinates and speeds.

5.40. Physics Module 1697

SymPy Documentation, Release 1.3

q_dep, qd_dep : array_like, optional

The dependent generalized coordinates and speeds.

SymbolicSystem (Docstrings)

SymbolicSystem

class sympy.physics.mechanics.system.SymbolicSystem(coord_states,
right_hand_side,
speeds=None,
mass_matrix=None, coor-
dinate_derivatives=None,
alg_con=None, out-
put_eqns={}, co-
ord_idxs=None,
speed_idxs=None, bod-
ies=None, loads=None)
SymbolicSystem is a class that contains all the information about a system in a symbolic
format such as the equations of motions and the bodies and loads in the system.
There are three ways that the equations of motion can be described for Symbolic System:
[1] Explicit form where the kinematics and dynamics are combined x’
= F_1(x, t, r, p)
[2] Implicit form where the kinematics and dynamics are combined
M_2(x, p) x’ = F_2(x, t, r, p)
[3] Implicit form where the kinematics and dynamics are separate
M_3(q, p) u’ = F_3(q, u, t, r, p) q’ = G(q, u, t, r, p)
where
x : states, e.g. [q, u] t : time r : specified (exogenous) inputs p : constants q : generalized
coordinates u : generalized speeds F_1 : right hand side of the combined equations in
explicit form F_2 : right hand side of the combined equations in implicit form F_3 : right
hand side of the dynamical equations in implicit form M_2 : mass matrix of the combined
equations in implicit form M_3 : mass matrix of the dynamical equations in implicit form
G : right hand side of the kinematical differential equations
Parameters coord_states : ordered iterable of functions of time
This input will either be a collection of the coordinates or states
of the system depending on whether or not the speeds are also
given. If speeds are specified this input will be assumed to be the
coordinates otherwise this input will be assumed to be the states.

right_hand_side [Matrix] This variable is the right hand side of the

equations of motion in any of the forms. The specific form will be
assumed depending on whether a mass matrix or coordinate deriva-
tives are given.
speeds [ordered iterable of functions of time, optional] This is a col-
lection of the generalized speeds of the system. If given it will be
assumed that the first argument (coord_states) will represent the
generalized coordinates of the system.

1698 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

mass_matrix [Matrix, optional] The matrix of the implicit forms of

the equations of motion (forms [2] and [3]). The distinction between
the forms is determined by whether or not the coordinate deriva-
tives are passed in. If they are given form [3] will be assumed oth-
erwise form [2] is assumed.
coordinate_derivatives [Matrix, optional] The right hand side of
the kinematical equations in explicit form. If given it will be as-
sumed that the equations of motion are being entered in form [3].
alg_con [Iterable, optional] The indexes of the rows in the equations
of motion that contain algebraic constraints instead of differential
equations. If the equations are input in form [3], it will be assumed
the indexes are referencing the mass_matrix/right_hand_side com-
bination and not the coordinate_derivatives.
output_eqns [Dictionary, optional] Any output equations that are de-
sired to be tracked are stored in a dictionary where the key corre-
sponds to the name given for the specific equation and the value is
the equation itself in symbolic form
coord_idxs [Iterable, optional] If coord_states corresponds to the
states rather than the coordinates this variable will tell Symbol-
icSystem which indexes of the states correspond to generalized co-
ordinates.
speed_idxs [Iterable, optional] If coord_states corresponds to the
states rather than the coordinates this variable will tell Symbol-
icSystem which indexes of the states correspond to generalized
speeds.
bodies [iterable of Body/Rigidbody objects, optional] Iterable con-
taining the bodies of the system
loads [iterable of load instances (described below), optional] Iter-
able containing the loads of the system where forces are given
by (point of application, force vector) and torques are given by
(reference frame acting upon, torque vector). Ex [(point, force),
(ref_frame, torque)]

Notes

m : number of generalized speeds n : number of generalized coordinates o : number of

states

Example

As a simple example, the dynamics of a simple pendulum will be input into a Symbol-
icSystem object manually. First some imports will be needed and then symbols will be
set up for the length of the pendulum (l), mass at the end of the pendulum (m), and a
constant for gravity (g).

>>> from sympy import Matrix, sin, symbols

>>> from sympy.physics.mechanics import dynamicsymbols, SymbolicSystem
>>> l, m, g = symbols('l m g')

5.40. Physics Module 1699

SymPy Documentation, Release 1.3

The system will be defined by an angle of theta from the vertical and a generalized speed
of omega will be used where omega = theta_dot.

>>> theta, omega = dynamicsymbols('theta omega')

Now the equations of motion are ready to be formed and passed to the SymbolicSystem
object.

>>> kin_explicit_rhs = Matrix([omega])

>>> dyn_implicit_mat = Matrix([l**2 * m])
>>> dyn_implicit_rhs = Matrix([-g * l * m * sin(theta)])
>>> symsystem = SymbolicSystem([theta], dyn_implicit_rhs, [omega],
... dyn_implicit_mat)

1700 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

co- (Matrix, shape(n, 1)) This is a matrix containing the generalized coordinates of
or- the system
di-
nates
speeds(Matrix, shape(m, 1)) This is a matrix containing the generalized speeds of the
system
states (Matrix, shape(o, 1)) This is a matrix containing the state variables of the system
alg_con(List) This list contains the indices of the algebraic constraints in the combined
equations of motion. The presence of these constraints requires that a DAE
solver be used instead of an ODE solver. If the system is given in form [3] the
alg_con variable will be adjusted such that it is a representation of the combined
kinematics and dynamics thus make sure it always matches the mass matrix
entered.
dyn_implicit_mat
(Matrix, shape(m, m)) This is the M matrix in form [3] of the equations of motion
(the mass matrix or generalized inertia matrix of the dynamical equations of
motion in implicit form).
dyn_implicit_rhs
(Matrix, shape(m, 1)) This is the F vector in form [3] of the equations of motion
(the right hand side of the dynamical equations of motion in implicit form).
comb_implicit_mat
(Matrix, shape(o, o)) This is the M matrix in form [2] of the equations of motion.
This matrix contains a block diagonal structure where the top left block (the first
rows) represent the matrix in the implicit form of the kinematical equations and
the bottom right block (the last rows) represent the matrix in the implicit form
of the dynamical equations.
comb_implicit_rhs
(Matrix, shape(o, 1)) This is the F vector in form [2] of the equations of motion.
The top part of the vector represents the right hand side of the implicit form
of the kinemaical equations and the bottom of the vector represents the right
hand side of the implicit form of the dynamical equations of motion.
comb_explicit_rhs
(Matrix, shape(o, 1)) This vector represents the right hand side of the combined
equations of motion in explicit form (form [1] from above).
kin_explicit_rhs
(Matrix, shape(m, 1)) This is the right hand side of the explicit form of the kine-
matical equations of motion as can be seen in form [3] (the G matrix).
out- (Dictionary) If output equations were given they are stored in a dictionary where
put_eqns
the key corresponds to the name given for the specific equation and the value
is the equation itself in symbolic form
bod- (Tuple) If the bodies in the system were given they are stored in a tuple for
ies future access
loads (Tuple) If the loads in the system were given they are stored in a tuple for future
access. This includes forces and torques where forces are given by (point of
application, force vector) and torques are given by (reference frame acted upon,
torque vector).

alg_con
Returns a list with the indices of the rows containing algebraic constraints in the
combined form of the equations of motion
bodies
Returns the bodies in the system
comb_explicit_rhs
Returns the right hand side of the equations of motion in explicit form, x’ = F, where
the kinematical equations are included

5.40. Physics Module 1701

SymPy Documentation, Release 1.3

comb_implicit_mat
Returns the matrix, M, corresponding to the equations of motion in implicit form
(form [2]), M x’ = F, where the kinematical equations are included
comb_implicit_rhs
Returns the column matrix, F, corresponding to the equations of motion in implicit
form (form [2]), M x’ = F, where the kinematical equations are included
compute_explicit_form()
If the explicit right hand side of the combined equations of motion is to provided
upon initialization, this method will calculate it. This calculation can potentially
take awhile to compute.
constant_symbols()
Returns a column matrix containing all of the symbols in the system that do not
depend on time
coordinates
Returns the column matrix of the generalized coordinates
dyn_implicit_mat
Returns the matrix, M, corresponding to the dynamic equations in implicit form, M
x’ = F, where the kinematical equations are not included
dyn_implicit_rhs
Returns the column matrix, F, corresponding to the dynamic equations in implicit
form, M x’ = F, where the kinematical equations are not included
dynamic_symbols()
Returns a column matrix containing all of the symbols in the system that depend on
time
kin_explicit_rhs
Returns the right hand side of the kinematical equations in explicit form, q’ = G
loads
Returns the loads in the system
speeds
Returns the column matrix of generalized speeds
states
Returns the column matrix of the state variables

Linearization (Docstrings)

Linearizer

class sympy.physics.mechanics.linearize.Linearizer(f_0, f_1, f_2, f_3, f_4, f_c,

f_v, f_a, q, u, q_i=None,
q_d=None, u_i=None,
u_d=None, r=None,
lams=None)
This object holds the general model form for a dynamic system. This model is used for
computing the linearized form of the system, while properly dealing with constraints
leading to dependent coordinates and speeds.

1702 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

f_0, f_1, f_2, f_3, f_4, (Matrix) Matrices holding the general system form.
f_c, f_v, f_a
q, u, r (Matrix) Matrices holding the generalized coordinates,
speeds, and input vectors.
q_i, u_i (Matrix) Matrices of the independent generalized coordi-
nates and speeds.
q_d, u_d (Matrix) Matrices of the dependent generalized coordinates
and speeds.
perm_mat (Matrix) Permutation matrix such that [q_ind, u_ind]^T =
perm_mat*[q, u]^T

linearize(op_point=None, A_and_B=False, simplify=False)

Linearize the system about the operating point. Note that q_op, u_op, qd_op, ud_op
must satisfy the equations of motion. These may be either symbolic or numeric.
Parameters op_point : dict or iterable of dicts, optional
Dictionary or iterable of dictionaries containing the operating point
conditions. These will be substituted in to the linearized system be-
fore the linearization is complete. Leave blank if you want a com-
pletely symbolic form. Note that any reduction in symbols (whether
substituted for numbers or expressions with a common parameter)
will result in faster runtime.
A_and_B : bool, optional
If A_and_B=False (default), (M, A, B) is returned for forming [M]*[q,
u]^T = [A]*[q_ind, u_ind]^T + [B]r. If A_and_B=True, (A, B) is re-
turned for forming dx = [A]x + [B]r, where x = [q_ind, u_ind]^T.
simplify : bool, optional
Determines if returned values are simplified before return. For large
expressions this may be time consuming. Default is False.

Potential Issues

Note that the process of solving with A_and_B=True is computationally intensive if

there are many symbolic parameters. For this reason, it may be more desirable to
use the default A_and_B=False, returning M, A, and B. More values may then be
substituted in to these matrices later on. The state space form can then be found as
A = P.T*M.LUsolve(A), B = P.T*M.LUsolve(B), where P = Linearizer.perm_mat.

Expression Manipulation (Docstrings)

msubs

sympy.physics.mechanics.msubs(expr, *sub_dicts, **kwargs)

A custom subs for use on expressions derived in physics.mechanics.
Traverses the expression tree once, performing the subs found in sub_dicts. Terms inside
Derivative expressions are ignored:

5.40. Physics Module 1703

SymPy Documentation, Release 1.3

>>> from sympy.physics.mechanics import dynamicsymbols, msubs

>>> x = dynamicsymbols('x')
>>> msubs(x.diff() + x, {x: 1})
Derivative(x(t), t) + 1

Note that sub_dicts can be a single dictionary, or several dictionaries:

>>> x, y, z = dynamicsymbols('x, y, z')
>>> sub1 = {x: 1, y: 2}
>>> sub2 = {z: 3, x.diff(): 4}
>>> msubs(x.diff() + x + y + z, sub1, sub2)
10

If smart=True (default False), also checks for conditions that may result in nan, but if
simplified would yield a valid expression. For example:
>>> from sympy import sin, tan
>>> (sin(x)/tan(x)).subs(x, 0)
nan
>>> msubs(sin(x)/tan(x), {x: 0}, smart=True)
1

It does this by first replacing all tan with sin/cos. Then each node is traversed. If
the node is a fraction, subs is first evaluated on the denominator. If this results in 0,
simplification of the entire fraction is attempted. Using this selective simplification, only
subexpressions that result in 1/0 are targeted, resulting in faster performance.

find_dynamicsymbols

sympy.physics.mechanics.find_dynamicsymbols(expression, exclude=None, refer-

ence_frame=None)
Find all dynamicsymbols in expression.
If the optional exclude kwarg is used, only dynamicsymbols not in the iterable ex-
clude are returned. If we intend to apply this function on a vector, the optional ‘’refer-
ence_frame’’ is also used to inform about the corresponding frame with respect to which
the dynamic symbols of the given vector is to be determined.
Parameters expression : sympy expression
exclude : iterable of dynamicsymbols, optional
reference_frame : ReferenceFrame, optional
The frame with respect to which the dynamic symbols of the given
vector is to be determined.

Examples

>>> from sympy.physics.mechanics import dynamicsymbols, find_dynamicsymbols

>>> from sympy.physics.mechanics import ReferenceFrame
>>> x, y = dynamicsymbols('x, y')
>>> expr = x + x.diff()*y
>>> find_dynamicsymbols(expr)
{x(t), y(t), Derivative(x(t), t)}
(continues on next page)

1704 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> find_dynamicsymbols(expr, exclude=[x, y])
{Derivative(x(t), t)}
>>> a, b, c = dynamicsymbols('a, b, c')
>>> A = ReferenceFrame('A')
>>> v = a * A.x + b * A.y + c * A.z
>>> find_dynamicsymbols(v, reference_frame=A)
{a(t), b(t), c(t)}

Printing (Docstrings)

mechanics_printing

This function is the same as physics.vector’s time_derivative_printing.

mprint

This function is the same as physics.vector’s vprint.

mpprint

This function is the same as physics.vector’s vpprint.

mlatex

This function is the same as physics.vector’s vlatex.

Body (Docstrings)

Body

class sympy.physics.mechanics.body.Body(name, masscenter=None, mass=None,

frame=None, central_inertia=None)
Body is a common representation of either a RigidBody or a Particle SymPy object
depending on what is passed in during initialization. If a mass is passed in and cen-
tral_inertia is left as None, the Particle object is created. Otherwise a RigidBody object
will be created.
The attributes that Body possesses will be the same as a Particle instance or a Rigid Body
instance depending on which was created. Additional attributes are listed below.
Parameters name : String
Defines the name of the body. It is used as the base for defining body
specific properties.
masscenter : Point, optional
A point that represents the center of mass of the body or particle. If
no point is given, a point is generated.

5.40. Physics Module 1705

SymPy Documentation, Release 1.3

mass : Sympifyable, optional

A Sympifyable object which represents the mass of the body. If no
mass is passed, one is generated.
frame : ReferenceFrame, optional
The ReferenceFrame that represents the reference frame of the body.
If no frame is given, a frame is generated.
central_inertia : Dyadic, optional
Central inertia dyadic of the body. If none is passed while creating
RigidBody, a default inertia is generated.

Examples

Default behaviour. This results in the creation of a RigidBody object for which the mass,
mass center, frame and inertia attributes are given default values.

>>> from sympy.physics.mechanics import Body

>>> body = Body('name_of_body')

This next example demonstrates the code required to specify all of the values of the Body
object. Note this will also create a RigidBody version of the Body object.

>>> from sympy import Symbol

>>> from sympy.physics.mechanics import ReferenceFrame, Point, inertia
>>> from sympy.physics.mechanics import Body
>>> mass = Symbol('mass')
>>> masscenter = Point('masscenter')
>>> frame = ReferenceFrame('frame')
>>> ixx = Symbol('ixx')
>>> body_inertia = inertia(frame, ixx, 0, 0)
>>> body = Body('name_of_body', masscenter, mass, frame, body_inertia)

The minimal code required to create a Particle version of the Body object involves simply
passing in a name and a mass.

>>> from sympy import Symbol

>>> from sympy.physics.mechanics import Body
>>> mass = Symbol('mass')
>>> body = Body('name_of_body', mass=mass)

The Particle version of the Body object can also receive a masscenter point and a refer-
ence frame, just not an inertia.

1706 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Attributes

name (string) The body’s name

mass- (Point) The point which represents the center of mass of the rigid body
cen-
ter
frame (ReferenceFrame) The reference frame which the body is fixed in
mass (Sympifyable) The body’s mass
iner- ((Dyadic, Point)) The body’s inertia around its center of mass. This attribute
tia is specific to the rigid body form of Body and is left undefined for the Particle
form
loads (iterable) This list contains information on the different loads acting on the
Body. Forces are listed as a (point, vector) tuple and torques are listed as
(reference frame, vector) tuples.

apply_force(vec, point=None)
Adds a force to a point (center of mass by default) on the body.
Parameters vec: Vector
Defines the force vector. Can be any vector w.r.t any frame or com-
binations of frames.
point: Point, optional
Defines the point on which the force is applied. Default is the Body’s
center of mass.

Example

The first example applies a gravitational force in the x direction of Body’s frame to
the body’s center of mass.
>>> from sympy import Symbol
>>> from sympy.physics.mechanics import Body
>>> body = Body('body')
>>> g = Symbol('g')
>>> body.apply_force(body.mass * g * body.frame.x)

To apply force to any other point than center of mass, pass that point as well. This
example applies a gravitational force to a point a distance l from the body’s center
of mass in the y direction. The force is again applied in the x direction.
>>> from sympy import Symbol
>>> from sympy.physics.mechanics import Body
>>> body = Body('body')
>>> g = Symbol('g')
>>> l = Symbol('l')
>>> point = body.masscenter.locatenew('force_point', l *
... body.frame.y)
>>> body.apply_force(body.mass * g * body.frame.x, point)

apply_torque(vec)
Adds a torque to the body.
Parameters vec: Vector

5.40. Physics Module 1707

SymPy Documentation, Release 1.3

Defines the torque vector. Can be any vector w.r.t any frame or com-
binations of frame.

Example

This example adds a simple torque around the body’s z axis.

>>> from sympy import Symbol

>>> from sympy.physics.mechanics import Body
>>> body = Body('body')
>>> T = Symbol('T')
>>> body.apply_torque(T * body.frame.z)

Quantum Mechanics

Abstract

Contains Docstrings of Physics-Quantum module

Quantum Functions

Anticommutator

The anti-commutator: {A,B} = A*B + B*A.

class sympy.physics.quantum.anticommutator.AntiCommutator
The standard anticommutator, in an unevaluated state.
Evaluating an anticommutator is defined [R470] as: {A, B} = A*B + B*A. This class
returns the anticommutator in an unevaluated form. To evaluate the anticommutator,
use the .doit() method.
Canonical ordering of an anticommutator is {A, B} for A < B. The arguments of the
anticommutator are put into canonical order using __cmp__. If B < A, then {A, B} is
returned as {B, A}.
Parameters A : Expr
The first argument of the anticommutator {A,B}.
B : Expr
The second argument of the anticommutator {A,B}.

References

[R470]

1708 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> from sympy.physics.quantum import AntiCommutator
>>> from sympy.physics.quantum import Operator, Dagger
>>> x, y = symbols('x,y')
>>> A = Operator('A')
>>> B = Operator('B')

Create an anticommutator and use doit() to multiply them out.

>>> ac = AntiCommutator(A,B); ac
{A,B}
>>> ac.doit()
A*B + B*A

The commutator orders it arguments in canonical order:

>>> ac = AntiCommutator(B,A); ac
{A,B}

Commutative constants are factored out:

>>> AntiCommutator(3*x*A,x*y*B)
3*x**2*y*{A,B}

Adjoint operations applied to the anticommutator are properly applied to the arguments:

>>> Dagger(AntiCommutator(A,B))
{Dagger(A),Dagger(B)}

doit(**hints)
Evaluate anticommutator

Clebsch-Gordan Coefficients

Clebsch-Gordon Coefficients.
class sympy.physics.quantum.cg.CG
Class for Clebsch-Gordan coefficient
Clebsch-Gordan coefficients describe the angular momentum coupling between two sys-
tems. The coefficients give the expansion of a coupled total angular momentum state
and an uncoupled tensor product state. The Clebsch-Gordan coefficients are defined as
[R471]:

Cjj21,m
,m1
2 ,j3 ,m3
= ⟨j1 , m1 ; j2 , m2 |j3 , m3 ⟩

Parameters j1, m1, j2, m2, j3, m3 : Number, Symbol

Terms determining the angular momentum of coupled angular mo-
mentum systems.
See also:

Wigner3j (page 1710) Wigner-3j symbols

5.40. Physics Module 1709

SymPy Documentation, Release 1.3

References

[R471]

Examples

Define a Clebsch-Gordan coefficient and evaluate its value

>>> from sympy.physics.quantum.cg import CG

>>> from sympy import S
>>> cg = CG(S(3)/2, S(3)/2, S(1)/2, -S(1)/2, 1, 1)
>>> cg
CG(3/2, 3/2, 1/2, -1/2, 1, 1)
>>> cg.doit()
sqrt(3)/2

class sympy.physics.quantum.cg.Wigner3j
Class for the Wigner-3j symbols
Wigner 3j-symbols are coefficients determined by the coupling of two angular momenta.
When created, they are expressed as symbolic quantities that, for numerical parameters,
can be evaluated using the .doit() method [R472].
Parameters j1, m1, j2, m2, j3, m3 : Number, Symbol
Terms determining the angular momentum of coupled angular mo-
mentum systems.
See also:

CG (page 1709) Clebsch-Gordan coefficients

References

[R472]

Examples

Declare a Wigner-3j coefficient and calculate its value

>>> from sympy.physics.quantum.cg import Wigner3j

>>> w3j = Wigner3j(6,0,4,0,2,0)
>>> w3j
Wigner3j(6, 0, 4, 0, 2, 0)
>>> w3j.doit()
sqrt(715)/143

class sympy.physics.quantum.cg.Wigner6j
Class for the Wigner-6j symbols
See also:

Wigner3j (page 1710) Wigner-3j symbols

1710 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.quantum.cg.Wigner9j
Class for the Wigner-9j symbols
See also:

Wigner3j (page 1710) Wigner-3j symbols

sympy.physics.quantum.cg.cg_simp(e)
Simplify and combine CG coefficients
This function uses various symmetry and properties of sums and products of Clebsch-
Gordan coefficients to simplify statements involving these terms [R473].
See also:

CG (page 1709) Clebsh-Gordan coefficients

References

[R473]

Examples

Simplify the sum over CG(a,alpha,0,0,a,alpha) for all alpha to 2*a+1

>>> from sympy.physics.quantum.cg import CG, cg_simp

>>> a = CG(1,1,0,0,1,1)
>>> b = CG(1,0,0,0,1,0)
>>> c = CG(1,-1,0,0,1,-1)
>>> cg_simp(a+b+c)
3

Commutator

The commutator: [A,B] = A*B - B*A.

class sympy.physics.quantum.commutator.Commutator
The standard commutator, in an unevaluated state.
Evaluating a commutator is defined [R474] as: [A, B] = A*B - B*A. This class returns
the commutator in an unevaluated form. To evaluate the commutator, use the .doit()
method.
Canonical ordering of a commutator is [A, B] for A < B. The arguments of the commu-
tator are put into canonical order using __cmp__. If B < A, then [B, A] is returned as
-[A, B].
Parameters A : Expr
The first argument of the commutator [A,B].
B : Expr
The second argument of the commutator [A,B].

5.40. Physics Module 1711

SymPy Documentation, Release 1.3

References

[R474]

Examples

>>> from sympy.physics.quantum import Commutator, Dagger, Operator

>>> from sympy.abc import x, y
>>> A = Operator('A')
>>> B = Operator('B')
>>> C = Operator('C')

Create a commutator and use .doit() to evaluate it:

>>> comm = Commutator(A, B)

>>> comm
[A,B]
>>> comm.doit()
A*B - B*A

The commutator orders it arguments in canonical order:

>>> comm = Commutator(B, A); comm

-[A,B]

Commutative constants are factored out:

>>> Commutator(3*x*A, x*y*B)

3*x**2*y*[A,B]

Using .expand(commutator=True), the standard commutator expansion rules can be

applied:

>>> Commutator(A+B, C).expand(commutator=True)

[A,C] + [B,C]
>>> Commutator(A, B+C).expand(commutator=True)
[A,B] + [A,C]
>>> Commutator(A*B, C).expand(commutator=True)
[A,C]*B + A*[B,C]
>>> Commutator(A, B*C).expand(commutator=True)
[A,B]*C + B*[A,C]

Adjoint operations applied to the commutator are properly applied to the arguments:

>>> Dagger(Commutator(A, B))

-[Dagger(A),Dagger(B)]

doit(**hints)
Evaluate commutator

Constants

Constants (like hbar) related to quantum mechanics.

1712 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Dagger

Hermitian conjugation.
class sympy.physics.quantum.dagger.Dagger
General Hermitian conjugate operation.
Take the Hermetian conjugate of an argument [R475]. For matrices this operation is
equivalent to transpose and complex conjugate [R476].
Parameters arg : Expr
The sympy expression that we want to take the dagger of.

References

[R475], [R476]

Examples

Daggering various quantum objects:

>>> from sympy.physics.quantum.dagger import Dagger

>>> from sympy.physics.quantum.state import Ket, Bra
>>> from sympy.physics.quantum.operator import Operator
>>> Dagger(Ket('psi'))
<psi|
>>> Dagger(Bra('phi'))
|phi>
>>> Dagger(Operator('A'))
Dagger(A)

Inner and outer products:

>>> from sympy.physics.quantum import InnerProduct, OuterProduct

>>> Dagger(InnerProduct(Bra('a'), Ket('b')))
<b|a>
>>> Dagger(OuterProduct(Ket('a'), Bra('b')))
|b><a|

Powers, sums and products:

>>> A = Operator('A')
>>> B = Operator('B')
>>> Dagger(A*B)
Dagger(B)*Dagger(A)
>>> Dagger(A+B)
Dagger(A) + Dagger(B)
>>> Dagger(A**2)
Dagger(A)**2

Dagger also seamlessly handles complex numbers and matrices:

>>> from sympy import Matrix, I

>>> m = Matrix([[1,I],[2,I]])
(continues on next page)

5.40. Physics Module 1713

SymPy Documentation, Release 1.3

(continued from previous page)

>>> m
Matrix([
[1, I],
[2, I]])
>>> Dagger(m)
Matrix([
[ 1, 2],
[-I, -I]])

Inner Product

Symbolic inner product.

class sympy.physics.quantum.innerproduct.InnerProduct
An unevaluated inner product between a Bra and a Ket [1].
Parameters bra : BraBase or subclass
The bra on the left side of the inner product.
ket : KetBase or subclass
The ket on the right side of the inner product.

References

[R479]

Examples

Create an InnerProduct and check its properties:

>>> from sympy.physics.quantum import Bra, Ket, InnerProduct

>>> b = Bra('b')
>>> k = Ket('k')
>>> ip = b*k
>>> ip
<b|k>
>>> ip.bra
<b|
>>> ip.ket
|k>

In simple products of kets and bras inner products will be automatically identified and
created:

>>> b*k
<b|k>

But in more complex expressions, there is ambiguity in whether inner or outer products
should be created:

1714 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> k*b*k*b
|k><b|*|k>*<b|

A user can force the creation of a inner products in a complex expression by using paren-
theses to group the bra and ket:

>>> k*(b*k)*b
<b|k>*|k>*<b|

Notice how the inner product <b|k> moved to the left of the expression because inner
products are commutative complex numbers.

Tensor Product

Abstract tensor product.

class sympy.physics.quantum.tensorproduct.TensorProduct
The tensor product of two or more arguments.
For matrices, this uses matrix_tensor_product to compute the Kronecker or tensor
product matrix. For other objects a symbolic TensorProduct instance is returned. The
tensor product is a non-commutative multiplication that is used primarily with operators
and states in quantum mechanics.
Currently, the tensor product distinguishes between commutative and non-commutative
arguments. Commutative arguments are assumed to be scalars and are pulled out in
front of the TensorProduct. Non-commutative arguments remain in the resulting Ten-
sorProduct.
Parameters args : tuple
A sequence of the objects to take the tensor product of.

Examples

Start with a simple tensor product of sympy matrices:

>>> from sympy import I, Matrix, symbols

>>> from sympy.physics.quantum import TensorProduct

>>> m1 = Matrix([[1,2],[3,4]])
>>> m2 = Matrix([[1,0],[0,1]])
>>> TensorProduct(m1, m2)
Matrix([
[1, 0, 2, 0],
[0, 1, 0, 2],
[3, 0, 4, 0],
[0, 3, 0, 4]])
>>> TensorProduct(m2, m1)
Matrix([
[1, 2, 0, 0],
[3, 4, 0, 0],
[0, 0, 1, 2],
[0, 0, 3, 4]])

We can also construct tensor products of non-commutative symbols:

5.40. Physics Module 1715

SymPy Documentation, Release 1.3

>>> from sympy import Symbol

>>> A = Symbol('A',commutative=False)
>>> B = Symbol('B',commutative=False)
>>> tp = TensorProduct(A, B)
>>> tp
AxB

We can take the dagger of a tensor product (note the order does NOT reverse like the
dagger of a normal product):

>>> from sympy.physics.quantum import Dagger

>>> Dagger(tp)
Dagger(A)xDagger(B)

Expand can be used to distribute a tensor product across addition:

>>> C = Symbol('C',commutative=False)
>>> tp = TensorProduct(A+B,C)
>>> tp
(A + B)xC
>>> tp.expand(tensorproduct=True)
AxC + BxC

sympy.physics.quantum.tensorproduct.tensor_product_simp(e, **hints)
Try to simplify and combine TensorProducts.
In general this will try to pull expressions inside of TensorProducts. It currently only
works for relatively simple cases where the products have only scalars, raw Tensor-
Products, not Add, Pow, Commutators of TensorProducts. It is best to see what it does
by showing examples.

Examples

>>> from sympy.physics.quantum import tensor_product_simp

>>> from sympy.physics.quantum import TensorProduct
>>> from sympy import Symbol
>>> A = Symbol('A',commutative=False)
>>> B = Symbol('B',commutative=False)
>>> C = Symbol('C',commutative=False)
>>> D = Symbol('D',commutative=False)

First see what happens to products of tensor products:

>>> e = TensorProduct(A,B)*TensorProduct(C,D)
>>> e
AxB*CxD
>>> tensor_product_simp(e)
(A*C)x(B*D)

This is the core logic of this function, and it works inside, powers, sums, commutators
and anticommutators as well:

>>> tensor_product_simp(e**2)
(A*C)x(B*D)**2

1716 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

States and Operators

Cartesian Operators and States

Operators and states for 1D cartesian position and momentum.

TODO:
• Add 3D classes to mappings in operatorset.py
class sympy.physics.quantum.cartesian.XOp
1D cartesian position operator.
class sympy.physics.quantum.cartesian.YOp
Y cartesian coordinate operator (for 2D or 3D systems)
class sympy.physics.quantum.cartesian.ZOp
Z cartesian coordinate operator (for 3D systems)
class sympy.physics.quantum.cartesian.PxOp
1D cartesian momentum operator.
class sympy.physics.quantum.cartesian.XKet
1D cartesian position eigenket.
position
The position of the state.
class sympy.physics.quantum.cartesian.XBra
1D cartesian position eigenbra.
position
The position of the state.
class sympy.physics.quantum.cartesian.PxKet
1D cartesian momentum eigenket.
momentum
The momentum of the state.
class sympy.physics.quantum.cartesian.PxBra
1D cartesian momentum eigenbra.
momentum
The momentum of the state.
class sympy.physics.quantum.cartesian.PositionState3D
Base class for 3D cartesian position eigenstates
position_x
The x coordinate of the state
position_y
The y coordinate of the state
position_z
The z coordinate of the state
class sympy.physics.quantum.cartesian.PositionKet3D
3D cartesian position eigenket
class sympy.physics.quantum.cartesian.PositionBra3D
3D cartesian position eigenbra

5.40. Physics Module 1717

SymPy Documentation, Release 1.3

Hilbert Space

Hilbert spaces for quantum mechanics.

Authors: * Brian Granger * Matt Curry
class sympy.physics.quantum.hilbert.HilbertSpace
An abstract Hilbert space for quantum mechanics.
In short, a Hilbert space is an abstract vector space that is complete with inner products
defined [R477].

References

[R477]

Examples

>>> from sympy.physics.quantum.hilbert import HilbertSpace

>>> hs = HilbertSpace()
>>> hs
H

dimension
Return the Hilbert dimension of the space.
class sympy.physics.quantum.hilbert.ComplexSpace
Finite dimensional Hilbert space of complex vectors.
The elements of this Hilbert space are n-dimensional complex valued vectors with the
usual inner product that takes the complex conjugate of the vector on the right.
A classic example of this type of Hilbert space is spin-1/2, which is ComplexSpace(2).
Generalizing to spin-s, the space is ComplexSpace(2*s+1). Quantum computing with N
qubits is done with the direct product space ComplexSpace(2)**N.

Examples

>>> from sympy import symbols

>>> from sympy.physics.quantum.hilbert import ComplexSpace
>>> c1 = ComplexSpace(2)
>>> c1
C(2)
>>> c1.dimension
2

>>> n = symbols('n')
>>> c2 = ComplexSpace(n)
>>> c2
C(n)
>>> c2.dimension
n

1718 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.quantum.hilbert.L2
The Hilbert space of square integrable functions on an interval.
An L2 object takes in a single sympy Interval argument which represents the interval its
functions (vectors) are defined on.

Examples

>>> from sympy import Interval, oo

>>> from sympy.physics.quantum.hilbert import L2
>>> hs = L2(Interval(0,oo))
>>> hs
L2(Interval(0, oo))
>>> hs.dimension
oo
>>> hs.interval
Interval(0, oo)

class sympy.physics.quantum.hilbert.FockSpace
The Hilbert space for second quantization.
Technically, this Hilbert space is a infinite direct sum of direct products of single particle
Hilbert spaces [R478]. This is a mess, so we have a class to represent it directly.

References

[R478]

Examples

>>> from sympy.physics.quantum.hilbert import FockSpace

>>> hs = FockSpace()
>>> hs
F
>>> hs.dimension
oo

Operator

Quantum mechanical operators.

TODO:
• Fix early 0 in apply_operators.
• Debug and test apply_operators.
• Get cse working with classes in this file.
• Doctests and documentation of special methods for InnerProduct, Commutator, Anti-
Commutator, represent, apply_operators.

5.40. Physics Module 1719

SymPy Documentation, Release 1.3

class sympy.physics.quantum.operator.Operator
Base class for non-commuting quantum operators.
An operator maps between quantum states [R480]. In quantum mechanics, observables
(including, but not limited to, measured physical values) are represented as Hermitian
operators [R481].
Parameters args : tuple
The list of numbers or parameters that uniquely specify the operator.
For time-dependent operators, this will include the time.

References

[R480], [R481]

Examples

Create an operator and examine its attributes:

>>> from sympy.physics.quantum import Operator

>>> from sympy import symbols, I
>>> A = Operator('A')
>>> A
A
>>> A.hilbert_space
H
>>> A.label
(A,)
>>> A.is_commutative
False

Create another operator and do some arithmetic operations:

>>> B = Operator('B')
>>> C = 2*A*A + I*B
>>> C
2*A**2 + I*B

Operators don’t commute:

>>> A.is_commutative
False
>>> B.is_commutative
False
>>> A*B == B*A
False

Polymonials of operators respect the commutation properties:

>>> e = (A+B)**3
>>> e.expand()
A*B*A + A*B**2 + A**2*B + A**3 + B*A*B + B*A**2 + B**2*A + B**3

Operator inverses are handle symbolically:

1720 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> A.inv()
A**(-1)
>>> A*A.inv()
1

class sympy.physics.quantum.operator.HermitianOperator
A Hermitian operator that satisfies H == Dagger(H).
Parameters args : tuple
The list of numbers or parameters that uniquely specify the operator.
For time-dependent operators, this will include the time.

Examples

>>> from sympy.physics.quantum import Dagger, HermitianOperator

>>> H = HermitianOperator('H')
>>> Dagger(H)
H

class sympy.physics.quantum.operator.UnitaryOperator
A unitary operator that satisfies U*Dagger(U) == 1.
Parameters args : tuple
The list of numbers or parameters that uniquely specify the operator.
For time-dependent operators, this will include the time.

Examples

>>> from sympy.physics.quantum import Dagger, UnitaryOperator

>>> U = UnitaryOperator('U')
>>> U*Dagger(U)
1

class sympy.physics.quantum.operator.IdentityOperator(*args, **hints)

An identity operator I that satisfies op * I == I * op == op for any operator op.
Parameters N : Integer
Optional parameter that specifies the dimension of the Hilbert space
of operator. This is used when generating a matrix representation.

Examples

>>> from sympy.physics.quantum import IdentityOperator

>>> IdentityOperator()
I

class sympy.physics.quantum.operator.OuterProduct
An unevaluated outer product between a ket and bra.

5.40. Physics Module 1721

SymPy Documentation, Release 1.3

This constructs an outer product between any subclass of KetBase and BraBase as
|a><b|. An OuterProduct inherits from Operator as they act as operators in quantum
expressions. For reference see [R482].
Parameters ket : KetBase
The ket on the left side of the outer product.
bar : BraBase
The bra on the right side of the outer product.

References

[R482]

Examples

Create a simple outer product by hand and take its dagger:

>>> from sympy.physics.quantum import Ket, Bra, OuterProduct, Dagger
>>> from sympy.physics.quantum import Operator

>>> k = Ket('k')
>>> b = Bra('b')
>>> op = OuterProduct(k, b)
>>> op
|k><b|
>>> op.hilbert_space
H
>>> op.ket
|k>
>>> op.bra
<b|
>>> Dagger(op)
|b><k|

In simple products of kets and bras outer products will be automatically identified and
created:
>>> k*b
|k><b|

But in more complex expressions, outer products are not automatically created:
>>> A = Operator('A')
>>> A*k*b
A*|k>*<b|

A user can force the creation of an outer product in a complex expression by using paren-
theses to group the ket and bra:
>>> A*(k*b)
A*|k><b|

bra
Return the bra on the right side of the outer product.

1722 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

ket
Return the ket on the left side of the outer product.
class sympy.physics.quantum.operator.DifferentialOperator
An operator for representing the differential operator, i.e. d/dx
It is initialized by passing two arguments. The first is an arbitrary expression that in-
volves a function, such as Derivative(f(x), x). The second is the function (e.g. f(x))
which we are to replace with the Wavefunction that this DifferentialOperator is ap-
plied to.
Parameters expr : Expr
The arbitrary expression which the appropriate Wavefunction is to be
substituted into
func : Expr
A function (e.g. f(x)) which is to be replaced with the appropriate
Wavefunction when this DifferentialOperator is applied

Examples

You can define a completely arbitrary expression and specify where the Wavefunction is
to be substituted
>>> from sympy import Derivative, Function, Symbol
>>> from sympy.physics.quantum.operator import DifferentialOperator
>>> from sympy.physics.quantum.state import Wavefunction
>>> from sympy.physics.quantum.qapply import qapply
>>> f = Function('f')
>>> x = Symbol('x')
>>> d = DifferentialOperator(1/x*Derivative(f(x), x), f(x))
>>> w = Wavefunction(x**2, x)
>>> d.function
f(x)
>>> d.variables
(x,)
>>> qapply(d*w)
Wavefunction(2, x)

expr
Returns the arbitrary expression which is to have the Wavefunction substituted into
it

Examples

>>> from sympy.physics.quantum.operator import DifferentialOperator

>>> from sympy import Function, Symbol, Derivative
>>> x = Symbol('x')
>>> f = Function('f')
>>> d = DifferentialOperator(Derivative(f(x), x), f(x))
>>> d.expr
Derivative(f(x), x)
>>> y = Symbol('y')
>>> d = DifferentialOperator(Derivative(f(x, y), x) +
(continues on next page)

5.40. Physics Module 1723

SymPy Documentation, Release 1.3

(continued from previous page)

... Derivative(f(x, y), y), f(x, y))
>>> d.expr
Derivative(f(x, y), x) + Derivative(f(x, y), y)

free_symbols
Return the free symbols of the expression.
function
Returns the function which is to be replaced with the Wavefunction

Examples

>>> from sympy.physics.quantum.operator import DifferentialOperator

>>> from sympy import Function, Symbol, Derivative
>>> x = Symbol('x')
>>> f = Function('f')
>>> d = DifferentialOperator(Derivative(f(x), x), f(x))
>>> d.function
f(x)
>>> y = Symbol('y')
>>> d = DifferentialOperator(Derivative(f(x, y), x) +
... Derivative(f(x, y), y), f(x, y))
>>> d.function
f(x, y)

variables
Returns the variables with which the function in the specified arbitrary expression
is evaluated

Examples

>>> from sympy.physics.quantum.operator import DifferentialOperator

>>> from sympy import Symbol, Function, Derivative
>>> x = Symbol('x')
>>> f = Function('f')
>>> d = DifferentialOperator(1/x*Derivative(f(x), x), f(x))
>>> d.variables
(x,)
>>> y = Symbol('y')
>>> d = DifferentialOperator(Derivative(f(x, y), x) +
... Derivative(f(x, y), y), f(x, y))
>>> d.variables
(x, y)

Operator/State Helper Functions

A module for mapping operators to their corresponding eigenstates and vice versa
It contains a global dictionary with eigenstate-operator pairings. If a new state-operator pair
is created, this dictionary should be updated as well.

1724 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

It also contains functions operators_to_state and state_to_operators for mapping between the
two. These can handle both classes and instances of operators and states. See the individual
function descriptions for details.
TODO List: - Update the dictionary with a complete list of state-operator pairs
sympy.physics.quantum.operatorset.operators_to_state(operators, **options)
Returns the eigenstate of the given operator or set of operators
A global function for mapping operator classes to their associated states. It takes either
an Operator or a set of operators and returns the state associated with these.
This function can handle both instances of a given operator or just the class itself (i.e.
both XOp() and XOp)
There are multiple use cases to consider:
1) A class or set of classes is passed: First, we try to instantiate default instances for
these operators. If this fails, then the class is simply returned. If we succeed in instan-
tiating default instances, then we try to call state._operators_to_state on the operator
instances. If this fails, the class is returned. Otherwise, the instance returned by _oper-
ators_to_state is returned.
2) An instance or set of instances is passed: In this case, state._operators_to_state is
called on the instances passed. If this fails, a state class is returned. If the method
returns an instance, that instance is returned.
In both cases, if the operator class or set does not exist in the state_mapping dictionary,
None is returned.
Parameters arg: Operator or set
The class or instance of the operator or set of operators to be mapped
to a state

Examples

>>> from sympy.physics.quantum.cartesian import XOp, PxOp

>>> from sympy.physics.quantum.operatorset import operators_to_state
>>> from sympy.physics.quantum.operator import Operator
>>> operators_to_state(XOp)
|x>
>>> operators_to_state(XOp())
|x>
>>> operators_to_state(PxOp)
|px>
>>> operators_to_state(PxOp())
|px>
>>> operators_to_state(Operator)
|psi>
>>> operators_to_state(Operator())
|psi>

sympy.physics.quantum.operatorset.state_to_operators(state, **options)
Returns the operator or set of operators corresponding to the given eigenstate
A global function for mapping state classes to their associated operators or sets of oper-
ators. It takes either a state class or instance.

5.40. Physics Module 1725

SymPy Documentation, Release 1.3

This function can handle both instances of a given state or just the class itself (i.e. both
XKet() and XKet)
There are multiple use cases to consider:
1) A state class is passed: In this case, we first try instantiating a default instance of
the class. If this succeeds, then we try to call state._state_to_operators on that instance.
If the creation of the default instance or if the calling of _state_to_operators fails, then
either an operator class or set of operator classes is returned. Otherwise, the appropriate
operator instances are returned.
2) A state instance is returned: Here, state._state_to_operators is called for the instance.
If this fails, then a class or set of operator classes is returned. Otherwise, the instances
are returned.
In either case, if the state’s class does not exist in state_mapping, None is returned.
Parameters arg: StateBase class or instance (or subclasses)
The class or instance of the state to be mapped to an operator or set
of operators

Examples

>>> from sympy.physics.quantum.cartesian import XKet, PxKet, XBra, PxBra

>>> from sympy.physics.quantum.operatorset import state_to_operators
>>> from sympy.physics.quantum.state import Ket, Bra
>>> state_to_operators(XKet)
X
>>> state_to_operators(XKet())
X
>>> state_to_operators(PxKet)
Px
>>> state_to_operators(PxKet())
Px
>>> state_to_operators(PxBra)
Px
>>> state_to_operators(XBra)
X
>>> state_to_operators(Ket)
O
>>> state_to_operators(Bra)
O

Qapply

Logic for applying operators to states.

Todo: * Sometimes the final result needs to be expanded, we should do this by hand.
sympy.physics.quantum.qapply.qapply(e, **options)
Apply operators to states in a quantum expression.
Parameters e : Expr
The expression containing operators and states. This expression tree
will be walked to find operators acting on states symbolically.

1726 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

options : dict
A dict of key/value pairs that determine how the operator actions are
carried out.
The following options are valid:
• dagger: try to apply Dagger operators to the left (default: False).
• ip_doit: call .doit() in inner products when they are encountered
(default: True).
Returns e : Expr
The original expression, but with the operators applied to states.

Examples

>>> from sympy.physics.quantum import qapply, Ket, Bra

>>> b = Bra('b')
>>> k = Ket('k')
>>> A = k * b
>>> A
|k><b|
>>> qapply(A * b.dual / (b * b.dual))
|k>
>>> qapply(k.dual * A / (k.dual * k), dagger=True)
<b|
>>> qapply(k.dual * A / (k.dual * k))
<k|*|k><b|/<k|k>

Represent

Logic for representing operators in state in various bases.

TODO:
• Get represent working with continuous hilbert spaces.
• Document default basis functionality.
sympy.physics.quantum.represent.represent(expr, **options)
Represent the quantum expression in the given basis.
In quantum mechanics abstract states and operators can be represented in various basis
sets. Under this operation the follow transforms happen:
• Ket -> column vector or function
• Bra -> row vector of function
• Operator -> matrix or differential operator
This function is the top-level interface for this action.
This function walks the sympy expression tree looking for QExpr instances that have a
_represent method. This method is then called and the object is replaced by the rep-
resentation returned by this method. By default, the _represent method will dispatch
to other methods that handle the representation logic for a particular basis set. The
naming convention for these methods is the following:

5.40. Physics Module 1727

SymPy Documentation, Release 1.3

def _represent_FooBasis(self, e, basis, **options)

This function will have the logic for representing instances of its class in the basis set
having a class named FooBasis.
Parameters expr : Expr
The expression to represent.
basis : Operator, basis set
An object that contains the information about the basis set. If an oper-
ator is used, the basis is assumed to be the orthonormal eigenvectors
of that operator. In general though, the basis argument can be any
object that contains the basis set information.
options : dict
Key/value pairs of options that are passed to the underlying method
that finds the representation. These options can be used to control
how the representation is done. For example, this is where the size
of the basis set would be set.
Returns e : Expr
The SymPy expression of the represented quantum expression.

Examples

Here we subclass Operator and Ket to create the z-spin operator and its spin 1/2 up
eigenstate. By defining the _represent_SzOp method, the ket can be represented in the
z-spin basis.

>>> from sympy.physics.quantum import Operator, represent, Ket

>>> from sympy import Matrix

>>> class SzUpKet(Ket):

... def _represent_SzOp(self, basis, **options):
... return Matrix([1,0])
...
>>> class SzOp(Operator):
... pass
...
>>> sz = SzOp('Sz')
>>> up = SzUpKet('up')
>>> represent(up, basis=sz)
Matrix([
[1],
[0]])

Here we see an example of representations in a continuous basis. We see that the result
of representing various combinations of cartesian position operators and kets give us
continuous expressions involving DiracDelta functions.

>>> from sympy.physics.quantum.cartesian import XOp, XKet, XBra

>>> X = XOp()
>>> x = XKet()
(continues on next page)

1728 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> y = XBra('y')
>>> represent(X*x)
x*DiracDelta(x - x_2)
>>> represent(X*x*y)
x*DiracDelta(x - x_3)*DiracDelta(x_1 - y)

sympy.physics.quantum.represent.rep_innerproduct(expr, **options)
Returns an innerproduct like representation (e.g. <x'|x>) for the given state.
Attempts to calculate inner product with a bra from the specified basis. Should only be
passed an instance of KetBase or BraBase
Parameters expr : KetBase or BraBase
The expression to be represented

Examples

>>> from sympy.physics.quantum.represent import rep_innerproduct

>>> from sympy.physics.quantum.cartesian import XOp, XKet, PxOp, PxKet
>>> rep_innerproduct(XKet())
DiracDelta(x - x_1)
>>> rep_innerproduct(XKet(), basis=PxOp())
sqrt(2)*exp(-I*px_1*x/hbar)/(2*sqrt(hbar)*sqrt(pi))
>>> rep_innerproduct(PxKet(), basis=XOp())
sqrt(2)*exp(I*px*x_1/hbar)/(2*sqrt(hbar)*sqrt(pi))

sympy.physics.quantum.represent.rep_expectation(expr, **options)
Returns an <x'|A|x> type representation for the given operator.
Parameters expr : Operator
Operator to be represented in the specified basis

Examples

>>> from sympy.physics.quantum.cartesian import XOp, XKet, PxOp, PxKet

>>> from sympy.physics.quantum.represent import rep_expectation
>>> rep_expectation(XOp())
x_1*DiracDelta(x_1 - x_2)
>>> rep_expectation(XOp(), basis=PxOp())
<px_2|*X*|px_1>
>>> rep_expectation(XOp(), basis=PxKet())
<px_2|*X*|px_1>

sympy.physics.quantum.represent.integrate_result(orig_expr, result, **options)

Returns the result of integrating over any unities (|x><x|) in the given expression. In-
tended for integrating over the result of representations in continuous bases.
This function integrates over any unities that may have been inserted into the quantum
expression and returns the result. It uses the interval of the Hilbert space of the basis
state passed to it in order to figure out the limits of integration. The unities option must
be specified for this to work.

5.40. Physics Module 1729

SymPy Documentation, Release 1.3

Note: This is mostly used internally by represent(). Examples are given merely to show
the use cases.
Parameters orig_expr : quantum expression
The original expression which was to be represented
result: Expr
The resulting representation that we wish to integrate over

Examples

>>> from sympy import symbols, DiracDelta

>>> from sympy.physics.quantum.represent import integrate_result
>>> from sympy.physics.quantum.cartesian import XOp, XKet
>>> x_ket = XKet()
>>> X_op = XOp()
>>> x, x_1, x_2 = symbols('x, x_1, x_2')
>>> integrate_result(X_op*x_ket, x*DiracDelta(x-x_1)*DiracDelta(x_1-x_2))
x*DiracDelta(x - x_1)*DiracDelta(x_1 - x_2)
>>> integrate_result(X_op*x_ket, x*DiracDelta(x-x_1)*DiracDelta(x_1-x_2),
... unities=[1])
x*DiracDelta(x - x_2)

sympy.physics.quantum.represent.get_basis(expr, **options)
Returns a basis state instance corresponding to the basis specified in options=s. If no
basis is specified, the function tries to form a default basis state of the given expression.
There are three behaviors:
1. The basis specified in options is already an instance of StateBase. If this is the case,
it is simply returned. If the class is specified but not an instance, a default instance
is returned.
2. The basis specified is an operator or set of operators. If this is the case, the opera-
tor_to_state mapping method is used.
3. No basis is specified. If expr is a state, then a default instance of its class is returned.
If expr is an operator, then it is mapped to the corresponding state. If it is neither,
then we cannot obtain the basis state.
If the basis cannot be mapped, then it is not changed.
This will be called from within represent, and represent will only pass QExpr’s.
TODO (?): Support for Muls and other types of expressions?
Parameters expr : Operator or StateBase
Expression whose basis is sought

Examples

>>> from sympy.physics.quantum.represent import get_basis

>>> from sympy.physics.quantum.cartesian import XOp, XKet, PxOp, PxKet
>>> x = XKet()
>>> X = XOp()
(continues on next page)

1730 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> get_basis(x)
|x>
>>> get_basis(X)
|x>
>>> get_basis(x, basis=PxOp())
|px>
>>> get_basis(x, basis=PxKet)
|px>

sympy.physics.quantum.represent.enumerate_states(*args, **options)
Returns instances of the given state with dummy indices appended
Operates in two different modes:
1. Two arguments are passed to it. The first is the base state which is to be indexed,
and the second argument is a list of indices to append.
2. Three arguments are passed. The first is again the base state to be indexed. The
second is the start index for counting. The final argument is the number of kets you
wish to receive.
Tries to call state._enumerate_state. If this fails, returns an empty list
Parameters args : list
See list of operation modes above for explanation

Examples

>>> from sympy.physics.quantum.cartesian import XBra, XKet

>>> from sympy.physics.quantum.represent import enumerate_states
>>> test = XKet('foo')
>>> enumerate_states(test, 1, 3)
[|foo_1>, |foo_2>, |foo_3>]
>>> test2 = XBra('bar')
>>> enumerate_states(test2, [4, 5, 10])
[<bar_4|, <bar_5|, <bar_10|]

Spin

Quantum mechanical angular momemtum.

class sympy.physics.quantum.spin.Rotation
Wigner D operator in terms of Euler angles.
Defines the rotation operator in terms of the Euler angles defined by the z-y-z convention
for a passive transformation. That is the coordinate axes are rotated first about the z-
axis, giving the new x’-y’-z’ axes. Then this new coordinate system is rotated about the
new y’-axis, giving new x’‘-y’‘-z’’ axes. Then this new coordinate system is rotated about
the z’‘-axis. Conventions follow those laid out in [R483].
Parameters alpha : Number, Symbol
First Euler Angle
beta : Number, Symbol

5.40. Physics Module 1731

SymPy Documentation, Release 1.3

Second Euler angle

gamma : Number, Symbol
Third Euler angle
See also:

WignerD (page 1733) Symbolic Wigner-D function

D (page 1732) Wigner-D function
d (page 1733) Wigner small-d function

References

[R483]

Examples

A simple example rotation operator:

>>> from sympy import pi

>>> from sympy.physics.quantum.spin import Rotation
>>> Rotation(pi, 0, pi/2)
R(pi,0,pi/2)

With symbolic Euler angles and calculating the inverse rotation operator:

>>> from sympy import symbols

>>> a, b, c = symbols('a b c')
>>> Rotation(a, b, c)
R(a,b,c)
>>> Rotation(a, b, c).inverse()
R(-c,-b,-a)

classmethod D(j, m, mp, alpha, beta, gamma)

Wigner D-function.
Returns an instance of the WignerD class corresponding to the Wigner-D function
specified by the parameters.
Parameters j : Number
Total angular momentum
m : Number
Eigenvalue of angular momentum along axis after rotation
mp : Number
Eigenvalue of angular momentum along rotated axis
alpha : Number, Symbol
First Euler angle of rotation
beta : Number, Symbol
Second Euler angle of rotation

1732 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

gamma : Number, Symbol

Third Euler angle of rotation
See also:

WignerD (page 1733) Symbolic Wigner-D function

Examples

Return the Wigner-D matrix element for a defined rotation, both numerical and sym-
bolic:

>>> from sympy.physics.quantum.spin import Rotation

>>> from sympy import pi, symbols
>>> alpha, beta, gamma = symbols('alpha beta gamma')
>>> Rotation.D(1, 1, 0,pi, pi/2,-pi)
WignerD(1, 1, 0, pi, pi/2, -pi)

classmethod d(j, m, mp, beta)

Wigner small-d function.
Returns an instance of the WignerD class corresponding to the Wigner-D function
specified by the parameters with the alpha and gamma angles given as 0.
Parameters j : Number
Total angular momentum
m : Number
Eigenvalue of angular momentum along axis after rotation
mp : Number
Eigenvalue of angular momentum along rotated axis
beta : Number, Symbol
Second Euler angle of rotation
See also:

WignerD (page 1733) Symbolic Wigner-D function

Examples

Return the Wigner-D matrix element for a defined rotation, both numerical and sym-
bolic:

>>> from sympy.physics.quantum.spin import Rotation

>>> from sympy import pi, symbols
>>> beta = symbols('beta')
>>> Rotation.d(1, 1, 0, pi/2)
WignerD(1, 1, 0, 0, pi/2, 0)

class sympy.physics.quantum.spin.WignerD
Wigner-D function

5.40. Physics Module 1733

SymPy Documentation, Release 1.3

The Wigner D-function gives the matrix elements of the rotation operator in the jm-
representation. For the Euler angles α, β, γ, the D-function is defined such that:

< j, m|R(α, β, γ)|j ′ , m′ >= δjj ′ D(j, m, m′ , α, β, γ)

Where the rotation operator is as defined by the Rotation class [R484].

The Wigner D-function defined in this way gives:
′
D(j, m, m′ , α, β, γ) = e−imα d(j, m, m′ , β)e−im γ

Where d is the Wigner small-d function, which is given by Rotation.d.

The Wigner small-d function gives the component of the Wigner D-function that is deter-
mined by the second Euler angle. That is the Wigner D-function is:
′
D(j, m, m′ , α, β, γ) = e−imα d(j, m, m′ , β)e−im γ

Where d is the small-d function. The Wigner D-function is given by Rotation.D.

Note that to evaluate the D-function, the j, m and mp parameters must be integer or half
integer numbers.
Parameters j : Number
Total angular momentum
m : Number
Eigenvalue of angular momentum along axis after rotation
mp : Number
Eigenvalue of angular momentum along rotated axis
alpha : Number, Symbol
First Euler angle of rotation
beta : Number, Symbol
Second Euler angle of rotation
gamma : Number, Symbol
Third Euler angle of rotation
See also:

Rotation (page 1731) Rotation operator

References

[R484]

Examples

Evaluate the Wigner-D matrix elements of a simple rotation:

1734 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.quantum.spin import Rotation

>>> from sympy import pi
>>> rot = Rotation.D(1, 1, 0, pi, pi/2, 0)
>>> rot
WignerD(1, 1, 0, pi, pi/2, 0)
>>> rot.doit()
sqrt(2)/2

Evaluate the Wigner-d matrix elements of a simple rotation

>>> rot = Rotation.d(1, 1, 0, pi/2)
>>> rot
WignerD(1, 1, 0, 0, pi/2, 0)
>>> rot.doit()
-sqrt(2)/2

class sympy.physics.quantum.spin.JxKet
Eigenket of Jx.
See JzKet for the usage of spin eigenstates.
See also:

JzKet (page 1735) Usage of spin states

class sympy.physics.quantum.spin.JxBra
Eigenbra of Jx.
See JzKet for the usage of spin eigenstates.
See also:

JzKet (page 1735) Usage of spin states

class sympy.physics.quantum.spin.JyKet
Eigenket of Jy.
See JzKet for the usage of spin eigenstates.
See also:

JzKet (page 1735) Usage of spin states

class sympy.physics.quantum.spin.JyBra
Eigenbra of Jy.
See JzKet for the usage of spin eigenstates.
See also:

JzKet (page 1735) Usage of spin states

class sympy.physics.quantum.spin.JzKet
Eigenket of Jz.
Spin state which is an eigenstate of the Jz operator. Uncoupled states, that is states
representing the interaction of multiple separate spin states, are defined as a tensor
product of states.
Parameters j : Number, Symbol

5.40. Physics Module 1735

SymPy Documentation, Release 1.3

Total spin angular momentum

m : Number, Symbol
Eigenvalue of the Jz spin operator
See also:

JzKetCoupled (page 1738) Coupled eigenstates

TensorProduct Used to specify uncoupled states
uncouple (page 1741) Uncouples states given coupling parameters
couple (page 1740) Couples uncoupled states

Examples

Normal States:
Defining simple spin states, both numerical and symbolic:

>>> from sympy.physics.quantum.spin import JzKet, JxKet

>>> from sympy import symbols
>>> JzKet(1, 0)
|1,0>
>>> j, m = symbols('j m')
>>> JzKet(j, m)
|j,m>

Rewriting the JzKet in terms of eigenkets of the Jx operator: Note: that the resulting
eigenstates are JxKet’s

>>> JzKet(1,1).rewrite(”Jx”)
|1,-1>/2 - sqrt(2)*|1,0>/2 + |1,1>/2

Get the vector representation of a state in terms of the basis elements of the Jx operator:

>>> from sympy.physics.quantum.represent import represent

>>> from sympy.physics.quantum.spin import Jx, Jz
>>> represent(JzKet(1,-1), basis=Jx)
Matrix([
[ 1/2],
[sqrt(2)/2],
[ 1/2]])

Apply innerproducts between states:

>>> from sympy.physics.quantum.innerproduct import InnerProduct

>>> from sympy.physics.quantum.spin import JxBra
>>> i = InnerProduct(JxBra(1,1), JzKet(1,1))
>>> i
<1,1|1,1>
>>> i.doit()
1/2

Uncoupled States:
Define an uncoupled state as a TensorProduct between two Jz eigenkets:

1736 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.quantum.tensorproduct import TensorProduct

>>> j1,m1,j2,m2 = symbols('j1 m1 j2 m2')
>>> TensorProduct(JzKet(1,0), JzKet(1,1))
|1,0>x|1,1>
>>> TensorProduct(JzKet(j1,m1), JzKet(j2,m2))
|j1,m1>x|j2,m2>

A TensorProduct can be rewritten, in which case the eigenstates that make up the tensor
product is rewritten to the new basis:

>>> TensorProduct(JzKet(1,1),JxKet(1,1)).rewrite('Jz')
|1,1>x|1,-1>/2 + sqrt(2)*|1,1>x|1,0>/2 + |1,1>x|1,1>/2

The represent method for TensorProduct’s gives the vector representation of the state.
Note that the state in the product basis is the equivalent of the tensor product of the
vector representation of the component eigenstates:

>>> represent(TensorProduct(JzKet(1,0),JzKet(1,1)))
Matrix([
[0],
[0],
[0],
[1],
[0],
[0],
[0],
[0],
[0]])
>>> represent(TensorProduct(JzKet(1,1),JxKet(1,1)), basis=Jz)
Matrix([
[ 1/2],
[sqrt(2)/2],
[ 1/2],
[ 0],
[ 0],
[ 0],
[ 0],
[ 0],
[ 0]])

class sympy.physics.quantum.spin.JzBra
Eigenbra of Jz.
See the JzKet for the usage of spin eigenstates.
See also:

JzKet (page 1735) Usage of spin states

class sympy.physics.quantum.spin.JxKetCoupled
Coupled eigenket of Jx.
See JzKetCoupled for the usage of coupled spin eigenstates.
See also:

JzKetCoupled (page 1738) Usage of coupled spin states

5.40. Physics Module 1737

SymPy Documentation, Release 1.3

class sympy.physics.quantum.spin.JxBraCoupled
Coupled eigenbra of Jx.
See JzKetCoupled for the usage of coupled spin eigenstates.
See also:

JzKetCoupled (page 1738) Usage of coupled spin states

class sympy.physics.quantum.spin.JyKetCoupled
Coupled eigenket of Jy.
See JzKetCoupled for the usage of coupled spin eigenstates.
See also:

JzKetCoupled (page 1738) Usage of coupled spin states

class sympy.physics.quantum.spin.JyBraCoupled
Coupled eigenbra of Jy.
See JzKetCoupled for the usage of coupled spin eigenstates.
See also:

JzKetCoupled (page 1738) Usage of coupled spin states

class sympy.physics.quantum.spin.JzKetCoupled
Coupled eigenket of Jz
Spin state that is an eigenket of Jz which represents the coupling of separate spin spaces.
The arguments for creating instances of JzKetCoupled are j, m, jn and an optional jcou-
pling argument. The j and m options are the total angular momentum quantum num-
bers, as used for normal states (e.g. JzKet).
The other required parameter in jn, which is a tuple defining the jn angular momentum
quantum numbers of the product spaces. So for example, if a state represented the
coupling of the product basis state |j1 , m1 ⟩ × |j2 , m2 ⟩, the jn for this state would be (j1,
j2).
The final option is jcoupling, which is used to define how the spaces specified by jn
are coupled, which includes both the order these spaces are coupled together and the
quantum numbers that arise from these couplings. The jcoupling parameter itself is
a list of lists, such that each of the sublists defines a single coupling between the spin
spaces. If there are N coupled angular momentum spaces, that is jn has N elements, then
there must be N-1 sublists. Each of these sublists making up the jcoupling parameter
have length 3. The first two elements are the indices of the product spaces that are
considered to be coupled together. For example, if we want to couple j1 and j4 , the
indices would be 1 and 4. If a state has already been coupled, it is referenced by the
smallest index that is coupled, so if j2 and j4 has already been coupled to some j24 , then
this value can be coupled by referencing it with index 2. The final element of the sublist
is the quantum number of the coupled state. So putting everything together, into a
valid sublist for jcoupling, if j1 and j2 are coupled to an angular momentum space with
quantum number j12 with the value j12, the sublist would be (1,2,j12), N-1 of these
sublists are used in the list for jcoupling.
Note the jcoupling parameter is optional, if it is not specified, the default coupling is
taken. This default value is to coupled the spaces in order and take the quantum number

1738 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

of the coupling to be the maximum value. For example, if the spin spaces are j1 , j2 , j3 ,
j4 , then the default coupling couples j1 and j2 to j12 = j1 + j2 , then, j12 and j3 are coupled
to j123 = j12 + j3 , and finally j123 and j4 to j = j123 + j4 . The jcoupling value that would
correspond to this is:
((1,2,j1+j2),(1,3,j1+j2+j3))

Parameters args : tuple

The arguments that must be passed are j, m, jn, and jcoupling. The j
value is the total angular momentum. The m value is the eigenvalue of
the Jz spin operator. The jn list are the j values of argular momentum
spaces coupled together. The jcoupling parameter is an optional
parameter defining how the spaces are coupled together. See the
above description for how these coupling parameters are defined.

See also:

JzKet (page 1735) Normal spin eigenstates

uncouple (page 1741) Uncoupling of coupling spin states
couple (page 1740) Coupling of uncoupled spin states

Examples

Defining simple spin states, both numerical and symbolic:

>>> from sympy.physics.quantum.spin import JzKetCoupled

>>> from sympy import symbols
>>> JzKetCoupled(1, 0, (1, 1))
|1,0,j1=1,j2=1>
>>> j, m, j1, j2 = symbols('j m j1 j2')
>>> JzKetCoupled(j, m, (j1, j2))
|j,m,j1=j1,j2=j2>

Defining coupled spin states for more than 2 coupled spaces with various coupling pa-
rameters:

>>> JzKetCoupled(2, 1, (1, 1, 1))

|2,1,j1=1,j2=1,j3=1,j(1,2)=2>
>>> JzKetCoupled(2, 1, (1, 1, 1), ((1,2,2),(1,3,2)) )
|2,1,j1=1,j2=1,j3=1,j(1,2)=2>
>>> JzKetCoupled(2, 1, (1, 1, 1), ((2,3,1),(1,2,2)) )
|2,1,j1=1,j2=1,j3=1,j(2,3)=1>

Rewriting the JzKetCoupled in terms of eigenkets of the Jx operator: Note: that the
resulting eigenstates are JxKetCoupled

>>> JzKetCoupled(1,1,(1,1)).rewrite(”Jx”)
|1,-1,j1=1,j2=1>/2 - sqrt(2)*|1,0,j1=1,j2=1>/2 + |1,1,j1=1,j2=1>/2

The rewrite method can be used to convert a coupled state to an uncoupled state. This
is done by passing coupled=False to the rewrite function:

>>> JzKetCoupled(1, 0, (1, 1)).rewrite('Jz', coupled=False)

-sqrt(2)*|1,-1>x|1,1>/2 + sqrt(2)*|1,1>x|1,-1>/2

5.40. Physics Module 1739

SymPy Documentation, Release 1.3

Get the vector representation of a state in terms of the basis elements of the Jx operator:

>>> from sympy.physics.quantum.represent import represent

>>> from sympy.physics.quantum.spin import Jx
>>> from sympy import S
>>> represent(JzKetCoupled(1,-1,(S(1)/2,S(1)/2)), basis=Jx)
Matrix([
[ 0],
[ 1/2],
[sqrt(2)/2],
[ 1/2]])

class sympy.physics.quantum.spin.JzBraCoupled
Coupled eigenbra of Jz.
See the JzKetCoupled for the usage of coupled spin eigenstates.
See also:

JzKetCoupled (page 1738) Usage of coupled spin states

sympy.physics.quantum.spin.couple(expr, jcoupling_list=None)
Couple a tensor product of spin states
This function can be used to couple an uncoupled tensor product of spin states. All of the
eigenstates to be coupled must be of the same class. It will return a linear combination
of eigenstates that are subclasses of CoupledSpinState determined by Clebsch-Gordan
angular momentum coupling coefficients.
Parameters expr : Expr
An expression involving TensorProducts of spin states to be coupled.
Each state must be a subclass of SpinState and they all must be the
same class.
jcoupling_list : list or tuple
Elements of this list are sub-lists of length 2 specifying the order of
the coupling of the spin spaces. The length of this must be N-1, where
N is the number of states in the tensor product to be coupled. The
elements of this sublist are the same as the first two elements of each
sublist in the jcoupling parameter defined for JzKetCoupled. If this
parameter is not specified, the default value is taken, which couples
the first and second product basis spaces, then couples this new cou-
pled space to the third product space, etc

Examples

Couple a tensor product of numerical states for two spaces:

>>> from sympy.physics.quantum.spin import JzKet, couple

>>> from sympy.physics.quantum.tensorproduct import TensorProduct
>>> couple(TensorProduct(JzKet(1,0), JzKet(1,1)))
-sqrt(2)*|1,1,j1=1,j2=1>/2 + sqrt(2)*|2,1,j1=1,j2=1>/2

Numerical coupling of three spaces using the default coupling method, i.e. first and
second spaces couple, then this couples to the third space:

1740 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> couple(TensorProduct(JzKet(1,1), JzKet(1,1), JzKet(1,0)))

sqrt(6)*|2,2,j1=1,j2=1,j3=1,j(1,2)=2>/3 + sqrt(3)*|3,2,j1=1,j2=1,j3=1,j(1,2)=2>/3

Perform this same coupling, but we define the coupling to first couple the first and third
spaces:

>>> couple(TensorProduct(JzKet(1,1), JzKet(1,1), JzKet(1,0)), ((1,3),(1,2)) )

sqrt(2)*|2,2,j1=1,j2=1,j3=1,j(1,3)=1>/2 - sqrt(6)*|2,2,j1=1,j2=1,j3=1,j(1,3)=2>/6␣
,→+ sqrt(3)*|3,2,j1=1,j2=1,j3=1,j(1,3)=2>/3

Couple a tensor product of symbolic states:

>>> from sympy import symbols

>>> j1,m1,j2,m2 = symbols('j1 m1 j2 m2')
>>> couple(TensorProduct(JzKet(j1,m1), JzKet(j2,m2)))
Sum(CG(j1, m1, j2, m2, j, m1 + m2)*|j,m1 + m2,j1=j1,j2=j2>, (j, m1 + m2, j1 + j2))

sympy.physics.quantum.spin.uncouple(expr, jn=None, jcoupling_list=None)

Uncouple a coupled spin state
Gives the uncoupled representation of a coupled spin state. Arguments must be either
a spin state that is a subclass of CoupledSpinState or a spin state that is a subclass of
SpinState and an array giving the j values of the spaces that are to be coupled
Parameters expr : Expr
The expression containing states that are to be coupled. If the states
are a subclass of SpinState, the jn and jcoupling parameters must
be defined. If the states are a subclass of CoupledSpinState, jn and
jcoupling will be taken from the state.
jn : list or tuple
The list of the j-values that are coupled. If state is a CoupledSpin-
State, this parameter is ignored. This must be defined if state is not
a subclass of CoupledSpinState. The syntax of this parameter is the
same as the jn parameter of JzKetCoupled.
jcoupling_list : list or tuple
The list defining how the j-values are coupled together. If state is a
CoupledSpinState, this parameter is ignored. This must be defined
if state is not a subclass of CoupledSpinState. The syntax of this pa-
rameter is the same as the jcoupling parameter of JzKetCoupled.

Examples

Uncouple a numerical state using a CoupledSpinState state:

>>> from sympy.physics.quantum.spin import JzKetCoupled, uncouple

>>> from sympy import S
>>> uncouple(JzKetCoupled(1, 0, (S(1)/2, S(1)/2)))
sqrt(2)*|1/2,-1/2>x|1/2,1/2>/2 + sqrt(2)*|1/2,1/2>x|1/2,-1/2>/2

Perform the same calculation using a SpinState state:

5.40. Physics Module 1741

SymPy Documentation, Release 1.3

>>> from sympy.physics.quantum.spin import JzKet

>>> uncouple(JzKet(1, 0), (S(1)/2, S(1)/2))
sqrt(2)*|1/2,-1/2>x|1/2,1/2>/2 + sqrt(2)*|1/2,1/2>x|1/2,-1/2>/2

Uncouple a numerical state of three coupled spaces using a CoupledSpinState state:

>>> uncouple(JzKetCoupled(1, 1, (1, 1, 1), ((1,3,1),(1,2,1)) ))

|1,-1>x|1,1>x|1,1>/2 - |1,0>x|1,0>x|1,1>/2 + |1,1>x|1,0>x|1,0>/2 - |1,1>x|1,1>x|1,
,→-1>/2

Perform the same calculation using a SpinState state:

>>> uncouple(JzKet(1, 1), (1, 1, 1), ((1,3,1),(1,2,1)) )

|1,-1>x|1,1>x|1,1>/2 - |1,0>x|1,0>x|1,1>/2 + |1,1>x|1,0>x|1,0>/2 - |1,1>x|1,1>x|1,
,→-1>/2

Uncouple a symbolic state using a CoupledSpinState state:

>>> from sympy import symbols

>>> j,m,j1,j2 = symbols('j m j1 j2')
>>> uncouple(JzKetCoupled(j, m, (j1, j2)))
Sum(CG(j1, m1, j2, m2, j, m)*|j1,m1>x|j2,m2>, (m1, -j1, j1), (m2, -j2, j2))

Perform the same calculation using a SpinState state

>>> uncouple(JzKet(j, m), (j1, j2))

Sum(CG(j1, m1, j2, m2, j, m)*|j1,m1>x|j2,m2>, (m1, -j1, j1), (m2, -j2, j2))

State

Dirac notation for states.

class sympy.physics.quantum.state.KetBase
Base class for Kets.
This class defines the dual property and the brackets for printing. This is an abstract
base class and you should not instantiate it directly, instead use Ket.
class sympy.physics.quantum.state.BraBase
Base class for Bras.
This class defines the dual property and the brackets for printing. This is an abstract
base class and you should not instantiate it directly, instead use Bra.
class sympy.physics.quantum.state.StateBase
Abstract base class for general abstract states in quantum mechanics.
All other state classes defined will need to inherit from this class. It carries the basic
structure for all other states such as dual, _eval_adjoint and label.
This is an abstract base class and you should not instantiate it directly, instead use State.

dual
Return the dual state of this one.
classmethod dual_class()
Return the class used to construct the dual.

1742 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

operators
Return the operator(s) that this state is an eigenstate of
class sympy.physics.quantum.state.State
General abstract quantum state used as a base class for Ket and Bra.
class sympy.physics.quantum.state.Ket
A general time-independent Ket in quantum mechanics.
Inherits from State and KetBase. This class should be used as the base class for all
physical, time-independent Kets in a system. This class and its subclasses will be the
main classes that users will use for expressing Kets in Dirac notation [R485].
Parameters args : tuple
The list of numbers or parameters that uniquely specify the ket.
This will usually be its symbol or its quantum numbers. For time-
dependent state, this will include the time.

References

[R485]

Examples

Create a simple Ket and looking at its properties:

>>> from sympy.physics.quantum import Ket, Bra

>>> from sympy import symbols, I
>>> k = Ket('psi')
>>> k
|psi>
>>> k.hilbert_space
H
>>> k.is_commutative
False
>>> k.label
(psi,)

Ket’s know about their associated bra:

>>> k.dual
<psi|
>>> k.dual_class()
<class 'sympy.physics.quantum.state.Bra'>

Take a linear combination of two kets:

>>> k0 = Ket(0)
>>> k1 = Ket(1)
>>> 2*I*k0 - 4*k1
2*I*|0> - 4*|1>

Compound labels are passed as tuples:

5.40. Physics Module 1743

SymPy Documentation, Release 1.3

>>> n, m = symbols('n,m')
>>> k = Ket(n,m)
>>> k
|nm>

class sympy.physics.quantum.state.Bra
A general time-independent Bra in quantum mechanics.
Inherits from State and BraBase. A Bra is the dual of a Ket [R486]. This class and
its subclasses will be the main classes that users will use for expressing Bras in Dirac
notation.
Parameters args : tuple
The list of numbers or parameters that uniquely specify the ket.
This will usually be its symbol or its quantum numbers. For time-
dependent state, this will include the time.

References

[R486]

Examples

Create a simple Bra and look at its properties:

>>> from sympy.physics.quantum import Ket, Bra

>>> from sympy import symbols, I
>>> b = Bra('psi')
>>> b
<psi|
>>> b.hilbert_space
H
>>> b.is_commutative
False

Bra’s know about their dual Ket’s:

>>> b.dual
|psi>
>>> b.dual_class()
<class 'sympy.physics.quantum.state.Ket'>

Like Kets, Bras can have compound labels and be manipulated in a similar manner:

>>> n, m = symbols('n,m')
>>> b = Bra(n,m) - I*Bra(m,n)
>>> b
-I*<mn| + <nm|

Symbols in a Bra can be substituted using .subs:

>>> b.subs(n,m)
<mm| - I*<mm|

1744 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.quantum.state.TimeDepState
Base class for a general time-dependent quantum state.
This class is used as a base class for any time-dependent state. The main difference
between this class and the time-independent state is that this class takes a second argu-
ment that is the time in addition to the usual label argument.
Parameters args : tuple
The list of numbers or parameters that uniquely specify the ket.
This will usually be its symbol or its quantum numbers. For time-
dependent state, this will include the time as the final argument.
label
The label of the state.
time
The time of the state.
class sympy.physics.quantum.state.TimeDepBra
General time-dependent Bra in quantum mechanics.
This inherits from TimeDepState and BraBase and is the main class that should be used
for Bras that vary with time. Its dual is a TimeDepBra.
Parameters args : tuple
The list of numbers or parameters that uniquely specify the ket.
This will usually be its symbol or its quantum numbers. For time-
dependent state, this will include the time as the final argument.

Examples

>>> from sympy.physics.quantum import TimeDepBra

>>> from sympy import symbols, I
>>> b = TimeDepBra('psi', 't')
>>> b
<psi;t|
>>> b.time
t
>>> b.label
(psi,)
>>> b.hilbert_space
H
>>> b.dual
|psi;t>

class sympy.physics.quantum.state.TimeDepKet
General time-dependent Ket in quantum mechanics.
This inherits from TimeDepState and KetBase and is the main class that should be used
for Kets that vary with time. Its dual is a TimeDepBra.
Parameters args : tuple
The list of numbers or parameters that uniquely specify the ket.
This will usually be its symbol or its quantum numbers. For time-
dependent state, this will include the time as the final argument.

5.40. Physics Module 1745

SymPy Documentation, Release 1.3

Examples

Create a TimeDepKet and look at its attributes:

>>> from sympy.physics.quantum import TimeDepKet
>>> k = TimeDepKet('psi', 't')
>>> k
|psi;t>
>>> k.time
t
>>> k.label
(psi,)
>>> k.hilbert_space
H

TimeDepKets know about their dual bra:

>>> k.dual
<psi;t|
>>> k.dual_class()
<class 'sympy.physics.quantum.state.TimeDepBra'>

class sympy.physics.quantum.state.Wavefunction
Class for representations in continuous bases
This class takes an expression and coordinates in its constructor. It can be used to easily
calculate normalizations and probabilities.
Parameters expr : Expr
The expression representing the functional form of the w.f.
coords : Symbol or tuple
The coordinates to be integrated over, and their bounds

Examples

Particle in a box, specifying bounds in the more primitive way of using Piecewise:
>>> from sympy import Symbol, Piecewise, pi, N
>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x = Symbol('x', real=True)
>>> n = 1
>>> L = 1
>>> g = Piecewise((0, x < 0), (0, x > L), (sqrt(2//L)*sin(n*pi*x/L), True))
>>> f = Wavefunction(g, x)
>>> f.norm
1
>>> f.is_normalized
True
>>> p = f.prob()
>>> p(0)
0
>>> p(L)
0
>>> p(0.5)
(continues on next page)

1746 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

2
>>> p(0.85*L)
2*sin(0.85*pi)**2
>>> N(p(0.85*L))
0.412214747707527

Additionally, you can specify the bounds of the function and the indices in a more compact
way:
>>> from sympy import symbols, pi, diff
>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x, L = symbols('x,L', positive=True)
>>> n = symbols('n', integer=True, positive=True)
>>> g = sqrt(2/L)*sin(n*pi*x/L)
>>> f = Wavefunction(g, (x, 0, L))
>>> f.norm
1
>>> f(L+1)
0
>>> f(L-1)
sqrt(2)*sin(pi*n*(L - 1)/L)/sqrt(L)
>>> f(-1)
0
>>> f(0.85)
sqrt(2)*sin(0.85*pi*n/L)/sqrt(L)
>>> f(0.85, n=1, L=1)
sqrt(2)*sin(0.85*pi)
>>> f.is_commutative
False

All arguments are automatically sympified, so you can define the variables as strings
rather than symbols:
>>> expr = x**2
>>> f = Wavefunction(expr, 'x')
>>> type(f.variables[0])
<class 'sympy.core.symbol.Symbol'>

Derivatives of Wavefunctions will return Wavefunctions:

>>> diff(f, x)
Wavefunction(2*x, x)

expr
Return the expression which is the functional form of the Wavefunction

Examples

>>> from sympy.physics.quantum.state import Wavefunction

>>> from sympy import symbols
>>> x, y = symbols('x, y')
>>> f = Wavefunction(x**2, x)
>>> f.expr
x**2

5.40. Physics Module 1747

SymPy Documentation, Release 1.3

is_commutative
Override Function’s is_commutative so that order is preserved in represented ex-
pressions
is_normalized
Returns true if the Wavefunction is properly normalized

Examples

>>> from sympy import symbols, pi

>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x, L = symbols('x,L', positive=True)
>>> n = symbols('n', integer=True, positive=True)
>>> g = sqrt(2/L)*sin(n*pi*x/L)
>>> f = Wavefunction(g, (x, 0, L))
>>> f.is_normalized
True

limits
Return the limits of the coordinates which the w.f. depends on If no limits are spec-
ified, defaults to (-oo, oo).

Examples

>>> from sympy.physics.quantum.state import Wavefunction

>>> from sympy import symbols
>>> x, y = symbols('x, y')
>>> f = Wavefunction(x**2, (x, 0, 1))
>>> f.limits
{x: (0, 1)}
>>> f = Wavefunction(x**2, x)
>>> f.limits
{x: (-oo, oo)}
>>> f = Wavefunction(x**2 + y**2, x, (y, -1, 2))
>>> f.limits
{x: (-oo, oo), y: (-1, 2)}

norm
Return the normalization of the specified functional form.
This function integrates over the coordinates of the Wavefunction, with the bounds
specified.

Examples

>>> from sympy import symbols, pi

>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x, L = symbols('x,L', positive=True)
>>> n = symbols('n', integer=True, positive=True)
>>> g = sqrt(2/L)*sin(n*pi*x/L)
(continues on next page)

1748 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> f = Wavefunction(g, (x, 0, L))
>>> f.norm
1
>>> g = sin(n*pi*x/L)
>>> f = Wavefunction(g, (x, 0, L))
>>> f.norm
sqrt(2)*sqrt(L)/2

normalize()
Return a normalized version of the Wavefunction

Examples

>>> from sympy import symbols, pi

>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x = symbols('x', real=True)
>>> L = symbols('L', positive=True)
>>> n = symbols('n', integer=True, positive=True)
>>> g = sin(n*pi*x/L)
>>> f = Wavefunction(g, (x, 0, L))
>>> f.normalize()
Wavefunction(sqrt(2)*sin(pi*n*x/L)/sqrt(L), (x, 0, L))

prob()
Return the absolute magnitude of the w.f., |ψ(x)|2

Examples

>>> from sympy import symbols, pi

>>> from sympy.functions import sqrt, sin
>>> from sympy.physics.quantum.state import Wavefunction
>>> x, L = symbols('x,L', real=True)
>>> n = symbols('n', integer=True)
>>> g = sin(n*pi*x/L)
>>> f = Wavefunction(g, (x, 0, L))
>>> f.prob()
Wavefunction(sin(pi*n*x/L)**2, x)

variables
Return the coordinates which the wavefunction depends on

Examples

>>> from sympy.physics.quantum.state import Wavefunction

>>> from sympy import symbols
>>> x,y = symbols('x,y')
>>> f = Wavefunction(x*y, x, y)
>>> f.variables
(x, y)
(continues on next page)

5.40. Physics Module 1749

SymPy Documentation, Release 1.3

(continued from previous page)

>>> g = Wavefunction(x*y, x)
>>> g.variables
(x,)

Quantum Computation

Circuit Plot

Matplotlib based plotting of quantum circuits.

Todo:
• Optimize printing of large circuits.
• Get this to work with single gates.
• Do a better job checking the form of circuits to make sure it is a Mul of Gates.
• Get multi-target gates plotting.
• Get initial and final states to plot.
• Get measurements to plot. Might need to rethink measurement as a gate issue.
• Get scale and figsize to be handled in a better way.
• Write some tests/examples!
sympy.physics.quantum.circuitplot.labeller(n, symbol=’q’)
Autogenerate labels for wires of quantum circuits.
Parameters n : int
number of qubits in the circuit
symbol : string
A character string to precede all gate labels. E.g. ‘q_0’, ‘q_1’, etc.
>>> from sympy.physics.quantum.circuitplot import labeller
>>> labeller(2)
[‘q_1’, ‘q_0’]
>>> labeller(3,’j’)
[‘j_2’, ‘j_1’, ‘j_0’]
class sympy.physics.quantum.circuitplot.Mz
Mock-up of a z measurement gate.
This is in circuitplot rather than gate.py because it’s not a real gate, it just draws one.
class sympy.physics.quantum.circuitplot.Mx
Mock-up of an x measurement gate.
This is in circuitplot rather than gate.py because it’s not a real gate, it just draws one.
sympy.physics.quantum.circuitplot.CreateCGate(name, latexname=None)
Use a lexical closure to make a controlled gate.

1750 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Gates

An implementation of gates that act on qubits.

Gates are unitary operators that act on the space of qubits.
Medium Term Todo:
• Optimize Gate._apply_operators_Qubit to remove the creation of many intermediate
Qubit objects.
• Add commutation relationships to all operators and use this in gate_sort.
• Fix gate_sort and gate_simp.
• Get multi-target UGates plotting properly.
• Get UGate to work with either sympy/numpy matrices and output either format. This
should also use the matrix slots.
class sympy.physics.quantum.gate.Gate
Non-controlled unitary gate operator that acts on qubits.
This is a general abstract gate that needs to be subclassed to do anything useful.
Parameters label : tuple, int
A list of the target qubits (as ints) that the gate will apply to.
get_target_matrix(format=’sympy’)
The matrix rep. of the target part of the gate.
Parameters format : str
The format string (‘sympy’,’numpy’, etc.)
min_qubits
The minimum number of qubits this gate needs to act on.
nqubits
The total number of qubits this gate acts on.
For controlled gate subclasses this includes both target and control qubits, so that,
for examples the CNOT gate acts on 2 qubits.
targets
A tuple of target qubits.
class sympy.physics.quantum.gate.CGate
A general unitary gate with control qubits.
A general control gate applies a target gate to a set of targets if all of the control qubits
have a particular values (set by CGate.control_value).
Parameters label : tuple
The label in this case has the form (controls, gate), where controls is
a tuple/list of control qubits (as ints) and gate is a Gate instance that
is the target operator.
controls
A tuple of control qubits.
decompose(**options)
Decompose the controlled gate into CNOT and single qubits gates.

5.40. Physics Module 1751

SymPy Documentation, Release 1.3

eval_controls(qubit)
Return True/False to indicate if the controls are satisfied.
gate
The non-controlled gate that will be applied to the targets.
min_qubits
The minimum number of qubits this gate needs to act on.
nqubits
The total number of qubits this gate acts on.
For controlled gate subclasses this includes both target and control qubits, so that,
for examples the CNOT gate acts on 2 qubits.
plot_gate(circ_plot, gate_idx)
Plot the controlled gate. If simplify_cgate is true, simplify C-X and C-Z gates into
their more familiar forms.
targets
A tuple of target qubits.
class sympy.physics.quantum.gate.UGate
General gate specified by a set of targets and a target matrix.
Parameters label : tuple
A tuple of the form (targets, U), where targets is a tuple of the target
qubits and U is a unitary matrix with dimension of len(targets).
get_target_matrix(format=’sympy’)
The matrix rep. of the target part of the gate.
Parameters format : str
The format string (‘sympy’,’numpy’, etc.)
targets
A tuple of target qubits.
class sympy.physics.quantum.gate.OneQubitGate
A single qubit unitary gate base class.
class sympy.physics.quantum.gate.TwoQubitGate
A two qubit unitary gate base class.
class sympy.physics.quantum.gate.IdentityGate
The single qubit identity gate.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.HadamardGate
The single qubit Hadamard gate.
Parameters target : int
The target qubit this gate will apply to.

1752 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import sqrt

>>> from sympy.physics.quantum.qubit import Qubit
>>> from sympy.physics.quantum.gate import HadamardGate
>>> from sympy.physics.quantum.qapply import qapply
>>> qapply(HadamardGate(0)*Qubit('1'))
sqrt(2)*|0>/2 - sqrt(2)*|1>/2
>>> # Hadamard on bell state, applied on 2 qubits.
>>> psi = 1/sqrt(2)*(Qubit('00')+Qubit('11'))
>>> qapply(HadamardGate(0)*HadamardGate(1)*psi)
sqrt(2)*|00>/2 + sqrt(2)*|11>/2

class sympy.physics.quantum.gate.XGate
The single qubit X, or NOT, gate.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.YGate
The single qubit Y gate.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.ZGate
The single qubit Z gate.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.TGate
The single qubit pi/8 gate.
This gate rotates the phase of the state by pi/4 if the state is |1> and does nothing if the
state is |0>.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.PhaseGate
The single qubit phase, or S, gate.
This gate rotates the phase of the state by pi/2 if the state is |1> and does nothing if the
state is |0>.
Parameters target : int
The target qubit this gate will apply to.
class sympy.physics.quantum.gate.SwapGate
Two qubit SWAP gate.
This gate swap the values of the two qubits.
Parameters label : tuple
A tuple of the form (target1, target2).
decompose(**options)
Decompose the SWAP gate into CNOT gates.

5.40. Physics Module 1753

SymPy Documentation, Release 1.3

class sympy.physics.quantum.gate.CNotGate
Two qubit controlled-NOT.
This gate performs the NOT or X gate on the target qubit if the control qubits all have
the value 1.
Parameters label : tuple
A tuple of the form (control, target).

Examples

>>> from sympy.physics.quantum.gate import CNOT

>>> from sympy.physics.quantum.qapply import qapply
>>> from sympy.physics.quantum.qubit import Qubit
>>> c = CNOT(1,0)
>>> qapply(c*Qubit('10')) # note that qubits are indexed from right to left
|11>

controls
A tuple of control qubits.
gate
The non-controlled gate that will be applied to the targets.
min_qubits
The minimum number of qubits this gate needs to act on.
targets
A tuple of target qubits.
sympy.physics.quantum.gate.CNOT
alias of sympy.physics.quantum.gate.CNotGate (page 1753)
sympy.physics.quantum.gate.SWAP
alias of sympy.physics.quantum.gate.SwapGate (page 1753)
sympy.physics.quantum.gate.H
alias of sympy.physics.quantum.gate.HadamardGate (page 1752)
sympy.physics.quantum.gate.X
alias of sympy.physics.quantum.gate.XGate (page 1753)
sympy.physics.quantum.gate.Y
alias of sympy.physics.quantum.gate.YGate (page 1753)
sympy.physics.quantum.gate.Z
alias of sympy.physics.quantum.gate.ZGate (page 1753)
sympy.physics.quantum.gate.T
alias of sympy.physics.quantum.gate.TGate (page 1753)
sympy.physics.quantum.gate.S
alias of sympy.physics.quantum.gate.PhaseGate (page 1753)
sympy.physics.quantum.gate.Phase
alias of sympy.physics.quantum.gate.PhaseGate (page 1753)
sympy.physics.quantum.gate.normalized(normalize)
Set flag controlling normalization of Hadamard gates by 1/sqrt(2).

1754 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

This is a global setting that can be used to simplify the look of various expressions, by
leaving off the leading 1/sqrt(2) of the Hadamard gate.
Parameters normalize : bool
Should the Hadamard gate include the 1/sqrt(2) normalization factor?
When True, the Hadamard gate will have the 1/sqrt(2). When False,
the Hadamard gate will not have this factor.
sympy.physics.quantum.gate.gate_sort(circuit)
Sorts the gates while keeping track of commutation relations
This function uses a bubble sort to rearrange the order of gate application. Keeps track
of Quantum computations special commutation relations (e.g. things that apply to the
same Qubit do not commute with each other)
circuit is the Mul of gates that are to be sorted.
sympy.physics.quantum.gate.gate_simp(circuit)
Simplifies gates symbolically
It first sorts gates using gate_sort. It then applies basic simplification rules to the circuit,
e.g., XGate**2 = Identity
sympy.physics.quantum.gate.random_circuit(ngates, nqubits, gate_space=(<class
’sympy.physics.quantum.gate.XGate’>,
<class ’sympy.physics.quantum.gate.YGate’>,
<class ’sympy.physics.quantum.gate.ZGate’>,
<class ’sympy.physics.quantum.gate.PhaseGate’>,
<class ’sympy.physics.quantum.gate.TGate’>,
<class ’sympy.physics.quantum.gate.HadamardGate’>,
<class ’sympy.physics.quantum.gate.CNotGate’>,
<class ’sympy.physics.quantum.gate.SwapGate’>))
Return a random circuit of ngates and nqubits.
This uses an equally weighted sample of (X, Y, Z, S, T, H, CNOT, SWAP) gates.
Parameters ngates : int
The number of gates in the circuit.
nqubits : int
The number of qubits in the circuit.
gate_space : tuple
A tuple of the gate classes that will be used in the circuit. Repeating
gate classes multiple times in this tuple will increase the frequency
they appear in the random circuit.
class sympy.physics.quantum.gate.CGateS
Version of CGate that allows gate simplifications. I.e. cnot looks like an oplus, cphase
has dots, etc.

Grover’s Algorithm

Grover’s algorithm and helper functions.

Todo:
• W gate construction (or perhaps -W gate based on Mermin’s book)

5.40. Physics Module 1755

SymPy Documentation, Release 1.3

• Generalize the algorithm for an unknown function that returns 1 on multiple qubit states,
not just one.
• Implement _represent_ZGate in OracleGate
class sympy.physics.quantum.grover.OracleGate
A black box gate.
The gate marks the desired qubits of an unknown function by flipping the sign of the
qubits. The unknown function returns true when it finds its desired qubits and false
otherwise.
Parameters qubits : int
Number of qubits.
oracle : callable
A callable function that returns a boolean on a computational basis.

Examples

Apply an Oracle gate that flips the sign of |2> on different qubits:

>>> from sympy.physics.quantum.qubit import IntQubit

>>> from sympy.physics.quantum.qapply import qapply
>>> from sympy.physics.quantum.grover import OracleGate
>>> f = lambda qubits: qubits == IntQubit(2)
>>> v = OracleGate(2, f)
>>> qapply(v*IntQubit(2))
-|2>
>>> qapply(v*IntQubit(3))
|3>

search_function
The unknown function that helps find the sought after qubits.
targets
A tuple of target qubits.
class sympy.physics.quantum.grover.WGate
General n qubit W Gate in Grover’s algorithm.
The gate performs the operation 2|phi><phi| - 1 on some qubits. |phi> = (tensor
product of n Hadamards)*(|0> with n qubits)
Parameters nqubits : int
The number of qubits to operate on
sympy.physics.quantum.grover.superposition_basis(nqubits)
Creates an equal superposition of the computational basis.
Parameters nqubits : int
The number of qubits.
Returns state : Qubit
An equal superposition of the computational basis with nqubits.

1756 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Create an equal superposition of 2 qubits:

>>> from sympy.physics.quantum.grover import superposition_basis

>>> superposition_basis(2)
|0>/2 + |1>/2 + |2>/2 + |3>/2

sympy.physics.quantum.grover.grover_iteration(qstate, oracle)
Applies one application of the Oracle and W Gate, WV.
Parameters qstate : Qubit
A superposition of qubits.
oracle : OracleGate
The black box operator that flips the sign of the desired basis qubits.
Returns Qubit : The qubits after applying the Oracle and W gate.

Examples

Perform one iteration of grover’s algorithm to see a phase change:

>>> from sympy.physics.quantum.qapply import qapply

>>> from sympy.physics.quantum.qubit import IntQubit
>>> from sympy.physics.quantum.grover import OracleGate
>>> from sympy.physics.quantum.grover import superposition_basis
>>> from sympy.physics.quantum.grover import grover_iteration
>>> numqubits = 2
>>> basis_states = superposition_basis(numqubits)
>>> f = lambda qubits: qubits == IntQubit(2)
>>> v = OracleGate(numqubits, f)
>>> qapply(grover_iteration(basis_states, v))
|2>

sympy.physics.quantum.grover.apply_grover(oracle, nqubits, iterations=None)

Applies grover’s algorithm.
Parameters oracle : callable
The unknown callable function that returns true when applied to the
desired qubits and false otherwise.
Returns state : Expr
The resulting state after Grover’s algorithm has been iterated.

Examples

Apply grover’s algorithm to an even superposition of 2 qubits:

>>> from sympy.physics.quantum.qapply import qapply

>>> from sympy.physics.quantum.qubit import IntQubit
>>> from sympy.physics.quantum.grover import apply_grover
>>> f = lambda qubits: qubits == IntQubit(2)
(continues on next page)

5.40. Physics Module 1757

SymPy Documentation, Release 1.3

(continued from previous page)

>>> qapply(apply_grover(f, 2))
|2>

QFT

An implementation of qubits and gates acting on them.

Todo:
• Update docstrings.
• Update tests.
• Implement apply using decompose.
• Implement represent using decompose or something smarter. For this to work we first
have to implement represent for SWAP.
• Decide if we want upper index to be inclusive in the constructor.
• Fix the printing of Rk gates in plotting.
class sympy.physics.quantum.qft.QFT
The forward quantum Fourier transform.
decompose()
Decomposes QFT into elementary gates.
class sympy.physics.quantum.qft.IQFT
The inverse quantum Fourier transform.
decompose()
Decomposes IQFT into elementary gates.
class sympy.physics.quantum.qft.RkGate
This is the R_k gate of the QTF.
sympy.physics.quantum.qft.Rk
alias of sympy.physics.quantum.qft.RkGate (page 1758)

Qubit

Qubits for quantum computing.

Todo: * Finish implementing measurement logic. This should include POVM. * Update doc-
strings. * Update tests.
class sympy.physics.quantum.qubit.Qubit
A multi-qubit ket in the computational (z) basis.
We use the normal convention that the least significant qubit is on the right, so |00001>
has a 1 in the least significant qubit.
Parameters values : list, str
The qubit values as a list of ints ([0,0,0,1,1,]) or a string (‘011’).

1758 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Create a qubit in a couple of different ways and look at their attributes:

>>> from sympy.physics.quantum.qubit import Qubit

>>> Qubit(0,0,0)
|000>
>>> q = Qubit('0101')
>>> q
|0101>

>>> q.nqubits
4
>>> len(q)
4
>>> q.dimension
4
>>> q.qubit_values
(0, 1, 0, 1)

We can flip the value of an individual qubit:

>>> q.flip(1)
|0111>

We can take the dagger of a Qubit to get a bra:

>>> from sympy.physics.quantum.dagger import Dagger

>>> Dagger(q)
<0101|
>>> type(Dagger(q))
<class 'sympy.physics.quantum.qubit.QubitBra'>

Inner products work as expected:

>>> ip = Dagger(q)*q
>>> ip
<0101|0101>
>>> ip.doit()
1

class sympy.physics.quantum.qubit.QubitBra
A multi-qubit bra in the computational (z) basis.
We use the normal convention that the least significant qubit is on the right, so |00001>
has a 1 in the least significant qubit.
Parameters values : list, str
The qubit values as a list of ints ([0,0,0,1,1,]) or a string (‘011’).
See also:

Qubit (page 1758) Examples using qubits

class sympy.physics.quantum.qubit.IntQubit
A qubit ket that store integers as binary numbers in qubit values.
The differences between this class and Qubit are:

5.40. Physics Module 1759

SymPy Documentation, Release 1.3

• The form of the constructor.

• The qubit values are printed as their corresponding integer, rather than the raw
qubit values. The internal storage format of the qubit values in the same as Qubit.

Parameters values : int, tuple

If a single argument, the integer we want to represent in the qubit
values. This integer will be represented using the fewest possible
number of qubits. If a pair of integers, the first integer gives the
integer to represent in binary form and the second integer gives the
number of qubits to use.

Examples

Create a qubit for the integer 5:

>>> from sympy.physics.quantum.qubit import IntQubit

>>> from sympy.physics.quantum.qubit import Qubit
>>> q = IntQubit(5)
>>> q
|5>

We can also create an IntQubit by passing a Qubit instance.

>>> q = IntQubit(Qubit('101'))
>>> q
|5>
>>> q.as_int()
5
>>> q.nqubits
3
>>> q.qubit_values
(1, 0, 1)

We can go back to the regular qubit form.

>>> Qubit(q)
|101>

class sympy.physics.quantum.qubit.IntQubitBra
A qubit bra that store integers as binary numbers in qubit values.
sympy.physics.quantum.qubit.qubit_to_matrix(qubit, format=’sympy’)
Converts an Add/Mul of Qubit objects into it’s matrix representation
This function is the inverse of matrix_to_qubit and is a shorthand for repre-
sent(qubit).
sympy.physics.quantum.qubit.matrix_to_qubit(matrix)
Convert from the matrix repr. to a sum of Qubit objects.
Parameters matrix : Matrix, numpy.matrix, scipy.sparse
The matrix to build the Qubit representation of. This works with
sympy matrices, numpy matrices and scipy.sparse sparse matrices.

1760 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Represent a state and then go back to its qubit form:

>>> from sympy.physics.quantum.qubit import matrix_to_qubit, Qubit

>>> from sympy.physics.quantum.gate import Z
>>> from sympy.physics.quantum.represent import represent
>>> q = Qubit('01')
>>> matrix_to_qubit(represent(q))
|01>

sympy.physics.quantum.qubit.matrix_to_density(mat)
Works by finding the eigenvectors and eigenvalues of the matrix. We know we can de-
compose rho by doing: sum(EigenVal*|Eigenvect><Eigenvect|)
sympy.physics.quantum.qubit.measure_all(qubit, format=’sympy’, normal-
ize=True)
Perform an ensemble measurement of all qubits.
Parameters qubit : Qubit, Add
The qubit to measure. This can be any Qubit or a linear combination
of them.
format : str
The format of the intermediate matrices to use. Possible values
are (‘sympy’,’numpy’,’scipy.sparse’). Currently only ‘sympy’ is imple-
mented.
Returns result : list
A list that consists of primitive states and their probabilities.

Examples

>>> from sympy.physics.quantum.qubit import Qubit, measure_all

>>> from sympy.physics.quantum.gate import H, X, Y, Z
>>> from sympy.physics.quantum.qapply import qapply

>>> c = H(0)*H(1)*Qubit('00')
>>> c
H(0)*H(1)*|00>
>>> q = qapply(c)
>>> measure_all(q)
[(|00>, 1/4), (|01>, 1/4), (|10>, 1/4), (|11>, 1/4)]

sympy.physics.quantum.qubit.measure_partial(qubit, bits, format=’sympy’, nor-

malize=True)
Perform a partial ensemble measure on the specified qubits.
Parameters qubits : Qubit
The qubit to measure. This can be any Qubit or a linear combination
of them.
bits : tuple
The qubits to measure.

5.40. Physics Module 1761

SymPy Documentation, Release 1.3

format : str
The format of the intermediate matrices to use. Possible values
are (‘sympy’,’numpy’,’scipy.sparse’). Currently only ‘sympy’ is imple-
mented.
Returns result : list
A list that consists of primitive states and their probabilities.

Examples

>>> from sympy.physics.quantum.qubit import Qubit, measure_partial

>>> from sympy.physics.quantum.gate import H, X, Y, Z
>>> from sympy.physics.quantum.qapply import qapply

>>> c = H(0)*H(1)*Qubit('00')
>>> c
H(0)*H(1)*|00>
>>> q = qapply(c)
>>> measure_partial(q, (0,))
[(sqrt(2)*|00>/2 + sqrt(2)*|10>/2, 1/2), (sqrt(2)*|01>/2 + sqrt(2)*|11>/2, 1/2)]

sympy.physics.quantum.qubit.measure_partial_oneshot(qubit, bits, for-

mat=’sympy’)
Perform a partial oneshot measurement on the specified qubits.
A oneshot measurement is equivalent to performing a measurement on a quantum sys-
tem. This type of measurement does not return the probabilities like an ensemble mea-
surement does, but rather returns one of the possible resulting states. The exact state
that is returned is determined by picking a state randomly according to the ensemble
probabilities.
Parameters qubits : Qubit
The qubit to measure. This can be any Qubit or a linear combination
of them.
bits : tuple
The qubits to measure.
format : str
The format of the intermediate matrices to use. Possible values
are (‘sympy’,’numpy’,’scipy.sparse’). Currently only ‘sympy’ is imple-
mented.
Returns result : Qubit
The qubit that the system collapsed to upon measurement.
sympy.physics.quantum.qubit.measure_all_oneshot(qubit, format=’sympy’)
Perform a oneshot ensemble measurement on all qubits.
A oneshot measurement is equivalent to performing a measurement on a quantum sys-
tem. This type of measurement does not return the probabilities like an ensemble mea-
surement does, but rather returns one of the possible resulting states. The exact state
that is returned is determined by picking a state randomly according to the ensemble
probabilities.

1762 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters qubits : Qubit

The qubit to measure. This can be any Qubit or a linear combination
of them.
format : str
The format of the intermediate matrices to use. Possible values
are (‘sympy’,’numpy’,’scipy.sparse’). Currently only ‘sympy’ is imple-
mented.
Returns result : Qubit
The qubit that the system collapsed to upon measurement.

Shor’s Algorithm

Shor’s algorithm and helper functions.

Todo:
• Get the CMod gate working again using the new Gate API.
• Fix everything.
• Update docstrings and reformat.
• Remove print statements. We may want to think about a better API for this.
class sympy.physics.quantum.shor.CMod
A controlled mod gate.
This is black box controlled Mod function for use by shor’s algorithm. TODO implement
a decompose property that returns how to do this in terms of elementary gates
N
N is the type of modular arithmetic we are doing.
a
Base of the controlled mod function.
t
Size of 1/2 input register. First 1/2 holds output.
sympy.physics.quantum.shor.period_find(a, N)
Finds the period of a in modulo N arithmetic
This is quantum part of Shor’s algorithm.It takes two registers, puts first in superposition
of states with Hadamards so: |k>|0> with k being all possible choices. It then does a
controlled mod and a QFT to determine the order of a.
sympy.physics.quantum.shor.shor(N)
This function implements Shor’s factoring algorithm on the Integer N
The algorithm starts by picking a random number (a) and seeing if it is coprime with N.
If it isn’t, then the gcd of the two numbers is a factor and we are done. Otherwise, it
begins the period_finding subroutine which finds the period of a in modulo N arithmetic.
This period, if even, can be used to calculate factors by taking a**(r/2)-1 and a**(r/2)+1.
These values are returned.

5.40. Physics Module 1763

SymPy Documentation, Release 1.3

Analytic Solutions

Particle in a Box

1D quantum particle in a box.

class sympy.physics.quantum.piab.PIABHamiltonian
Particle in a box Hamiltonian operator.
class sympy.physics.quantum.piab.PIABKet
Particle in a box eigenket.
class sympy.physics.quantum.piab.PIABBra
Particle in a box eigenbra.

Optics Module

Abstract

Contains docstrings of Physics-Optics module

Gaussian Optics

Gaussian optics.
The module implements:
• Ray transfer matrices for geometrical and gaussian optics.
See RayTransferMatrix, GeometricRay and BeamParameter
• Conjugation relations for geometrical and gaussian optics.
See geometric_conj*, gauss_conj and conjugate_gauss_beams
The conventions for the distances are as follows:
focal distance positive for convergent lenses
object distance positive for real objects
image distance positive for real images
class sympy.physics.optics.gaussopt.RayTransferMatrix
Base class for a Ray Transfer Matrix.
It should be used if there isn’t already a more specific subclass mentioned in See Also.
Parameters parameters : A, B, C and D or 2x2 matrix (Matrix(2, 2, [A, B, C,
D]))
See also:
GeometricRay (page 1769), BeamParameter (page 1770), FreeSpace (page 1766), Fla-
tRefraction (page 1767), CurvedRefraction (page 1767), FlatMirror (page 1768),
CurvedMirror (page 1768), ThinLens (page 1768)

1764 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

References

[R465]

Examples

>>> from sympy.physics.optics import RayTransferMatrix, ThinLens

>>> from sympy import Symbol, Matrix

>>> mat = RayTransferMatrix(1, 2, 3, 4)

>>> mat
Matrix([
[1, 2],
[3, 4]])

>>> RayTransferMatrix(Matrix([[1, 2], [3, 4]]))

Matrix([
[1, 2],
[3, 4]])

>>> mat.A
1

>>> f = Symbol('f')
>>> lens = ThinLens(f)
>>> lens
Matrix([
[ 1, 0],
[-1/f, 1]])

>>> lens.C
-1/f

Attributes

cols
rows

A
The A parameter of the Matrix.

Examples

>>> from sympy.physics.optics import RayTransferMatrix

>>> mat = RayTransferMatrix(1, 2, 3, 4)
>>> mat.A
1

B
The B parameter of the Matrix.

5.40. Physics Module 1765

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.optics import RayTransferMatrix

>>> mat = RayTransferMatrix(1, 2, 3, 4)
>>> mat.B
2

C
The C parameter of the Matrix.

Examples

>>> from sympy.physics.optics import RayTransferMatrix

>>> mat = RayTransferMatrix(1, 2, 3, 4)
>>> mat.C
3

D
The D parameter of the Matrix.

Examples

>>> from sympy.physics.optics import RayTransferMatrix

>>> mat = RayTransferMatrix(1, 2, 3, 4)
>>> mat.D
4

class sympy.physics.optics.gaussopt.FreeSpace
Ray Transfer Matrix for free space.
Parameters distance
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import FreeSpace

>>> from sympy import symbols
>>> d = symbols('d')
>>> FreeSpace(d)
Matrix([
[1, d],
[0, 1]])

Attributes

cols
rows

1766 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.optics.gaussopt.FlatRefraction
Ray Transfer Matrix for refraction.
Parameters n1 : refractive index of one medium
n2 : refractive index of other medium
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import FlatRefraction

>>> from sympy import symbols
>>> n1, n2 = symbols('n1 n2')
>>> FlatRefraction(n1, n2)
Matrix([
[1, 0],
[0, n1/n2]])

Attributes

cols
rows

class sympy.physics.optics.gaussopt.CurvedRefraction
Ray Transfer Matrix for refraction on curved interface.
Parameters R : radius of curvature (positive for concave)
n1 : refractive index of one medium
n2 : refractive index of other medium
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import CurvedRefraction

>>> from sympy import symbols
>>> R, n1, n2 = symbols('R n1 n2')
>>> CurvedRefraction(R, n1, n2)
Matrix([
[ 1, 0],
[(n1 - n2)/(R*n2), n1/n2]])

5.40. Physics Module 1767

SymPy Documentation, Release 1.3

Attributes

cols
rows

class sympy.physics.optics.gaussopt.FlatMirror
Ray Transfer Matrix for reflection.
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import FlatMirror

>>> FlatMirror()
Matrix([
[1, 0],
[0, 1]])

Attributes

cols
rows

class sympy.physics.optics.gaussopt.CurvedMirror
Ray Transfer Matrix for reflection from curved surface.
Parameters R : radius of curvature (positive for concave)
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import CurvedMirror

>>> from sympy import symbols
>>> R = symbols('R')
>>> CurvedMirror(R)
Matrix([
[ 1, 0],
[-2/R, 1]])

Attributes

cols
rows

1768 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.physics.optics.gaussopt.ThinLens
Ray Transfer Matrix for a thin lens.
Parameters f : the focal distance
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import ThinLens

>>> from sympy import symbols
>>> f = symbols('f')
>>> ThinLens(f)
Matrix([
[ 1, 0],
[-1/f, 1]])

Attributes

cols
rows

class sympy.physics.optics.gaussopt.GeometricRay
Representation for a geometric ray in the Ray Transfer Matrix formalism.
Parameters h : height, and
angle : angle, or
matrix : a 2x1 matrix (Matrix(2, 1, [height, angle]))
See also:
RayTransferMatrix (page 1764)

Examples

>>> from sympy.physics.optics import GeometricRay, FreeSpace

>>> from sympy import symbols, Matrix
>>> d, h, angle = symbols('d, h, angle')

>>> GeometricRay(h, angle)

Matrix([
[ h],
[angle]])

>>> FreeSpace(d)*GeometricRay(h, angle)

Matrix([
[angle*d + h],
[ angle]])

5.40. Physics Module 1769

SymPy Documentation, Release 1.3

>>> GeometricRay( Matrix( ((h,), (angle,)) ) )

Matrix([
[ h],
[angle]])

Attributes

cols
rows

angle
The angle with the optical axis.

Examples

>>> from sympy.physics.optics import GeometricRay

>>> from sympy import symbols
>>> h, angle = symbols('h, angle')
>>> gRay = GeometricRay(h, angle)
>>> gRay.angle
angle

height
The distance from the optical axis.

Examples

>>> from sympy.physics.optics import GeometricRay

>>> from sympy import symbols
>>> h, angle = symbols('h, angle')
>>> gRay = GeometricRay(h, angle)
>>> gRay.height
h

class sympy.physics.optics.gaussopt.BeamParameter
Representation for a gaussian ray in the Ray Transfer Matrix formalism.
Parameters wavelen : the wavelength,
z : the distance to waist, and
w : the waist, or
z_r : the rayleigh range
See also:
RayTransferMatrix (page 1764)

References

[R466], [R467]

1770 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.q
1 + 1.88679245283019*I*pi

>>> p.q.n()
1.0 + 5.92753330865999*I
>>> p.w_0.n()
0.00100000000000000
>>> p.z_r.n()
5.92753330865999

>>> from sympy.physics.optics import FreeSpace

>>> fs = FreeSpace(10)
>>> p1 = fs*p
>>> p.w.n()
0.00101413072159615
>>> p1.w.n()
0.00210803120913829

divergence
Half of the total angular spread.

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.divergence
0.00053/pi

gouy
The Gouy phase.

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.gouy
atan(0.53/pi)

q
The complex parameter representing the beam.

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.q
1 + 1.88679245283019*I*pi

5.40. Physics Module 1771

SymPy Documentation, Release 1.3

radius
The radius of curvature of the phase front.

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.radius
1 + 3.55998576005696*pi**2

w
The beam radius at 1/e2 intensity.
See also:

w_0 (page 1772) the minimal radius of beam

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.w
0.001*sqrt(0.2809/pi**2 + 1)

w_0
The beam waist (minimal radius).
See also:

w (page 1772) the beam radius at 1/e2 intensity

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.w_0
0.00100000000000000

waist_approximation_limit
The minimal waist for which the gauss beam approximation is valid.
The gauss beam is a solution to the paraxial equation. For curvatures that are too
great it is not a valid approximation.

Examples

>>> from sympy.physics.optics import BeamParameter

>>> p = BeamParameter(530e-9, 1, w=1e-3)
>>> p.waist_approximation_limit
1.06e-6/pi

1772 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.physics.optics.gaussopt.waist2rayleigh(w, wavelen)
Calculate the rayleigh range from the waist of a gaussian beam.
See also:
rayleigh2waist (page 1773), BeamParameter (page 1770)

Examples

>>> from sympy.physics.optics import waist2rayleigh

>>> from sympy import symbols
>>> w, wavelen = symbols('w wavelen')
>>> waist2rayleigh(w, wavelen)
pi*w**2/wavelen

sympy.physics.optics.gaussopt.rayleigh2waist(z_r, wavelen)
Calculate the waist from the rayleigh range of a gaussian beam.
See also:
waist2rayleigh (page 1772), BeamParameter (page 1770)

Examples

>>> from sympy.physics.optics import rayleigh2waist

>>> from sympy import symbols
>>> z_r, wavelen = symbols('z_r wavelen')
>>> rayleigh2waist(z_r, wavelen)
sqrt(wavelen*z_r)/sqrt(pi)

sympy.physics.optics.gaussopt.geometric_conj_ab(a, b)
Conjugation relation for geometrical beams under paraxial conditions.
Takes the distances to the optical element and returns the needed focal distance.
See also:
geometric_conj_af (page 1773), geometric_conj_bf (page 1774)

Examples

>>> from sympy.physics.optics import geometric_conj_ab

>>> from sympy import symbols
>>> a, b = symbols('a b')
>>> geometric_conj_ab(a, b)
a*b/(a + b)

sympy.physics.optics.gaussopt.geometric_conj_af(a, f)
Conjugation relation for geometrical beams under paraxial conditions.
Takes the object distance (for geometric_conj_af) or the image distance (for geomet-
ric_conj_bf) to the optical element and the focal distance. Then it returns the other
distance needed for conjugation.
See also:
geometric_conj_ab (page 1773)

5.40. Physics Module 1773

SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.optics.gaussopt import geometric_conj_af, geometric_conj_bf

>>> from sympy import symbols
>>> a, b, f = symbols('a b f')
>>> geometric_conj_af(a, f)
a*f/(a - f)
>>> geometric_conj_bf(b, f)
b*f/(b - f)

sympy.physics.optics.gaussopt.geometric_conj_bf(a, f)
Conjugation relation for geometrical beams under paraxial conditions.
Takes the object distance (for geometric_conj_af) or the image distance (for geomet-
ric_conj_bf) to the optical element and the focal distance. Then it returns the other
distance needed for conjugation.
See also:
geometric_conj_ab (page 1773)

Examples

>>> from sympy.physics.optics.gaussopt import geometric_conj_af, geometric_conj_bf

>>> from sympy import symbols
>>> a, b, f = symbols('a b f')
>>> geometric_conj_af(a, f)
a*f/(a - f)
>>> geometric_conj_bf(b, f)
b*f/(b - f)

sympy.physics.optics.gaussopt.gaussian_conj(s_in, z_r_in, f)
Conjugation relation for gaussian beams.
Parameters s_in : the distance to optical element from the waist
z_r_in : the rayleigh range of the incident beam
f : the focal length of the optical element
Returns a tuple containing (s_out, z_r_out, m)
s_out : the distance between the new waist and the optical element
z_r_out : the rayleigh range of the emergent beam
m : the ration between the new and the old waists

Examples

>>> from sympy.physics.optics import gaussian_conj

>>> from sympy import symbols
>>> s_in, z_r_in, f = symbols('s_in z_r_in f')

>>> gaussian_conj(s_in, z_r_in, f)[0]

1/(-1/(s_in + z_r_in**2/(-f + s_in)) + 1/f)

1774 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> gaussian_conj(s_in, z_r_in, f)[1]

z_r_in/(1 - s_in**2/f**2 + z_r_in**2/f**2)

>>> gaussian_conj(s_in, z_r_in, f)[2]

1/sqrt(1 - s_in**2/f**2 + z_r_in**2/f**2)

sympy.physics.optics.gaussopt.conjugate_gauss_beams(wavelen, waist_in,
waist_out, **kwargs)
Find the optical setup conjugating the object/image waists.
Parameters wavelen : the wavelength of the beam
waist_in and waist_out : the waists to be conjugated
f : the focal distance of the element used in the conjugation
Returns a tuple containing (s_in, s_out, f)
s_in : the distance before the optical element
s_out : the distance after the optical element
f : the focal distance of the optical element

Examples

>>> from sympy.physics.optics import conjugate_gauss_beams

>>> from sympy import symbols, factor
>>> l, w_i, w_o, f = symbols('l w_i w_o f')

>>> conjugate_gauss_beams(l, w_i, w_o, f=f)[0]

f*(-sqrt(w_i**2/w_o**2 - pi**2*w_i**4/(f**2*l**2)) + 1)

>>> factor(conjugate_gauss_beams(l, w_i, w_o, f=f)[1])

f*w_o**2*(w_i**2/w_o**2 - sqrt(w_i**2/w_o**2 -
pi**2*w_i**4/(f**2*l**2)))/w_i**2

>>> conjugate_gauss_beams(l, w_i, w_o, f=f)[2]

f

Medium

Contains
• Medium
class sympy.physics.optics.medium.Medium
This class represents an optical medium. The prime reason to implement this is to facil-
itate refraction, Fermat’s principle, etc.
An optical medium is a material through which electromagnetic waves propagate. The
permittivity and permeability of the medium define how electromagnetic waves propa-
gate in it.
Parameters name: string

5.40. Physics Module 1775

SymPy Documentation, Release 1.3

The display name of the Medium.

permittivity: Sympifyable
Electric permittivity of the space.
permeability: Sympifyable
Magnetic permeability of the space.
n: Sympifyable
Index of refraction of the medium.

References

[R468]

Examples

>>> from sympy.abc import epsilon, mu

>>> from sympy.physics.optics import Medium
>>> m1 = Medium('m1')
>>> m2 = Medium('m2', epsilon, mu)
>>> m1.intrinsic_impedance
149896229*pi*kilogram*meter**2/(1250000*ampere**2*second**3)
>>> m2.refractive_index
299792458*meter*sqrt(epsilon*mu)/second

intrinsic_impedance
Returns intrinsic impedance of the medium.
The intrinsic impedance of a medium is the ratio of the transverse components of the
electric and magnetic fields of the electromagnetic wave travelling in the medium.
In a region with no electrical conductivity it simplifies to the square root of ratio of
magnetic permeability to electric permittivity.

Examples

>>> from sympy.physics.optics import Medium

>>> m = Medium('m')
>>> m.intrinsic_impedance
149896229*pi*kilogram*meter**2/(1250000*ampere**2*second**3)

permeability
Returns magnetic permeability of the medium.

Examples

>>> from sympy.physics.optics import Medium

>>> m = Medium('m')
>>> m.permeability
pi*kilogram*meter/(2500000*ampere**2*second**2)

1776 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

permittivity
Returns electric permittivity of the medium.

Examples

>>> from sympy.physics.optics import Medium

>>> m = Medium('m')
>>> m.permittivity
625000*ampere**2*second**4/(22468879468420441*pi*kilogram*meter**3)

refractive_index
Returns refractive index of the medium.

Examples

>>> from sympy.physics.optics import Medium

>>> m = Medium('m')
>>> m.refractive_index
1

speed
Returns speed of the electromagnetic wave travelling in the medium.

Examples

>>> from sympy.physics.optics import Medium

>>> m = Medium('m')
>>> m.speed
299792458*meter/second

Utilities

Contains
• refraction_angle
• deviation
• brewster_angle
• lens_makers_formula
• mirror_formula
• lens_formula
• hyperfocal_distance
• transverse_magnification
sympy.physics.optics.utils.refraction_angle(incident, medium1, medium2, nor-
mal=None, plane=None)
This function calculates transmitted vector after refraction at planar surface. medium1
and medium2 can be M edium or any sympifiable object.

5.40. Physics Module 1777

SymPy Documentation, Release 1.3

If incident is an object of Ray3D, normal also has to be an instance of Ray3D in order to

get the output as a Ray3D. Please note that if plane of separation is not provided and
normal is an instance of Ray3D, normal will be assumed to be intersecting incident ray
at the plane of separation. This will not be the case when normal is a M atrix or any other
sequence. If incident is an instance of Ray3D and plane has not been provided and normal
is not Ray3D, output will be a M atrix.
Parameters incident : Matrix, Ray3D, or sequence
Incident vector
medium1 : sympy.physics.optics.medium.Medium or sympifiable
Medium 1 or its refractive index
medium2 : sympy.physics.optics.medium.Medium or sympifiable
Medium 2 or its refractive index
normal : Matrix, Ray3D, or sequence
Normal vector
plane : Plane
Plane of separation of the two media.

Examples

>>> from sympy.physics.optics import refraction_angle

>>> from sympy.geometry import Point3D, Ray3D, Plane
>>> from sympy.matrices import Matrix
>>> from sympy import symbols
>>> n = Matrix([0, 0, 1])
>>> P = Plane(Point3D(0, 0, 0), normal_vector=[0, 0, 1])
>>> r1 = Ray3D(Point3D(-1, -1, 1), Point3D(0, 0, 0))
>>> refraction_angle(r1, 1, 1, n)
Matrix([
[ 1],
[ 1],
[-1]])
>>> refraction_angle(r1, 1, 1, plane=P)
Ray3D(Point3D(0, 0, 0), Point3D(1, 1, -1))

With different index of refraction of the two media

>>> n1, n2 = symbols('n1, n2')

>>> refraction_angle(r1, n1, n2, n)
Matrix([
[ n1/n2],
[ n1/n2],
[-sqrt(3)*sqrt(-2*n1**2/(3*n2**2) + 1)]])
>>> refraction_angle(r1, n1, n2, plane=P)
Ray3D(Point3D(0, 0, 0), Point3D(n1/n2, n1/n2, -sqrt(3)*sqrt(-2*n1**2/(3*n2**2) +␣
,→1)))

sympy.physics.optics.utils.deviation(incident, medium1, medium2, nor-

mal=None, plane=None)
This function calculates the angle of deviation of a ray due to refraction at planar surface.

1778 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters incident : Matrix, Ray3D, or sequence

Incident vector
medium1 : sympy.physics.optics.medium.Medium or sympifiable
Medium 1 or its refractive index
medium2 : sympy.physics.optics.medium.Medium or sympifiable
Medium 2 or its refractive index
normal : Matrix, Ray3D, or sequence
Normal vector
plane : Plane
Plane of separation of the two media.

Examples

>>> from sympy.physics.optics import deviation

>>> from sympy.geometry import Point3D, Ray3D, Plane
>>> from sympy.matrices import Matrix
>>> from sympy import symbols
>>> n1, n2 = symbols('n1, n2')
>>> n = Matrix([0, 0, 1])
>>> P = Plane(Point3D(0, 0, 0), normal_vector=[0, 0, 1])
>>> r1 = Ray3D(Point3D(-1, -1, 1), Point3D(0, 0, 0))
>>> deviation(r1, 1, 1, n)
0
>>> deviation(r1, n1, n2, plane=P)
-acos(-sqrt(-2*n1**2/(3*n2**2) + 1)) + acos(-sqrt(3)/3)

sympy.physics.optics.utils.brewster_angle(medium1, medium2)
This function calculates the Brewster’s angle of incidence to Medium 2 from Medium 1
in radians.
Parameters medium 1 : Medium or sympifiable
Refractive index of Medium 1
medium 2 : Medium or sympifiable
Refractive index of Medium 1

Examples

>>> from sympy.physics.optics import brewster_angle

>>> brewster_angle(1, 1.33)
0.926093295503462

sympy.physics.optics.utils.lens_makers_formula(n_lens, n_surr, r1, r2)

This function calculates focal length of a thin lens. It follows cartesian sign convention.
Parameters n_lens : Medium or sympifiable
Index of refraction of lens.

5.40. Physics Module 1779

SymPy Documentation, Release 1.3

n_surr : Medium or sympifiable

Index of reflection of surrounding.
r1 : sympifiable
Radius of curvature of first surface.
r2 : sympifiable
Radius of curvature of second surface.

Examples

>>> from sympy.physics.optics import lens_makers_formula

>>> lens_makers_formula(1.33, 1, 10, -10)
15.1515151515151

sympy.physics.optics.utils.mirror_formula(focal_length=None, u=None,
v=None)
This function provides one of the three parameters when two of them are supplied. This
is valid only for paraxial rays.
Parameters focal_length : sympifiable
Focal length of the mirror.
u : sympifiable
Distance of object from the pole on the principal axis.
v : sympifiable
Distance of the image from the pole on the principal axis.

Examples

>>> from sympy.physics.optics import mirror_formula

>>> from sympy.abc import f, u, v
>>> mirror_formula(focal_length=f, u=u)
f*u/(-f + u)
>>> mirror_formula(focal_length=f, v=v)
f*v/(-f + v)
>>> mirror_formula(u=u, v=v)
u*v/(u + v)

sympy.physics.optics.utils.lens_formula(focal_length=None, u=None, v=None)

This function provides one of the three parameters when two of them are supplied. This
is valid only for paraxial rays.
Parameters focal_length : sympifiable
Focal length of the mirror.
u : sympifiable
Distance of object from the optical center on the principal axis.
v : sympifiable
Distance of the image from the optical center on the principal axis.

1780 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.physics.optics import lens_formula

>>> from sympy.abc import f, u, v
>>> lens_formula(focal_length=f, u=u)
f*u/(f + u)
>>> lens_formula(focal_length=f, v=v)
f*v/(f - v)
>>> lens_formula(u=u, v=v)
u*v/(u - v)

sympy.physics.optics.utils.hyperfocal_distance(f, N, c)
Parameters f: sympifiable
Focal length of a given lens
N: sympifiable
F-number of a given lens
c: sympifiable
Circle of Confusion (CoC) of a given image format

Example

>>> from sympy.physics.optics import hyperfocal_distance

>>> from sympy.abc import f, N, c
>>> round(hyperfocal_distance(f = 0.5, N = 8, c = 0.0033), 2)
9.47

sympy.physics.optics.utils.transverse_magnification(si, so)
Calculates the transverse magnification, which is the ratio of the image size to the object
size.
Parameters so: sympifiable
Lens-object distance
si: sympifiable
Lens-image distance

Example

>>> from sympy.physics.optics import transverse_magnification

>>> transverse_magnification(30, 15)
-2

Waves

This module has all the classes and functions related to waves in optics.
Contains

5.40. Physics Module 1781

SymPy Documentation, Release 1.3

• TWave
class sympy.physics.optics.waves.TWave(amplitude, frequency=None, phase=0,
time_period=None, n=n)
This is a simple transverse sine wave travelling in a one-dimensional space. Basic prop-
erties are required at the time of creation of the object, but they can be changed later
with respective methods provided.
It is represented as A × cos(k ∗ x − ω × t + ϕ), where A is the amplitude, ω is the angular
velocity, k is the wavenumber (spatial frequency), x is a spatial variable to represent the
position on the dimension on which the wave propagates, and ϕ is the phase angle of the
wave.
Raises ValueError : When neither frequency nor time period is provided
or they are not consistent.
TypeError : When anything other than TWave objects is added.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A1, phi1, A2, phi2, f = symbols('A1, phi1, A2, phi2, f')
>>> w1 = TWave(A1, f, phi1)
>>> w2 = TWave(A2, f, phi2)
>>> w3 = w1 + w2 # Superposition of two waves
>>> w3
TWave(sqrt(A1**2 + 2*A1*A2*cos(phi1 - phi2) + A2**2), f,
atan2(A1*cos(phi1) + A2*cos(phi2), A1*sin(phi1) + A2*sin(phi2)))
>>> w3.amplitude
sqrt(A1**2 + 2*A1*A2*cos(phi1 - phi2) + A2**2)
>>> w3.phase
atan2(A1*cos(phi1) + A2*cos(phi2), A1*sin(phi1) + A2*sin(phi2))
>>> w3.speed
299792458*meter/(second*n)
>>> w3.angular_velocity
2*pi*f

Arguments

amplitude [Sympifyable] Amplitude of the wave.

frequency [Sympifyable] Frequency of the wave.
phase [Sympifyable] Phase angle of the wave.
time_period [Sympifyable] Time period of the wave.
n [Sympifyable] Refractive index of the medium.

amplitude
Returns the amplitude of the wave.

1782 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.amplitude
A

angular_velocity
Returns the angular velocity of the wave, in radians per second.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.angular_velocity
2*pi*f

frequency
Returns the frequency of the wave, in cycles per second.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.frequency
f

phase
Returns the phase angle of the wave, in radians.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.phase
phi

speed
Returns the propagation speed of the wave, in meters per second. It is dependent
on the propagation medium.

5.40. Physics Module 1783

SymPy Documentation, Release 1.3

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.speed
299792458*meter/(second*n)

time_period
Returns the temporal period of the wave, in seconds per cycle.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.time_period
1/f

wavelength
Returns the wavelength (spatial period) of the wave, in meters per cycle. It depends
on the medium of the wave.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.wavelength
299792458*meter/(second*f*n)

wavenumber
Returns the wavenumber of the wave, in radians per meter.

Examples

>>> from sympy import symbols

>>> from sympy.physics.optics import TWave
>>> A, phi, f = symbols('A, phi, f')
>>> w = TWave(A, f, phi)
>>> w.wavenumber
pi*second*f*n/(149896229*meter)

Continuum Mechanics

1784 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Abstract

Contains docstrings for methods in continuum mechanics module.

Beam

Beam (Docstrings)

Beam

This module can be used to solve 2D beam bending problems with singularity functions in
mechanics.
class sympy.physics.continuum_mechanics.beam.Beam(length, elastic_modulus,
second_moment, vari-
able=x, base_char=’C’)
A Beam is a structural element that is capable of withstanding load primarily by resist-
ing against bending. Beams are characterized by their cross sectional profile(Second
moment of area), their length and their material.

Note: While solving a beam bending problem, a user should choose its own sign con-
vention and should stick to it. The results will automatically follow the chosen sign
convention.

Examples

There is a beam of length 4 meters. A constant distributed load of 6 N/m is applied from
half of the beam till the end. There are two simple supports below the beam, one at the
starting point and another at the ending point of the beam. The deflection of the beam
at the end is restricted.
Using the sign convention of downwards forces being positive.
>>> from sympy.physics.continuum_mechanics.beam import Beam
>>> from sympy import symbols, Piecewise
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(4, E, I)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(6, 2, 0)
>>> b.apply_load(R2, 4, -1)
>>> b.bc_deflection = [(0, 0), (4, 0)]
>>> b.boundary_conditions
{'deflection': [(0, 0), (4, 0)], 'slope': []}
>>> b.load
R1*SingularityFunction(x, 0, -1) + R2*SingularityFunction(x, 4, -1) +␣
,→6*SingularityFunction(x, 2, 0)

>>> b.solve_for_reaction_loads(R1, R2)

>>> b.load
-3*SingularityFunction(x, 0, -1) + 6*SingularityFunction(x, 2, 0) -␣
,→9*SingularityFunction(x, 4, -1)
(continues on next page)

5.40. Physics Module 1785

SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.shear_force()
-3*SingularityFunction(x, 0, 0) + 6*SingularityFunction(x, 2, 1) -␣
,→9*SingularityFunction(x, 4, 0)

>>> b.bending_moment()
-3*SingularityFunction(x, 0, 1) + 3*SingularityFunction(x, 2, 2) -␣
,→9*SingularityFunction(x, 4, 1)

>>> b.slope()
(-3*SingularityFunction(x, 0, 2)/2 + SingularityFunction(x, 2, 3) -␣
,→9*SingularityFunction(x, 4, 2)/2 + 7)/(E*I)

>>> b.deflection()
(7*x - SingularityFunction(x, 0, 3)/2 + SingularityFunction(x, 2, 4)/4 -␣
,→3*SingularityFunction(x, 4, 3)/2)/(E*I)

>>> b.deflection().rewrite(Piecewise)
(7*x - Piecewise((x**3, x > 0), (0, True))/2
- 3*Piecewise(((x - 4)**3, x - 4 > 0), (0, True))/2
+ Piecewise(((x - 2)**4, x - 2 > 0), (0, True))/4)/(E*I)

applied_loads
Returns a list of all loads applied on the beam object. Each load in the list is a tuple
of form (value, start, order, end).

Examples

There is a beam of length 4 meters. A moment of magnitude 3 Nm is applied in the

clockwise direction at the starting point of the beam. A pointload of magnitude 4
N is applied from the top of the beam at 2 meters from the starting point. Another
pointload of magnitude 5 N is applied at same position.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(4, E, I)
>>> b.apply_load(-3, 0, -2)
>>> b.apply_load(4, 2, -1)
>>> b.apply_load(5, 2, -1)
>>> b.load
-3*SingularityFunction(x, 0, -2) + 9*SingularityFunction(x, 2, -1)
>>> b.applied_loads
[(-3, 0, -2, None), (4, 2, -1, None), (5, 2, -1, None)]

apply_load(value, start, order, end=None)

This method adds up the loads given to a particular beam object.
Parameters value : Sympifyable
The magnitude of an applied load.
start : Sympifyable
The starting point of the applied load. For point moments and point
forces this is the location of application.
order : Integer
The order of the applied load. - For moments, order= -2 - For point
loads, order=-1 - For constant distributed load, order=0 - For ramp
loads, order=1 - For parabolic ramp loads, order=2 - … so on.

1786 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

end : Sympifyable, optional

An optional argument that can be used if the load has an end point
within the length of the beam.

Examples

There is a beam of length 4 meters. A moment of magnitude 3 Nm is applied in

the clockwise direction at the starting point of the beam. A pointload of magnitude
4 N is applied from the top of the beam at 2 meters from the starting point and a
parabolic ramp load of magnitude 2 N/m is applied below the beam starting from 2
meters to 3 meters away from the starting point of the beam.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(4, E, I)
>>> b.apply_load(-3, 0, -2)
>>> b.apply_load(4, 2, -1)
>>> b.apply_load(-2, 2, 2, end = 3)
>>> b.load
-3*SingularityFunction(x, 0, -2) + 4*SingularityFunction(x, 2, -1) -␣
,→2*SingularityFunction(x, 2, 2)

+ 2*SingularityFunction(x, 3, 0) + 2*SingularityFunction(x, 3, 2)

apply_support(loc, type=’fixed’)
This method applies support to a particular beam object.
Parameters loc : Sympifyable
Location of point at which support is applied.
type : String
Determines type of Beam support applied. To apply support structure
with - zero degree of freedom, type = “fixed” - one degree of freedom,
type = “pin” - two degrees of freedom, type = “roller”

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is
applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(30, E, I)
>>> b.apply_support(10, 'roller')
>>> b.apply_support(30, 'roller')
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(120, 30, -2)
(continues on next page)

5.40. Physics Module 1787

SymPy Documentation, Release 1.3

(continued from previous page)

>>> R_10, R_30 = symbols('R_10, R_30')
>>> b.solve_for_reaction_loads(R_10, R_30)
>>> b.load
-8*SingularityFunction(x, 0, -1) + 6*SingularityFunction(x, 10, -1)
+ 120*SingularityFunction(x, 30, -2) + 2*SingularityFunction(x, 30, -1)
>>> b.slope()
(-4*SingularityFunction(x, 0, 2) + 3*SingularityFunction(x, 10, 2)
+ 120*SingularityFunction(x, 30, 1) + SingularityFunction(x, 30, 2) +␣
,→4000/3)/(E*I)

bending_moment()
Returns a Singularity Function expression which represents the bending moment
curve of the Beam object.

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is
applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.
>>> from sympy.physics.continuum_mechanics.beam import Beam
>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1)
>>> b.apply_load(R2, 30, -1)
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection = [(10, 0), (30, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.bending_moment()
-8*SingularityFunction(x, 0, 1) + 6*SingularityFunction(x, 10, 1) +␣
,→120*SingularityFunction(x, 30, 0) + 2*SingularityFunction(x, 30, 1)

boundary_conditions
Returns a dictionary of boundary conditions applied on the beam. The dictionary has
three kewwords namely moment, slope and deflection. The value of each keyword is
a list of tuple, where each tuple contains loaction and value of a boundary condition
in the format (location, value).

Examples

There is a beam of length 4 meters. The bending moment at 0 should be 4 and at 4

it should be 0. The slope of the beam should be 1 at 0. The deflection should be 2
at 0.
>>> from sympy.physics.continuum_mechanics.beam import Beam
>>> from sympy import symbols
(continues on next page)

1788 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> E, I = symbols('E, I')
>>> b = Beam(4, E, I)
>>> b.bc_deflection = [(0, 2)]
>>> b.bc_slope = [(0, 1)]
>>> b.boundary_conditions
{'deflection': [(0, 2)], 'slope': [(0, 1)]}

Here the deflection of the beam should be 2 at 0. Similarly, the slope of the beam
should be 1 at 0.
deflection()
Returns a Singularity Function expression which represents the elastic curve or
deflection of the Beam object.

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is
applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1)
>>> b.apply_load(R2, 30, -1)
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection = [(10, 0), (30, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.deflection()
(4000*x/3 - 4*SingularityFunction(x, 0, 3)/3 + SingularityFunction(x, 10, 3)
+ 60*SingularityFunction(x, 30, 2) + SingularityFunction(x, 30, 3)/3 -␣
,→12000)/(E*I)

elastic_modulus
Young’s Modulus of the Beam.
join(beam, via=’fixed’)
This method joins two beams to make a new composite beam system. Passed Beam
class instance is attached to the right end of calling object. This method can be used
to form beams having Discontinuous values of Elastic modulus or Second moment.
Parameters beam : Beam class object
The Beam object which would be connected to the right of calling
object.
via : String
States the way two Beam object would get connected - For ax-
ially fixed Beams, via=”fixed” - For Beams connected via hinge,

5.40. Physics Module 1789

SymPy Documentation, Release 1.3

via=”hinge”

Examples

There is a cantilever beam of length 4 meters. For first 2 meters its moment of
inertia is 1.5 ∗ I and I for the other end. A pointload of magnitude 4 N is applied from
the top at its free end.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b1 = Beam(2, E, 1.5*I)
>>> b2 = Beam(2, E, I)
>>> b = b1.join(b2, ”fixed”)
>>> b.apply_load(20, 4, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 0, -2)
>>> b.bc_slope = [(0, 0)]
>>> b.bc_deflection = [(0, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.load
80*SingularityFunction(x, 0, -2) - 20*SingularityFunction(x, 0, -1) +␣
,→20*SingularityFunction(x, 4, -1)

>>> b.slope()
(((80*SingularityFunction(x, 0, 1) - 10*SingularityFunction(x, 0, 2) +␣
,→10*SingularityFunction(x, 4, 2))/I - 120/I)/E + 80.0/

,→(E*I))*SingularityFunction(x, 2, 0)

+ 0.666666666666667*(80*SingularityFunction(x, 0, 1) -␣
,→10*SingularityFunction(x, 0, 2) + 10*SingularityFunction(x, 4,␣

,→2))*SingularityFunction(x, 0, 0)/(E*I)

- 0.666666666666667*(80*SingularityFunction(x, 0, 1) -␣
,→10*SingularityFunction(x, 0, 2) + 10*SingularityFunction(x, 4,␣

,→2))*SingularityFunction(x, 2, 0)/(E*I)

length
Length of the Beam.
load
Returns a Singularity Function expression which represents the load distribution
curve of the Beam object.

Examples

There is a beam of length 4 meters. A moment of magnitude 3 Nm is applied in

the clockwise direction at the starting point of the beam. A pointload of magnitude
4 N is applied from the top of the beam at 2 meters from the starting point and a
parabolic ramp load of magnitude 2 N/m is applied below the beam starting from 3
meters away from the starting point of the beam.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(4, E, I)
(continues on next page)

1790 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.apply_load(-3, 0, -2)
>>> b.apply_load(4, 2, -1)
>>> b.apply_load(-2, 3, 2)
>>> b.load
-3*SingularityFunction(x, 0, -2) + 4*SingularityFunction(x, 2, -1) -␣
,→2*SingularityFunction(x, 3, 2)

max_bmoment()
Returns maximum Shear force and its coordinate in the Beam object.
max_deflection()
Returns point of max deflection and its coresponding deflection value in a Beam
object.
max_shear_force()
Returns maximum Shear force and its coordinate in the Beam object.
plot_bending_moment(subs=None)
Returns a plot for Bending moment present in the Beam object.
Parameters subs : dictionary
Python dictionary containing Symbols as key and their corresponding
values.

Examples

There is a beam of length 8 meters. A constant distributed load of 10 KN/m is applied

from half of the beam till the end. There are two simple supports below the beam,
one at the starting point and another at the ending point of the beam. A pointload
of magnitude 5 KN is also applied from top of the beam, at a distance of 4 meters
from the starting point. Take E = 200 GPa and I = 400*(10**-6) meter**4.
Using the sign convention of downwards forces being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(8, 200*(10**9), 400*(10**-6))
>>> b.apply_load(5000, 2, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(10000, 4, 0, end=8)
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.plot_bending_moment()
Plot object containing:
[0]: cartesian line: -13750*SingularityFunction(x, 0, 1) +␣
,→5000*SingularityFunction(x, 2, 1)

+ 5000*SingularityFunction(x, 4, 2) - 31250*SingularityFunction(x, 8, 1)
- 5000*SingularityFunction(x, 8, 2) for x over (0.0, 8.0)

plot_deflection(subs=None)
Returns a plot for deflection curve of the Beam object.
Parameters subs : dictionary

5.40. Physics Module 1791

SymPy Documentation, Release 1.3

Python dictionary containing Symbols as key and their corresponding

values.

Examples

There is a beam of length 8 meters. A constant distributed load of 10 KN/m is applied

from half of the beam till the end. There are two simple supports below the beam,
one at the starting point and another at the ending point of the beam. A pointload
of magnitude 5 KN is also applied from top of the beam, at a distance of 4 meters
from the starting point. Take E = 200 GPa and I = 400*(10**-6) meter**4.
Using the sign convention of downwards forces being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(8, 200*(10**9), 400*(10**-6))
>>> b.apply_load(5000, 2, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(10000, 4, 0, end=8)
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.plot_deflection()
Plot object containing:
[0]: cartesian line: 0.00138541666666667*x - 2.86458333333333e-
,→5*SingularityFunction(x, 0, 3)

+ 1.04166666666667e-5*SingularityFunction(x, 2, 3) + 5.20833333333333e-
,→6*SingularityFunction(x, 4, 4)

- 6.51041666666667e-5*SingularityFunction(x, 8, 3) - 5.20833333333333e-
,→6*SingularityFunction(x, 8, 4)

for x over (0.0, 8.0)

plot_loading_results(subs=None)
Returns Axes object containing subplots of Shear Force, Bending Moment, Slope
and Deflection of the Beam object.
Parameters subs : dictionary
Python dictionary containing Symbols as key and their corresponding
values.
.. note::
This method only works if numpy and matplotlib libraries are installed
on the system.

Examples

There is a beam of length 8 meters. A constant distributed load of 10 KN/m is applied

from half of the beam till the end. There are two simple supports below the beam,
one at the starting point and another at the ending point of the beam. A pointload
of magnitude 5 KN is also applied from top of the beam, at a distance of 4 meters
from the starting point. Take E = 200 GPa and I = 400*(10**-6) meter**4.
Using the sign convention of downwards forces being positive.

1792 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(8, 200*(10**9), 400*(10**-6))
>>> b.apply_load(5000, 2, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(10000, 4, 0, end=8)
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> axes = b.plot_loading_results()

plot_shear_force(subs=None)
Returns a plot for Shear force present in the Beam object.
Parameters subs : dictionary
Python dictionary containing Symbols as key and their corresponding
values.

Examples

There is a beam of length 8 meters. A constant distributed load of 10 KN/m is applied

from half of the beam till the end. There are two simple supports below the beam,
one at the starting point and another at the ending point of the beam. A pointload
of magnitude 5 KN is also applied from top of the beam, at a distance of 4 meters
from the starting point. Take E = 200 GPa and I = 400*(10**-6) meter**4.
Using the sign convention of downwards forces being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(8, 200*(10**9), 400*(10**-6))
>>> b.apply_load(5000, 2, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(10000, 4, 0, end=8)
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.plot_shear_force()
Plot object containing:
[0]: cartesian line: -13750*SingularityFunction(x, 0, 0) +␣
,→5000*SingularityFunction(x, 2, 0)

+ 10000*SingularityFunction(x, 4, 1) - 31250*SingularityFunction(x, 8, 0)
- 10000*SingularityFunction(x, 8, 1) for x over (0.0, 8.0)

plot_slope(subs=None)
Returns a plot for slope of deflection curve of the Beam object.
Parameters subs : dictionary
Python dictionary containing Symbols as key and their corresponding
values.

5.40. Physics Module 1793

SymPy Documentation, Release 1.3

Examples

There is a beam of length 8 meters. A constant distributed load of 10 KN/m is applied

from half of the beam till the end. There are two simple supports below the beam,
one at the starting point and another at the ending point of the beam. A pointload
of magnitude 5 KN is also applied from top of the beam, at a distance of 4 meters
from the starting point. Take E = 200 GPa and I = 400*(10**-6) meter**4.
Using the sign convention of downwards forces being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(8, 200*(10**9), 400*(10**-6))
>>> b.apply_load(5000, 2, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(10000, 4, 0, end=8)
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.plot_slope()
Plot object containing:
[0]: cartesian line: -8.59375e-5*SingularityFunction(x, 0, 2) + 3.125e-
,→5*SingularityFunction(x, 2, 2)

+ 2.08333333333333e-5*SingularityFunction(x, 4, 3) - 0.
,→0001953125*SingularityFunction(x, 8, 2)

- 2.08333333333333e-5*SingularityFunction(x, 8, 3) + 0.00138541666666667 for␣

,→x over (0.0, 8.0)

point_cflexure()
Returns a Set of point(s) with zero bending moment and where bending moment
curve of the beam object changes its sign from negative to positive or vice versa.

Examples

There is is 10 meter long overhanging beam. There are two simple supports below
the beam. One at the start and another one at a distance of 6 meters from the start.
Point loads of magnitude 10KN and 20KN are applied at 2 meters and 4 meters from
start respectively. A Uniformly distribute load of magnitude of magnitude 3KN/m is
also applied on top starting from 6 meters away from starting point till end. Using
the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(10, E, I)
>>> b.apply_load(-4, 0, -1)
>>> b.apply_load(-46, 6, -1)
>>> b.apply_load(10, 2, -1)
>>> b.apply_load(20, 4, -1)
>>> b.apply_load(3, 6, 0)
>>> b.point_cflexure()
[10/3]

reaction_loads
Returns the reaction forces in a dictionary.

1794 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

remove_load(value, start, order, end=None)

This method removes a particular load present on the beam object. Returns a Val-
ueError if the load passed as an argument is not present on the beam.
Parameters value : Sympifyable
The magnitude of an applied load.
start : Sympifyable
The starting point of the applied load. For point moments and point
forces this is the location of application.
order : Integer
The order of the applied load. - For moments, order= -2 - For point
loads, order=-1 - For constant distributed load, order=0 - For ramp
loads, order=1 - For parabolic ramp loads, order=2 - … so on.
end : Sympifyable, optional
An optional argument that can be used if the load has an end point
within the length of the beam.

Examples

There is a beam of length 4 meters. A moment of magnitude 3 Nm is applied in

the clockwise direction at the starting point of the beam. A pointload of magnitude
4 N is applied from the top of the beam at 2 meters from the starting point and a
parabolic ramp load of magnitude 2 N/m is applied below the beam starting from 2
meters to 3 meters away from the starting point of the beam.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> b = Beam(4, E, I)
>>> b.apply_load(-3, 0, -2)
>>> b.apply_load(4, 2, -1)
>>> b.apply_load(-2, 2, 2, end = 3)
>>> b.load
-3*SingularityFunction(x, 0, -2) + 4*SingularityFunction(x, 2, -1) -␣
,→2*SingularityFunction(x, 2, 2)

+ 2*SingularityFunction(x, 3, 0) + 2*SingularityFunction(x, 3, 2)
>>> b.remove_load(-2, 2, 2, end = 3)
>>> b.load
-3*SingularityFunction(x, 0, -2) + 4*SingularityFunction(x, 2, -1)

second_moment
Second moment of area of the Beam.
shear_force()
Returns a Singularity Function expression which represents the shear force curve
of the Beam object.

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is

5.40. Physics Module 1795

SymPy Documentation, Release 1.3

applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1)
>>> b.apply_load(R2, 30, -1)
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection = [(10, 0), (30, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.shear_force()
-8*SingularityFunction(x, 0, 0) + 6*SingularityFunction(x, 10, 0) +␣
,→120*SingularityFunction(x, 30, -1) + 2*SingularityFunction(x, 30, 0)

slope()
Returns a Singularity Function expression which represents the slope the elastic
curve of the Beam object.

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is
applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1)
>>> b.apply_load(R2, 30, -1)
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection = [(10, 0), (30, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.slope()
(-4*SingularityFunction(x, 0, 2) + 3*SingularityFunction(x, 10, 2)
+ 120*SingularityFunction(x, 30, 1) + SingularityFunction(x, 30, 2) +␣
,→4000/3)/(E*I)

solve_for_reaction_loads(*reactions)
Solves for the reaction forces.

1796 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied

in the clockwise direction at the end of the beam. A pointload of magnitude 8 N is
applied from the top of the beam at the starting point. There are two simple supports
below the beam. One at the end and another one at a distance of 10 meters from
the start. The deflection is restricted at both the supports.
Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols, linsolve, limit
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1) # Reaction force at x = 10
>>> b.apply_load(R2, 30, -1) # Reaction force at x = 30
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection = [(10, 0), (30, 0)]
>>> b.load
R1*SingularityFunction(x, 10, -1) + R2*SingularityFunction(x, 30, -1)
- 8*SingularityFunction(x, 0, -1) + 120*SingularityFunction(x, 30, -2)
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.reaction_loads
{R1: 6, R2: 2}
>>> b.load
-8*SingularityFunction(x, 0, -1) + 6*SingularityFunction(x, 10, -1)
+ 120*SingularityFunction(x, 30, -2) + 2*SingularityFunction(x, 30, -1)

variable
A symbol that can be used as a variable along the length of the beam while repre-
senting load distribution, shear force curve, bending moment, slope curve and the
deflection curve. By default, it is set to Symbol('x'), but this property is mutable.

Examples

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> x, y, z = symbols('x, y, z')
>>> b = Beam(4, E, I)
>>> b.variable
x
>>> b.variable = y
>>> b.variable
y
>>> b = Beam(4, E, I, z)
>>> b.variable
z

class sympy.physics.continuum_mechanics.beam.Beam3D(length, elastic_modulus,

shear_modulus, sec-
ond_moment, area, vari-
able=x)
This class handles loads applied in any direction of a 3D space along with unequal values

5.40. Physics Module 1797

SymPy Documentation, Release 1.3

of Second moment along different axes.

Note: While solving a beam bending problem, a user should choose its own sign con-
vention and should stick to it. The results will automatically follow the chosen sign con-
vention. This class assumes that any kind of distributed load/moment is applied through
out the span of a beam.

References

[R461]

Examples

There is a beam of l meters long. A constant distributed load of magnitude q is applied

along y-axis from start till the end of beam. A constant distributed moment of magnitude
m is also applied along z-axis from start till the end of beam. Beam is fixed at both of its
end. So, deflection of the beam at the both ends is restricted.

>>> from sympy.physics.continuum_mechanics.beam import Beam3D

>>> from sympy import symbols
>>> l, E, G, I, A = symbols('l, E, G, I, A')
>>> b = Beam3D(l, E, G, I, A)
>>> q, m = symbols('q, m')
>>> b.apply_load(q, 0, 0, dir=”y”)
>>> b.apply_moment_load(m, 0, -1, dir=”z”)
>>> b.shear_force()
[0, -q*x, 0]
>>> b.bending_moment()
[0, 0, -m*x + q*x**2/2]
>>> b.bc_slope = [(0, [0, 0, 0]), (l, [0, 0, 0])]
>>> b.bc_deflection = [(0, [0, 0, 0]), (l, [0, 0, 0])]
>>> b.solve_slope_deflection()
>>> b.slope()
[0, 0, l*x*(-l*q + 3*l*(A*G*l**2*q - 2*A*G*l*m + 12*E*I*q)/(2*(A*G*l**2 +␣
,→12*E*I)) + 3*m)/(6*E*I)

+ q*x**3/(6*E*I) + x**2*(-l*(A*G*l**2*q - 2*A*G*l*m + 12*E*I*q)/(2*(A*G*l**2 +␣

,→12*E*I))

- m)/(2*E*I)]
>>> b.deflection()
[0, -l**2*q*x**2/(12*E*I) + l**2*x**2*(A*G*l**2*q - 2*A*G*l*m + 12*E*I*q)/
,→(8*E*I*(A*G*l**2 + 12*E*I))

+ l*m*x**2/(4*E*I) - l*x**3*(A*G*l**2*q - 2*A*G*l*m + 12*E*I*q)/(12*E*I*(A*G*l**2␣

,→+ 12*E*I)) - m*x**3/(6*E*I)

+ q*x**4/(24*E*I) + l*x*(A*G*l**2*q - 2*A*G*l*m + 12*E*I*q)/(2*A*G*(A*G*l**2 +␣

,→12*E*I)) - q*x**2/(2*A*G), 0]

apply_load(value, start, order, dir=’y’)

This method adds up the force load to a particular beam object.
Parameters value : Sympifyable
The magnitude of an applied load.
dir : String

1798 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Axis along which load is applied.

order : Integer
The order of the applied load. - For point loads, order=-1 - For
constant distributed load, order=0 - For ramp loads, order=1 - For
parabolic ramp loads, order=2 - … so on.
apply_moment_load(value, start, order, dir=’y’)
This method adds up the moment loads to a particular beam object.
Parameters value : Sympifyable
The magnitude of an applied moment.
dir : String
Axis along which moment is applied.
order : Integer
The order of the applied load. - For point moments, order=-2 - For
constant distributed moment, order=-1 - For ramp moments, order=0
- For parabolic ramp moments, order=1 - … so on.
area
Cross-sectional area of the Beam.
axial_force()
Returns expression of Axial shear force present inside the Beam object.
bending_moment()
Returns a list of three expressions which represents the bending moment curve of
the Beam object along all three axes.
boundary_conditions
Returns a dictionary of boundary conditions applied on the beam. The dictionary
has two keywords namely slope and deflection. The value of each keyword is a list
of tuple, where each tuple contains loaction and value of a boundary condition in
the format (location, value). Further each value is a list corresponding to slope or
deflection(s) values along three axes at that location.

Examples

There is a beam of length 4 meters. The slope at 0 should be 4 along the x-axis and
0 along others. At the other end of beam, deflection along all the three axes should
be zero.

>>> from sympy.physics.continuum_mechanics.beam import Beam3D

>>> from sympy import symbols
>>> l, E, G, I, A, x = symbols('l, E, G, I, A, x')
>>> b = Beam3D(30, E, G, I, A, x)
>>> b.bc_slope = [(0, (4, 0, 0))]
>>> b.bc_deflection = [(4, [0, 0, 0])]
>>> b.boundary_conditions
{'deflection': [(4, [0, 0, 0])], 'slope': [(0, (4, 0, 0))]}

Here the deflection of the beam should be 0 along all the three axes at 4. Similarly,
the slope of the beam should be 4 along x-axis and 0 along y and z axis at 0.

5.40. Physics Module 1799

SymPy Documentation, Release 1.3

deflection()
Returns a three element list representing deflection curve along all the three axes.
load_vector
Returns a three element list representing the load vector.
moment_load_vector
Returns a three element list representing moment loads on Beam.
second_moment
Second moment of area of the Beam.
shear_force()
Returns a list of three expressions which represents the shear force curve of the
Beam object along all three axes.
shear_modulus
Young’s Modulus of the Beam.
slope()
Returns a three element list representing slope of deflection curve along all the three
axes.
solve_for_reaction_loads(*reaction)
Solves for the reaction forces.

Examples

There is a beam of length 30 meters. It it supported by rollers at of its end. A

constant distributed load of magnitude 8 N is applied from start till its end along
y-axis. Another linear load having slope equal to 9 is applied along z-axis.

>>> from sympy.physics.continuum_mechanics.beam import Beam3D

>>> from sympy import symbols
>>> l, E, G, I, A, x = symbols('l, E, G, I, A, x')
>>> b = Beam3D(30, E, G, I, A, x)
>>> b.apply_load(8, start=0, order=0, dir=”y”)
>>> b.apply_load(9*x, start=0, order=0, dir=”z”)
>>> b.bc_deflection = [(0, [0, 0, 0]), (30, [0, 0, 0])]
>>> R1, R2, R3, R4 = symbols('R1, R2, R3, R4')
>>> b.apply_load(R1, start=0, order=-1, dir=”y”)
>>> b.apply_load(R2, start=30, order=-1, dir=”y”)
>>> b.apply_load(R3, start=0, order=-1, dir=”z”)
>>> b.apply_load(R4, start=30, order=-1, dir=”z”)
>>> b.solve_for_reaction_loads(R1, R2, R3, R4)
>>> b.reaction_loads
{R1: -120, R2: -120, R3: -1350, R4: -2700}

torsional_moment()
Returns expression of Torsional moment present inside the Beam object.

Solving Beam Bending Problems using Singularity Functions

To make this document easier to read, we are going to enable pretty printing.

1800 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy import *

>>> x, y, z = symbols('x y z')
>>> init_printing(use_unicode=True, wrap_line=False)

Beam

A Beam is a structural element that is capable of withstanding load primarily by resisting

against bending. Beams are characterized by their second moment of area, their length and
their elastic modulus.
In Sympy, we can construct a 2D beam objects with the following properties :
• Length
• Elastic Modulus
• Second Moment of Area
• Variable : A symbol that can be used as a variable along the length. By default, this is
set to Symbol(x).
• Boundary Conditions
– bc_slope : Boundary conditions for slope.
– bc_deflection : Boundary conditions for deflection.
• Load Distribution
We have following methods under the beam class:
• apply_load
• solve_for_reaction_loads
• shear_force
• bending_moment
• slope
• deflection

Examples

Let us solve some beam bending problems using this module :

Example 1

A beam of length 9 meters is having a fixed support at the start. A distributed constant load
of 8 kN/m is applied downward from the starting point till 5 meters away from the start. A
clockwise moment of 50 kN-m is applied at 5 meters away from the start of the beam. A
downward point load of 12 kN is applied at the end.

5.40. Physics Module 1801

SymPy Documentation, Release 1.3

\\\\| 8 KN/m
\\\\|_____________
\\\\|| | | | | | | 50 KN-m 12 KN
\\\\|V V V V V V V | |
\\\\|________________|_______________V
\\\\|________________|_______________|
\\\\| :
\\\\|----------------|---------------|
5.0 m 4.0 m

Note: Since a user is free to choose its own sign convention we are considering the upward
forces and clockwise bending moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, M1 = symbols('R1, M1')
>>> b = Beam(9, E, I)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(M1, 0, -2)
>>> b.apply_load(-8, 0, 0, end=5)
>>> b.apply_load(50, 5, -2)
>>> b.apply_load(-12, 9, -1)
>>> b.bc_slope.append((0, 0))
>>> b.bc_deflection.append((0, 0))
>>> b.solve_for_reaction_loads(R1, M1)
>>> b.reaction_loads
{M1 : -258, R1 : 52}
>>> b.load
-2 -1 0 -2 0 -1
- 258⋅<x> + 52⋅<x> - 8⋅<x> + 50⋅<x - 5> + 8⋅<x - 5> - 12⋅<x - 9>
>>> b.shear_force()
-1 0 1 -1 1 0
- 258⋅<x> + 52⋅<x> - 8⋅<x> + 50⋅<x - 5> + 8⋅<x - 5> - 12⋅<x - 9>
>>> b.bending_moment()
0 1 2 0 2 1
- 258⋅<x> + 52⋅<x> - 4⋅<x> + 50⋅<x - 5> + 4⋅<x - 5> - 12⋅<x - 9>
>>> b.slope()
3 3
1 2 4⋅<x> 1 4⋅<x - 5> 2
- 258⋅<x> + 26⋅<x> - ────── + 50⋅<x - 5> + ────────── - 6⋅<x - 9>
3 3
─────────────────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
3 4 4
2 26⋅<x> <x> 2 <x - 5> 3
- 129⋅<x> + ─────── - ──── + 25⋅<x - 5> + ──────── - 2⋅<x - 9>
3 3 3
─────────────────────────────────────────────────────────────────
E⋅I

1802 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Example 2

There is a beam of length 30 meters. A moment of magnitude 120 Nm is applied in the

clockwise direction at the end of the beam. A pointload of magnitude 8 N is applied from the
top of the beam at the starting point. There are two simple supports below the beam. One at
the end and another one at a distance of 10 meters from the start. The deflection is restricted
at both the supports.

|| 8 N 120 Nm
\/______________________________________________|
|_______________________________________________|
/\ /\
|------------|---------------------------------|
10 m 20 m

Note: Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(30, E, I)
>>> b.apply_load(-8, 0, -1)
>>> b.apply_load(R1, 10, -1)
>>> b.apply_load(R2, 30, -1)
>>> b.apply_load(120, 30, -2)
>>> b.bc_deflection.append((10, 0))
>>> b.bc_deflection.append((30, 0))
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.reaction_loads
{R1 : 6, R2 : 2}
>>> b.load
-1 -1 -2 -1
- 8⋅<x> + 6⋅<x - 10> + 120⋅<x - 30> + 2⋅<x - 30>
>>> b.shear_force()
0 0 -1 0
- 8⋅<x> + 6⋅<x - 10> + 120⋅<x - 30> + 2⋅<x - 30>
>>> b.bending_moment()
1 1 0 1
- 8⋅<x> + 6⋅<x - 10> + 120⋅<x - 30> + 2⋅<x - 30>
>>> b.slope()
2 2 1 2 4000
- 4⋅<x> + 3⋅<x - 10> + 120⋅<x - 30> + <x - 30> + ────
3
─────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
3 3
4000⋅x 4⋅<x> 3 2 <x - 30>
────── - ────── + <x - 10> + 60⋅<x - 30> + ───────── - 12000
3 3 3
──────────────────────────────────────────────────────────────
E⋅I

5.40. Physics Module 1803

SymPy Documentation, Release 1.3

Example 3

A beam of length 6 meters is having a roller support at the start and a hinged support at
the end. A clockwise moment of 1.5 kN-m is applied at the mid of the beam. A constant
distributed load of 3 kN/m and a ramp load of 1 kN/m is applied from the mid till the end of
the beam.

ramp load = 1 KN/m

constant load = 3 KN/m
|------------------------|
1.5 KN-m
______________________|________________________
|_______________________________________________|
o | /\
|----------------------|-----------------------|
3.0 m 3.0 m

Note: Using the sign convention of upward forces and clockwise moment being positive.

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b = Beam(6, E, I)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(1.5, 3, -2)
>>> b.apply_load(-3, 3, 0)
>>> b.apply_load(-1, 3, 1)
>>> b.apply_load(R2, 6, -1)
>>> b.bc_deflection.append((0, 0))
>>> b.bc_deflection.append((6, 0))
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.reaction_loads
{R1 : 2.75, R2 : 10.75}
>>> b.load
-1 -2 0 1 -1
2.75⋅<x> + 1.5⋅<x - 3> - 3⋅<x - 3> - <x - 3> + 10.75⋅<x - 6>
>>> b.shear_force()
2
0 -1 1 <x - 3> 0
2.75⋅<x> + 1.5⋅<x - 3> - 3⋅<x - 3> - ──────── + 10.75⋅<x - 6>
2
>>> b.bending_moment()
2 3
1 0 3⋅<x - 3> <x - 3> 1
2.75⋅<x> + 1.5⋅<x - 3> - ────────── - ──────── + 10.75⋅<x - 6>
2 6
>>> b.slope()
3 4
2 1 <x - 3> <x - 3> 2
1.375⋅<x> + 1.5⋅<x - 3> - ──────── - ──────── + 5.375⋅<x - 6> - 15.6
2 24
───────────────────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
(continues on next page)

1804 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

4 5
3 2 <x - 3> <x - 3> ␣
,→ 3
-15.6⋅x + 0.458333333333333⋅<x> + 0.75⋅<x - 3> - ──────── - ──────── + 1.
,→79166666666667⋅<x - 6>

8 120
␣
,→──────────────────────────────────────────────────────────────────────────────────────────────────

E⋅I

Example 4

An overhanging beam of length 8 meters is pinned at 1 meter from starting point and sup-
ported by a roller 1 meter before the other end. It is subjected to a distributed constant load
of 10 KN/m from the starting point till 2 meters away from it. Two pointloads of 20KN and
8KN are applied at 5 meters and 7.5 meters away from the starting point respectively.
---> x
|
v y
10 KN/m
_____________ 20 KN 8 KN
| | | | | | | | |
V V V V V V V V V
_______________________________________________
|_______________________________________________|
/\ O
|-----|------|-----------------|----------|--|--|
1m 1m 3m 2m .5m .5m

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E,I,M,V = symbols('E I M V')
>>> b = Beam(8, E, I)
>>> E,I,R1,R2 = symbols('E I R1 R2')
>>> b.apply_load(R1, 1, -1)
>>> b.apply_load(R2, 7, -1)
>>> b.apply_load(10, 0, 0, end=2)
>>> b.apply_load(20, 5, -1)
>>> b.apply_load(8, 7.5, -1)
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.reaction_loads
{R1 : -26.0, R2 : -22.0}
>>> b.load
0 -1 0 -1 -1 -1
10⋅<x> - 26.0⋅<x - 1> - 10⋅<x - 2> + 20⋅<x - 5> - 22.0⋅<x - 7> + 8⋅<x - 7.5>

>>> b.shear_force()
1 0 1 0 0 0
10⋅<x> - 26.0⋅<x - 1> - 10⋅<x - 2> + 20⋅<x - 5> - 22.0⋅<x - 7> + 8⋅<x - 7.5>

>>> b.bending_moment()
2 1 2 1 1 1
5⋅<x> - 26.0⋅<x - 1> - 5⋅<x - 2> + 20⋅<x - 5> - 22.0⋅<x - 7> + 8⋅<x - 7.5>
(continues on next page)

5.40. Physics Module 1805

SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.bc_deflection = [(1, 0), (7, 0)]

>>> b.slope()
3 3
5⋅<x> 2 5⋅<x - 2> 2 2 2
────── - 13.0⋅<x - 1> - ────────── + 10⋅<x - 5> - 11.0⋅<x - 7> + 4⋅<x - 7.5> + 28.
,→2916666666667

3 3
───────────────────────────────────────────────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
4 4 3 ␣
,→ 3
5⋅<x> 3 5⋅<x - 2> 10⋅<x - 5> ␣
,→ 3 4⋅<x - 7.5>
28.2916666666667⋅x + ────── - 4.33333333333333⋅<x - 1> - ────────── + ─────────── -␣
,→3.66666666666667⋅<x - 7> + ──────────── - 28.7083333333333
12 12 3 ␣
,→ 3
─────────────────────────────────────────────────────────────────────────────────────────────────────
E⋅I

Example 5

A cantilever beam of length 6 meters is under downward distributed constant load with mag-
nitude of 4.0 KN/m from starting point till 2 meters away from it. A ramp load of 1 kN/m
applied from the mid till the end of the beam. A point load of 12KN is also applied in same
direction 4 meters away from start.
---> x .
| . |
v y 12 KN . | |
| . | | |
V . | | | |
\\\\| 4 KN/m . | | | | |
\\\\|___________ . 1 KN/m | |
\\\\|| | | | | | . V V V V V V V
\\\\|V V V V V V |---------------|
\\\\|________________________________
\\\\|________________________________|
\\\\| : : :
\\\\|----------|-----|----|----------|
2.0 m 1m 1m 2.0 m

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E,I,M,V = symbols('E I M V')
>>> b = Beam(6, E, I)
>>> b.apply_load(V, 0, -1)
>>> b.apply_load(M, 0, -2)
>>> b.apply_load(4, 0, 0, end=2)
>>> b.apply_load(12, 4, -1)
>>> b.apply_load(1, 3, 1, end=6)
>>> b.solve_for_reaction_loads(V, M)
(continues on next page)

1806 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.reaction_loads
{M: 157/2, V: -49/2}
>>> b.load
-2 -1
157⋅<x> 49⋅<x> 0 0 1 -1 0 ␣
,→ 1
───────── - ──────── + 4⋅<x> - 4⋅<x - 2> + <x - 3> + 12⋅<x - 4> - <x - 6> - <x -
,→ 6>

2 2
>>> b.shear_force()
-1 0 2 ␣
,→ 2

157⋅<x> 49⋅<x> 1 1 <x - 3> 0 1 <x -␣

,→6>

───────── - ─────── + 4⋅<x> - 4⋅<x - 2> + ──────── + 12⋅<x - 4> - <x - 6> -␣
,→────────

2 2 2 2
>>> b.bending_moment()
0 1 3 2 ␣
,→3

157⋅<x> 49⋅<x> 2 2 <x - 3> 1 <x - 6> <x - 6>

──────── - ─────── + 2⋅<x> - 2⋅<x - 2> + ──────── + 12⋅<x - 4> - ──────── -␣
,→────────

2 2 6 2 6
>>> b.bc_deflection = [(0, 0)]
>>> b.bc_slope = [(0, 0)]
>>> b.slope()
1 2 3 3 4 3 4
157⋅<x> 49⋅<x> 2⋅<x> 2⋅<x - 2> <x - 3> 2 <x - 6> <x - 6>
──────── - ─────── + ────── - ────────── + ──────── + 6⋅<x - 4> - ──────── - ────────
2 4 3 3 24 6 24
──────────────────────────────────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
2 3 4 4 5 4 5
157⋅<x> 49⋅<x> <x> <x - 2> <x - 3> 3 <x - 6> <x - 6>
──────── - ─────── + ──── - ──────── + ──────── + 2⋅<x - 4> - ──────── - ────────
4 12 6 6 120 24 120
──────────────────────────────────────────────────────────────────────────────────
E⋅I

Example 6

An overhanging beam of length 11 meters is subjected to a distributed constant load of 2

KN/m from 2 meters away from the starting point till 6 meters away from it. It is pinned at
the starting point and is resting over a roller 8 meters away from that end. Also a clockwise
moment of 5 KN-m is applied at the overhanging end.

2 KN/m ---> x
_________________ |
| | | | | | | | | v y
V V V V V V V V V 5 KN-m
____________________________________________________|
O____________________________________________________|
(continues on next page)

5.40. Physics Module 1807

SymPy Documentation, Release 1.3

(continued from previous page)

/ \ /\
|--------|----------------|----------|---------------|
2m 4m 2m 3m

>>> R1, R2 = symbols('R1, R2')

>>> E, I = symbols('E, I')
>>> b = Beam(11, E, I)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(2, 2, 0, end=6)
>>> b.apply_load(R2, 8, -1)
>>> b.apply_load(5, 11, -2)
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.reaction_loads
{R1 : -37/8, R2 : -27/8}
>>> b.load
-1 -1
37⋅<x> 0 0 27⋅<x - 8> -2
- ──────── + 2⋅<x - 2> - 2⋅<x - 6> - ──────────── + 5⋅<x - 11>
8 8
>>> b.shear_force()
0 0
37⋅<x> 1 1 27⋅<x - 8> -1
- ─────── + 2⋅<x - 2> - 2⋅<x - 6> - ─────────── + 5⋅<x - 11>
8 8
>>> b.bending_moment()
1 1
37⋅<x> 2 2 27⋅<x - 8> 0
- ─────── + <x - 2> - <x - 6> - ─────────── + 5⋅<x - 11>
8 8
>>> b.bc_deflection = [(0, 0), (8, 0)]
>>> b.slope()
2 3 3 2
37⋅<x> <x - 2> <x - 6> 27⋅<x - 8> 1
- ─────── + ──────── - ──────── - ─────────── + 5⋅<x - 11> + 36
16 3 3 16
────────────────────────────────────────────────────────────────
E⋅I
>>> b.deflection()
3 4 4 3 2
37⋅<x> <x - 2> <x - 6> 9⋅<x - 8> 5⋅<x - 11>
36⋅x - ─────── + ──────── - ──────── - ────────── + ───────────
48 12 12 16 2
───────────────────────────────────────────────────────────────
E⋅I

Example 7

There is a beam of length l, fixed at both ends. A concentrated point load of magnitude F is
applied in downward direction at mid-point of the beam.
^ y
|
---> x
\\\\| F |\\\\
(continues on next page)

1808 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

\\\\| | |\\\\
\\\\| V |\\\\
\\\\|_____________________________________|\\\\
\\\\|_____________________________________|\\\\
\\\\| : |\\\\
\\\\| : |\\\\
\\\\|------------------|------------------|\\\\
l/2 l/2

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I, F = symbols('E I F')
>>> l = symbols('l', positive=True)
>>> b = Beam(l, E, I)
>>> R1,R2 = symbols('R1 R2')
>>> M1, M2 = symbols('M1, M2')
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(M1, 0, -2)
>>> b.apply_load(R2, l, -1)
>>> b.apply_load(M2, l, -2)
>>> b.apply_load(-F, l/2, -1)
>>> b.bc_deflection = [(0, 0),(l, 0)]
>>> b.bc_slope = [(0, 0),(l, 0)]
>>> b.solve_for_reaction_loads(R1, R2, M1, M2)
>>> b.reaction_loads
⎧ -F⋅l F⋅l F F⎫
⎨M1 : ─────, M2 : ───, R1 : ─, R2 : ─⎬
⎩ 8 8 2 2⎭

>>> b.load
-2 -2 -1 -1 -1
F⋅l⋅<x> F⋅l⋅<-l + x> F⋅<x> l F⋅<-l + x>
- ───────── + ────────────── + ─────── - F⋅<- ─ + x> + ────────────
8 8 2 2 2

>>> b.shear_force()
-1 -1 0 0 0
F⋅l⋅<x> F⋅l⋅<-l + x> F⋅<x> l F⋅<-l + x>
- ───────── + ────────────── + ────── - F⋅<- ─ + x> + ───────────
8 8 2 2 2

>>> b.bending_moment()
0 0 1 1 1
F⋅l⋅<x> F⋅l⋅<-l + x> F⋅<x> l F⋅<-l + x>
- ──────── + ───────────── + ────── - F⋅<- ─ + x> + ───────────
8 8 2 2 2

>>> b.slope()
2
l
1 1 2 F⋅<- ─ + x> 2
F⋅l⋅<x> F⋅l⋅<-l + x> F⋅<x> 2 F⋅<-l + x>
- ──────── + ───────────── + ────── - ──────────── + ───────────
8 8 4 2 4
────────────────────────────────────────────────────────────────
E⋅I
(continues on next page)

5.40. Physics Module 1809

SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.deflection()
3
l
2 2 3 F⋅<- ─ + x> 3
F⋅l⋅<x> F⋅l⋅<-l + x> F⋅<x> 2 F⋅<-l + x>
- ──────── + ───────────── + ────── - ──────────── + ───────────
16 16 12 6 12
────────────────────────────────────────────────────────────────
E⋅I

Example 8

There is a beam of length 4*l, having a hinge connector at the middle. It is having a fixed
support at the start and also has two rollers at a distance of l and 4*l from the starting point.
A concentrated point load P is also applied at a distance of 3*l from the starting point.
---> x
\\\\| P |
\\\\| | v y
\\\\| V
\\\\|_____________________ _______________________
\\\\|_____________________O_______________________|
\\\\| /\ : /\
\\\\| oooo : oooo
\\\\|----------|-----------|----------|-----------|
l l l l

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E I')
>>> l = symbols('l', positive=True)
>>> R1, M1, R2, R3, P = symbols('R1 M1 R2 R3 P')
>>> b1 = Beam(2*l, E, I)
>>> b2 = Beam(2*l, E, I)
>>> b = b1.join(b2, ”hinge”)
>>> b.apply_load(M1, 0, -2)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, l, -1)
>>> b.apply_load(R3, 4*l, -1)
>>> b.apply_load(P, 3*l, -1)
>>> b.bc_slope = [(0, 0)]
>>> b.bc_deflection = [(0, 0), (l, 0), (4*l, 0)]
>>> b.solve_for_reaction_loads(M1, R1, R2, R3)
>>> b.reaction_loads
⎧ -P⋅l 3⋅P -5⋅P -P ⎫
⎨M1 : ─────, R1 : ───, R2 : ─────, R3 : ───⎬
⎩ 4 4 4 2 ⎭

>>> b.load
-2 -1 -1 -1
P⋅l⋅<x> 3⋅P⋅<x> 5⋅P⋅<-l + x> -1 P⋅<-4⋅l + x>
- ───────── + ───────── - ────────────── + P⋅<-3⋅l + x> - ──────────────
4 4 4 2
(continues on next page)

1810 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.shear_force()
-1 0 0 0
P⋅l⋅<x> 3⋅P⋅<x> 5⋅P⋅<-l + x> 0 P⋅<-4⋅l + x>
- ───────── + ──────── - ───────────── + P⋅<-3⋅l + x> - ─────────────
4 4 4 2

>>> b.bending_moment()
0 1 1 1
P⋅l⋅<x> 3⋅P⋅<x> 5⋅P⋅<-l + x> 1 P⋅<-4⋅l + x>
- ──────── + ──────── - ───────────── + P⋅<-3⋅l + x> - ─────────────
4 4 4 2

>>> b.slope()
⎛ 2 2 2 2⎞ ⎛ 1 ␣
,→ 2 2 2⎞ ⎛ 1 2 ␣
,→ 2 2⎞
⎜5⋅P⋅l P⋅<-2⋅l + x> P⋅<-3⋅l + x> P⋅<-4⋅l + x> ⎟ 0 ⎜ P⋅l⋅<x> ␣
,→3⋅P⋅<x> 5⋅P⋅<-l + x> P⋅<-2⋅l + x> ⎟ 0 ⎜ P⋅l⋅<x> 3⋅P⋅<x> 5⋅P⋅<-l +␣
,→x> P⋅<-2⋅l + x> ⎟ 0
⎜────── - ───────────── + ───────────── - ─────────────⎟⋅<-2⋅l + x> ⎜- ──────── +␣
,→──────── - ───────────── + ─────────────⎟⋅<x> ⎜- ──────── + ──────── -␣
,→───────────── + ─────────────⎟⋅<-2⋅l + x>

⎝ 48 4 2 4 ⎠ ⎝ 4 ␣
,→ 8 8 4 ⎠ ⎝ 4 8 8 ␣
,→ 4 ⎠
──────────────────────────────────────────────────────────────────── +␣
,→──────────────────────────────────────────────────────────── -␣

,→───────────────────────────────────────────────────────────────────

E⋅I ␣
,→ E⋅I E⋅I
>>> b.deflection()
⎛ 2 3 3 3⎞ ⎛ 2 3 ␣
,→ 3 3⎞ ⎛ 3 2 ␣
,→ 3 3 3⎞
⎜ P⋅l⋅<x> P⋅<x> 5⋅P⋅<-l + x> P⋅<-2⋅l + x> ⎟ 0 ⎜ P⋅l⋅<x> P⋅<x> ␣
,→5⋅P⋅<-l + x> P⋅<-2⋅l + x> ⎟ 0 ⎜7⋅P⋅l 5⋅P⋅l ⋅(-2⋅l + x) P⋅<-2⋅l␣
,→+ x> P⋅<-3⋅l + x> P⋅<-4⋅l + x> ⎟ 0
⎜- ──────── + ────── - ───────────── + ─────────────⎟⋅<x> ⎜- ──────── + ────── -␣
,→───────────── + ─────────────⎟⋅<-2⋅l + x> ⎜────── + ───────────────── -␣
,→───────────── + ───────────── - ─────────────⎟⋅<-2⋅l + x>

⎝ 8 8 24 12 ⎠ ⎝ 8 8 ␣
,→ 24 12 ⎠ ⎝ 24 48 12 ␣
,→ 6 12 ⎠
────────────────────────────────────────────────────────── -␣
,→───────────────────────────────────────────────────────────────── +␣

,→────────────────────────────────────────────────────────────────────────────────────────

E⋅I ␣
,→ E⋅I ␣
,→ E⋅I

5.40. Physics Module 1811

SymPy Documentation, Release 1.3

Example 9

There is a cantilever beam of length 4 meters. For first 2 meters its moment of inertia is
1.5*I and I for the other end. A pointload of magnitude 20 N is applied from the top at its
free end.

---> x
\\\\| |
\\\\| 20 N v y
\\\\|________________ |
\\\\| |_______________V
\\\\| 1.5*I _______I_______|
\\\\|________________|
\\\\| :
\\\\|----------------|---------------|
2.0 m 2.0 m

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> R1, R2 = symbols('R1, R2')
>>> b1 = Beam(2, E, 1.5*I)
>>> b2 = Beam(2, E, I)
>>> b = b1.join(b2, ”fixed”)
>>> b.apply_load(20, 4, -1)
>>> b.apply_load(R1, 0, -1)
>>> b.apply_load(R2, 0, -2)
>>> b.bc_slope = [(0, 0)]
>>> b.bc_deflection = [(0, 0)]
>>> b.solve_for_reaction_loads(R1, R2)
>>> b.load
-2 -1 -1
80⋅<x> - 20⋅<x> + 20⋅<x - 4>
>>> b.shear_force()
-1 0 0
80⋅<x> - 20⋅<x> + 20⋅<x - 4>
>>> b.bending_moment()
0 1 1
80⋅<x> - 20⋅<x> + 20⋅<x - 4>
>>> b.slope()
⎛ 1 2 2 ⎞
⎜80⋅<x> - 10⋅<x> + 10⋅<x - 4> 120 ⎟
⎜─────────────────────────────── - ─── ⎟ ⎛ 1 ␣
,→ 2 2⎞ 0 ⎛ 1 2 2⎞ ␣
,→ 0
⎜ I I 80.0⎟ 0 0.666666666666667⋅⎝80⋅<x> -
,→ 10⋅<x> + 10⋅<x - 4> ⎠⋅<x> 0.666666666666667⋅⎝80⋅<x> - 10⋅<x> + 10⋅<x - 4> ⎠⋅
,→<x - 2>

⎜───────────────────────────────────── + ────⎟⋅<x - 2> +␣

,→──────────────────────────────────────────────────────── -␣

,→────────────────────────────────────────────────────────────

⎝ E E⋅I ⎠ ␣
,→E⋅I E⋅I

1812 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Example 10

A combined beam, with constant flexural rigidity E*I, is formed by joining a Beam of length
2*l to the right of another Beam of length l. The whole beam is fixed at both of its both end.
A point load of magnitude P is also applied from the top at a distance of 2*l from starting
point.
---> x
|
\\\\| P v y |\\\\
\\\\| | |\\\\
\\\\| V |\\\\
\\\\|____________ ________________________|\\\\
\\\\|____________O________________________|\\\\
\\\\| : : |\\\\
\\\\| : : |\\\\
\\\\|------------|------------|-----------|\\\\
l l l

>>> from sympy.physics.continuum_mechanics.beam import Beam

>>> from sympy import symbols
>>> E, I = symbols('E, I')
>>> l = symbols('l', positive=True)
>>> b1 = Beam(l ,E,I)
>>> b2 = Beam(2*l ,E,I)
>>> b = b1.join(b2,”hinge”)
>>> M1, A1, M2, A2, P = symbols('M1 A1 M2 A2 P')
>>> b.apply_load(A1, 0, -1)
>>> b.apply_load(M1, 0 ,-2)
>>> b.apply_load(P, 2*l, -1)
>>> b.apply_load(A2, 3*l, -1)
>>> b.apply_load(M2, 3*l, -2)
>>> b.bc_slope=[(0, 0), (3*l, 0)]
>>> b.bc_deflection=[(0, 0), (3*l, 0)]
>>> b.solve_for_reaction_loads(M1, A1, M2, A2)
>>> b.reaction_loads
⎧ -5⋅P -13⋅P 5⋅P⋅l -4⋅P⋅l ⎫
⎨A1 : ─────, A2 : ──────, M1 : ─────, M2 : ───────⎬
⎩ 18 18 18 9 ⎭

>>> b.load
-2 -2 -1 -1
5⋅P⋅l⋅<x> 4⋅P⋅l⋅<-3⋅l + x> 5⋅P⋅<x> -1 13⋅P⋅<-3⋅l + x>
─────────── - ────────────────── - ───────── + P⋅<-2⋅l + x> - ─────────────────
18 9 18 18

>>> b.shear_force()
-1 -1 0 0
5⋅P⋅l⋅<x> 4⋅P⋅l⋅<-3⋅l + x> 5⋅P⋅<x> 0 13⋅P⋅<-3⋅l + x>
─────────── - ────────────────── - ──────── + P⋅<-2⋅l + x> - ────────────────
18 9 18 18

>>> b.bending_moment()
0 0 1 1
5⋅P⋅l⋅<x> 4⋅P⋅l⋅<-3⋅l + x> 5⋅P⋅<x> 1 13⋅P⋅<-3⋅l + x>
────────── - ───────────────── - ──────── + P⋅<-2⋅l + x> - ────────────────
18 9 18 18
(continues on next page)

5.40. Physics Module 1813

SymPy Documentation, Release 1.3

(continued from previous page)

>>> b.slope()
⎛ 1 2 2⎞ ⎛ 1 2 ␣
,→2⎞ ⎛ 2 1 2 2 ␣
,→ 2⎞
⎜5⋅P⋅l⋅<x> 5⋅P⋅<x> 5⋅P⋅<-l + x> ⎟ 0 ⎜5⋅P⋅l⋅<x> 5⋅P⋅<x> 5⋅P⋅<-l + x>␣
,→⎟ 0 ⎜P⋅l 4⋅P⋅l⋅<-3⋅l + x> 5⋅P⋅<-l + x> P⋅<-2⋅l + x> 13⋅P⋅<-
,→3⋅l + x> ⎟ 0
⎜────────── - ──────── + ─────────────⎟⋅<x> ⎜────────── - ──────── +␣
,→─────────────⎟⋅<-l + x> ⎜──── - ───────────────── - ───────────── +␣
,→───────────── - ────────────────⎟⋅<-l + x>

⎝ 18 36 36 ⎠ ⎝ 18 36 36 ␣
,→⎠ ⎝ 18 9 36 2 36␣
,→ ⎠
──────────────────────────────────────────── -␣
,→───────────────────────────────────────────────── +␣

,→───────────────────────────────────────────────────────────────────────────────────────

E⋅I E⋅I ␣
,→ E⋅I

>>> b.deflection()
⎛ 2 3 3⎞ ⎛ 2 3 ␣
,→3⎞ ⎛ 3 2 2 3 ␣
,→ 3 3⎞
⎜5⋅P⋅l⋅<x> 5⋅P⋅<x> 5⋅P⋅<-l + x> ⎟ 0 ⎜5⋅P⋅l⋅<x> 5⋅P⋅<x> 5⋅P⋅<-l + x>␣
,→⎟ 0 ⎜5⋅P⋅l P⋅l ⋅(-l + x) 2⋅P⋅l⋅<-3⋅l + x> 5⋅P⋅<-l + x> P⋅<-2⋅l␣
,→+ x> 13⋅P⋅<-3⋅l + x> ⎟ 0
⎜────────── - ──────── + ─────────────⎟⋅<x> ⎜────────── - ──────── +␣
,→─────────────⎟⋅<-l + x> ⎜────── + ───────────── - ───────────────── -␣
,→───────────── + ───────────── - ────────────────⎟⋅<-l + x>

⎝ 36 108 108 ⎠ ⎝ 36 108 108 ␣

,→⎠ ⎝ 54 18 9 108 6␣
,→ 108 ⎠
──────────────────────────────────────────── -␣
,→───────────────────────────────────────────────── +␣

,→───────────────────────────────────────────────────────────────────────────────────────────────────

E⋅I E⋅I ␣
,→ E⋅I

5.41 Category Theory Module

5.41.1 Introduction

The category theory module for SymPy will allow manipulating diagrams within a single cat-
egory, including drawing them in TikZ and deciding whether they are commutative or not.
The general reference work this module tries to follow is
[JoyOfCats] J. Adamek, H. Herrlich. G. E. Strecker: Abstract and Concrete
Categories. The Joy of Cats.
The latest version of this book should be available for free download from
katmat.math.uni-bremen.de/acc/acc.pdf

1814 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The module is still in its pre-embryonic stage.

5.41.2 Base Class Reference

This section lists the classes which implement some of the basic notions in category theory:
objects, morphisms, categories, and diagrams.
class sympy.categories.Object
The base class for any kind of object in an abstract category.
While technically any instance of Basic will do, this class is the recommended way to
create abstract objects in abstract categories.
class sympy.categories.Morphism
The base class for any morphism in an abstract category.
In abstract categories, a morphism is an arrow between two category objects. The object
where the arrow starts is called the domain, while the object where the arrow ends is
called the codomain.
Two morphisms between the same pair of objects are considered to be the same mor-
phisms. To distinguish between morphisms between the same objects use NamedMor-
phism (page 1816).
It is prohibited to instantiate this class. Use one of the derived classes instead.
See also:
IdentityMorphism (page 1818), NamedMorphism (page 1816), CompositeMorphism
(page 1817)
codomain
Returns the codomain of the morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> f.codomain
Object(”B”)

compose(other)
Composes self with the supplied morphism.
The order of elements in the composition is the usual order, i.e., to construct g ◦ f
use g.compose(f).

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
(continues on next page)

5.41. Category Theory Module 1815

SymPy Documentation, Release 1.3

(continued from previous page)

>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> g * f
CompositeMorphism((NamedMorphism(Object(”A”), Object(”B”), ”f”),
NamedMorphism(Object(”B”), Object(”C”), ”g”)))
>>> (g * f).domain
Object(”A”)
>>> (g * f).codomain
Object(”C”)

domain
Returns the domain of the morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> f.domain
Object(”A”)

class sympy.categories.NamedMorphism
Represents a morphism which has a name.
Names are used to distinguish between morphisms which have the same domain and
codomain: two named morphisms are equal if they have the same domains, codomains,
and names.
See also:
Morphism (page 1815)

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> f
NamedMorphism(Object(”A”), Object(”B”), ”f”)
>>> f.name
'f'

name
Returns the name of the morphism.

Examples

1816 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> f.name
'f'

class sympy.categories.CompositeMorphism
Represents a morphism which is a composition of other morphisms.
Two composite morphisms are equal if the morphisms they were obtained from (compo-
nents) are the same and were listed in the same order.
The arguments to the constructor for this class should be listed in diagram order: to
obtain the composition g ◦ f from the instances of Morphism (page 1815) g and f use
CompositeMorphism(f, g).

Examples

>>> from sympy.categories import Object, NamedMorphism, CompositeMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> g * f
CompositeMorphism((NamedMorphism(Object(”A”), Object(”B”), ”f”),
NamedMorphism(Object(”B”), Object(”C”), ”g”)))
>>> CompositeMorphism(f, g) == g * f
True

codomain
Returns the codomain of this composite morphism.
The codomain of the composite morphism is the codomain of its last component.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> (g * f).codomain
Object(”C”)

components
Returns the components of this composite morphism.

5.41. Category Theory Module 1817

SymPy Documentation, Release 1.3

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> (g * f).components
(NamedMorphism(Object(”A”), Object(”B”), ”f”),
NamedMorphism(Object(”B”), Object(”C”), ”g”))

domain
Returns the domain of this composite morphism.
The domain of the composite morphism is the domain of its first component.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> (g * f).domain
Object(”A”)

flatten(new_name)
Forgets the composite structure of this morphism.
If new_name is not empty, returns a NamedMorphism (page 1816) with the supplied
name, otherwise returns a Morphism (page 1815). In both cases the domain of the
new morphism is the domain of this composite morphism and the codomain of the
new morphism is the codomain of this composite morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> (g * f).flatten(”h”)
NamedMorphism(Object(”A”), Object(”C”), ”h”)

class sympy.categories.IdentityMorphism
Represents an identity morphism.
An identity morphism is a morphism with equal domain and codomain, which acts as an
identity with respect to composition.
See also:
Morphism (page 1815)

1818 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.categories import Object, NamedMorphism, IdentityMorphism

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> id_A = IdentityMorphism(A)
>>> id_B = IdentityMorphism(B)
>>> f * id_A == f
True
>>> id_B * f == f
True

class sympy.categories.Category
An (abstract) category.
A category [JoyOfCats] is a quadruple K = (O, hom, id, ◦) consisting of
• a (set-theoretical) class O, whose members are called K-objects,
• for each pair (A, B) of K-objects, a set hom(A, B) whose members are called K-
morphisms from A to B,
• for a each K-object A, a morphism id : A → A, called the K-identity of A,
• a composition law ◦ associating with every K-morphisms f : A → B and g : B → C a
K-morphism g ◦ f : A → C, called the composite of f and g.
Composition is associative, K-identities are identities with respect to composition, and
the sets hom(A, B) are pairwise disjoint.
This class knows nothing about its objects and morphisms. Concrete cases of (abstract)
categories should be implemented as classes derived from this one.
Certain instances of Diagram (page 1820) can be asserted to be commutative in a Cate-
gory (page 1819) by supplying the argument commutative_diagrams in the constructor.
See also:
Diagram (page 1820)

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram, Category

>>> from sympy import FiniteSet
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g])
>>> K = Category(”K”, commutative_diagrams=[d])
>>> K.commutative_diagrams == FiniteSet(d)
True

commutative_diagrams
Returns the FiniteSet of diagrams which are known to be commutative in this cat-
egory.

5.41. Category Theory Module 1819

SymPy Documentation, Release 1.3

>>> from sympy.categories import Object, NamedMorphism, Diagram, Category

>>> from sympy import FiniteSet
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g])
>>> K = Category(”K”, commutative_diagrams=[d])
>>> K.commutative_diagrams == FiniteSet(d)
True

name
Returns the name of this category.

Examples

>>> from sympy.categories import Category

>>> K = Category(”K”)
>>> K.name
'K'

objects
Returns the class of objects of this category.

Examples

>>> from sympy.categories import Object, Category

>>> from sympy import FiniteSet
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> K = Category(”K”, FiniteSet(A, B))
>>> K.objects
Class({Object(”A”), Object(”B”)})

class sympy.categories.Diagram
Represents a diagram in a certain category.
Informally, a diagram is a collection of objects of a category and certain morphisms
between them. A diagram is still a monoid with respect to morphism composition; i.e.,
identity morphisms, as well as all composites of morphisms included in the diagram
belong to the diagram. For a more formal approach to this notion see [Pare1970].
The components of composite morphisms are also added to the diagram. No properties
are assigned to such morphisms by default.
A commutative diagram is often accompanied by a statement of the following kind: “if
such morphisms with such properties exist, then such morphisms which such proper-
ties exist and the diagram is commutative”. To represent this, an instance of Diagram
(page 1820) includes a collection of morphisms which are the premises and another col-
lection of conclusions. premises and conclusions associate morphisms belonging to
the corresponding categories with the FiniteSet’s of their properties.

1820 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The set of properties of a composite morphism is the intersection of the sets of properties
of its components. The domain and codomain of a conclusion morphism should be among
the domains and codomains of the morphisms listed as the premises of a diagram.
No checks are carried out of whether the supplied object and morphisms do belong to
one and the same category.

References

[Pare1970] B. Pareigis: Categories and functors. Academic Press, 1970.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy import FiniteSet, pprint, default_sort_key
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g])
>>> premises_keys = sorted(d.premises.keys(), key=default_sort_key)
>>> pprint(premises_keys, use_unicode=False)
[g*f:A-->C, id:A-->A, id:B-->B, id:C-->C, f:A-->B, g:B-->C]
>>> pprint(d.premises, use_unicode=False)
{g*f:A-->C: EmptySet(), id:A-->A: EmptySet(), id:B-->B: EmptySet(), id:C-->C:
EmptySet(), f:A-->B: EmptySet(), g:B-->C: EmptySet()}
>>> d = Diagram([f, g], {g * f: ”unique”})
>>> pprint(d.conclusions)
{g*f:A-->C: {unique}}

conclusions
Returns the conclusions of this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import IdentityMorphism, Diagram
>>> from sympy import FiniteSet
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g])
>>> IdentityMorphism(A) in d.premises.keys()
True
>>> g * f in d.premises.keys()
True
>>> d = Diagram([f, g], {g * f: ”unique”})
>>> d.conclusions[g * f] == FiniteSet(”unique”)
True

5.41. Category Theory Module 1821

SymPy Documentation, Release 1.3

hom(A, B)
Returns a 2-tuple of sets of morphisms between objects A and B: one set of mor-
phisms listed as premises, and the other set of morphisms listed as conclusions.
See also:
Object (page 1815), Morphism (page 1815)

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy import pretty
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g], {g * f: ”unique”})
>>> print(pretty(d.hom(A, C), use_unicode=False))
({g*f:A-->C}, {g*f:A-->C})

is_subdiagram(diagram)
Checks whether diagram is a subdiagram of self. Diagram D′ is a subdiagram of D
if all premises (conclusions) of D′ are contained in the premises (conclusions) of D.
The morphisms contained both in D′ and D should have the same properties for D′
to be a subdiagram of D.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g], {g * f: ”unique”})
>>> d1 = Diagram([f])
>>> d.is_subdiagram(d1)
True
>>> d1.is_subdiagram(d)
False

objects
Returns the FiniteSet of objects that appear in this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
(continues on next page)

1822 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g])
>>> d.objects
{Object(”A”), Object(”B”), Object(”C”)}

premises
Returns the premises of this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import IdentityMorphism, Diagram
>>> from sympy import pretty
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> f = NamedMorphism(A, B, ”f”)
>>> id_A = IdentityMorphism(A)
>>> id_B = IdentityMorphism(B)
>>> d = Diagram([f])
>>> print(pretty(d.premises, use_unicode=False))
{id:A-->A: EmptySet(), id:B-->B: EmptySet(), f:A-->B: EmptySet()}

subdiagram_from_objects(objects)
If objects is a subset of the objects of self, returns a diagram which has as premises
all those premises of self which have a domains and codomains in objects, likewise
for conclusions. Properties are preserved.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy import FiniteSet
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g], {f: ”unique”, g*f: ”veryunique”})
>>> d1 = d.subdiagram_from_objects(FiniteSet(A, B))
>>> d1 == Diagram([f], {f: ”unique”})
True

5.41.3 Diagram Drawing

This section lists the classes which allow automatic drawing of diagrams.
class sympy.categories.diagram_drawing.DiagramGrid(diagram, groups=None,
**hints)
Constructs and holds the fitting of the diagram into a grid.
The mission of this class is to analyse the structure of the supplied diagram and to place
its objects on a grid such that, when the objects and the morphisms are actually drawn,
the diagram would be “readable”, in the sense that there will not be many intersections of

5.41. Category Theory Module 1823

SymPy Documentation, Release 1.3

moprhisms. This class does not perform any actual drawing. It does strive nevertheless
to offer sufficient metadata to draw a diagram.
Consider the following simple diagram.

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import Diagram, DiagramGrid
>>> from sympy import pprint
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g])

The simplest way to have a diagram laid out is the following:

>>> grid = DiagramGrid(diagram)

>>> (grid.width, grid.height)
(2, 2)
>>> pprint(grid)
A B
<BLANKLINE>
C

Sometimes one sees the diagram as consisting of logical groups. One can advise Dia-
gramGrid as to such groups by employing the groups keyword argument.
Consider the following diagram:

>>> D = Object(”D”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> h = NamedMorphism(D, A, ”h”)
>>> k = NamedMorphism(D, B, ”k”)
>>> diagram = Diagram([f, g, h, k])

Lay it out with generic layout:

>>> grid = DiagramGrid(diagram)

>>> pprint(grid)
A B D
<BLANKLINE>
C

Now, we can group the objects A and D to have them near one another:

>>> grid = DiagramGrid(diagram, groups=[[A, D], B, C])

>>> pprint(grid)
B C
<BLANKLINE>
A D

Note how the positioning of the other objects changes.

Further indications can be supplied to the constructor of DiagramGrid (page 1823) us-
ing keyword arguments. The currently supported hints are explained in the following
paragraphs.

1824 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

DiagramGrid (page 1823) does not automatically guess which layout would suit the sup-
plied diagram better. Consider, for example, the following linear diagram:

>>> E = Object(”E”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> h = NamedMorphism(C, D, ”h”)
>>> i = NamedMorphism(D, E, ”i”)
>>> diagram = Diagram([f, g, h, i])

When laid out with the generic layout, it does not get to look linear:

>>> grid = DiagramGrid(diagram)

>>> pprint(grid)
A B
<BLANKLINE>
C D
<BLANKLINE>
E

To get it laid out in a line, use layout=”sequential”:

>>> grid = DiagramGrid(diagram, layout=”sequential”)

>>> pprint(grid)
A B C D E

One may sometimes need to transpose the resulting layout. While this can always be
done by hand, DiagramGrid (page 1823) provides a hint for that purpose:

>>> grid = DiagramGrid(diagram, layout=”sequential”, transpose=True)

>>> pprint(grid)
A
<BLANKLINE>
B
<BLANKLINE>
C
<BLANKLINE>
D
<BLANKLINE>
E

Separate hints can also be provided for each group. For an example, refer to tests/
test_drawing.py, and see the different ways in which the five lemma [FiveLemma] can
be laid out.
See also:
Diagram

References

[FiveLemma] http://en.wikipedia.org/wiki/Five_lemma
height
Returns the number of rows in this diagram layout.

5.41. Category Theory Module 1825

SymPy Documentation, Release 1.3

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.height
2

morphisms
Returns those morphisms (and their properties) which are sufficiently meaningful
to be drawn.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.morphisms
{NamedMorphism(Object(”A”), Object(”B”), ”f”): EmptySet(),
NamedMorphism(Object(”B”), Object(”C”), ”g”): EmptySet()}

width
Returns the number of columns in this diagram layout.

Examples

>>> from sympy.categories import Object, NamedMorphism

>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.width
2

1826 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

class sympy.categories.diagram_drawing.ArrowStringDescription(unit, curv-

ing, curv-
ing_amount,
looping_start,
looping_end,
horizon-
tal_direction,
verti-
cal_direction,
la-
bel_position,
label)
Stores the information necessary for producing an Xy-pic description of an arrow.
The principal goal of this class is to abstract away the string representation of an arrow
and to also provide the functionality to produce the actual Xy-pic string.
unit sets the unit which will be used to specify the amount of curving and other dis-
tances. horizontal_direction should be a string of ”r” or ”l” specifying the horizontal
offset of the target cell of the arrow relatively to the current one. vertical_direction
should specify the vertical offset using a series of either ”d” or ”u”. label_position
should be either ”^”, ”_”, or ”|” to specify that the label should be positioned above the
arrow, below the arrow or just over the arrow, in a break. Note that the notions “above”
and “below” are relative to arrow direction. label stores the morphism label.
This works as follows (disregard the yet unexplained arguments):

>>> from sympy.categories.diagram_drawing import ArrowStringDescription

>>> astr = ArrowStringDescription(
... unit=”mm”, curving=None, curving_amount=None,
... looping_start=None, looping_end=None, horizontal_direction=”d”,
... vertical_direction=”r”, label_position=”_”, label=”f”)
>>> print(str(astr))
\ar[dr]_{f}

curving should be one of ”^”, ”_” to specify in which direction the arrow is going to
curve. curving_amount is a number describing how many unit’s the morphism is going
to curve:

>>> astr = ArrowStringDescription(

... unit=”mm”, curving=”^”, curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction=”d”,
... vertical_direction=”r”, label_position=”_”, label=”f”)
>>> print(str(astr))
\ar@/^12mm/[dr]_{f}

looping_start and looping_end are currently only used for loop morphisms, those
which have the same domain and codomain. These two attributes should store a valid
Xy-pic direction and specify, correspondingly, the direction the arrow gets out into and
the direction the arrow gets back from:

>>> astr = ArrowStringDescription(

... unit=”mm”, curving=None, curving_amount=None,
... looping_start=”u”, looping_end=”l”, horizontal_direction=””,
... vertical_direction=””, label_position=”_”, label=”f”)
>>> print(str(astr))
\ar@(u,l)[]_{f}

5.41. Category Theory Module 1827

SymPy Documentation, Release 1.3

label_displacement controls how far the arrow label is from the ends of the arrow. For
example, to position the arrow label near the arrow head, use “>”:

>>> astr = ArrowStringDescription(

... unit=”mm”, curving=”^”, curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction=”d”,
... vertical_direction=”r”, label_position=”_”, label=”f”)
>>> astr.label_displacement = ”>”
>>> print(str(astr))
\ar@/^12mm/[dr]_>{f}

Finally, arrow_style is used to specify the arrow style. To get a dashed arrow, for ex-
ample, use “{–>}” as arrow style:

>>> astr = ArrowStringDescription(

... unit=”mm”, curving=”^”, curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction=”d”,
... vertical_direction=”r”, label_position=”_”, label=”f”)
>>> astr.arrow_style = ”{-->}”
>>> print(str(astr))
\ar@/^12mm/@{-->}[dr]_{f}

See also:
XypicDiagramDrawer (page 1828)

Notes

Instances of ArrowStringDescription (page 1826) will be constructed by XypicDia-

gramDrawer (page 1828) and provided for further use in formatters. The user is not
expected to construct instances of ArrowStringDescription (page 1826) themselves.
To be able to properly utilise this class, the reader is encouraged to checkout the Xy-pic
user guide, available at [Xypic].

References

[Xypic] http://xy-pic.sourceforge.net/
class sympy.categories.diagram_drawing.XypicDiagramDrawer
Given a Diagram and the corresponding DiagramGrid (page 1823), produces the Xy-pic
representation of the diagram.
The most important method in this class is draw. Consider the following triangle dia-
gram:

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy.categories import DiagramGrid, XypicDiagramDrawer
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g], {g * f: ”unique”})

To draw this diagram, its objects need to be laid out with a DiagramGrid (page 1823):

1828 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> grid = DiagramGrid(diagram)

Finally, the drawing:

>>> drawer = XypicDiagramDrawer()

>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

For further details see the docstring of this method.

To control the appearance of the arrows, formatters are used. The dictionary ar-
row_formatters maps morphisms to formatter functions. A formatter is accepts an Ar-
rowStringDescription (page 1826) and is allowed to modify any of the arrow properties
exposed thereby. For example, to have all morphisms with the property unique appear
as dashed arrows, and to have their names prepended with ∃!, the following should be
done:

>>> def formatter(astr):

... astr.label = ”\exists !” + astr.label
... astr.arrow_style = ”{-->}”
>>> drawer.arrow_formatters[”unique”] = formatter
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar@{-->}[d]_{\exists !g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

To modify the appearance of all arrows in the diagram, set default_arrow_formatter.

For example, to place all morphism labels a little bit farther from the arrow head so that
they look more centred, do as follows:

>>> def default_formatter(astr):

... astr.label_displacement = ”(0.45)”
>>> drawer.default_arrow_formatter = default_formatter
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar@{-->}[d]_(0.45){\exists !g\circ f} \ar[r]^(0.45){f} & B \ar[ld]^(0.45){g} \\
C &
}

In some diagrams some morphisms are drawn as curved arrows. Consider the following
diagram:

>>> D = Object(”D”)
>>> E = Object(”E”)
>>> h = NamedMorphism(D, A, ”h”)
>>> k = NamedMorphism(D, B, ”k”)
>>> diagram = Diagram([f, g, h, k])
>>> grid = DiagramGrid(diagram)
>>> drawer = XypicDiagramDrawer()
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_3mm/[ll]_{h} \\
(continues on next page)

5.41. Category Theory Module 1829

SymPy Documentation, Release 1.3

(continued from previous page)

& C &
}

To control how far the morphisms are curved by default, one can use the unit and de-
fault_curving_amount attributes:

>>> drawer.unit = ”cm”

>>> drawer.default_curving_amount = 1
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_1cm/[ll]_{h} \\
& C &
}

In some diagrams, there are multiple curved morphisms between the same two objects.
To control by how much the curving changes between two such successive morphisms,
use default_curving_step:

>>> drawer.default_curving_step = 1
>>> h1 = NamedMorphism(A, D, ”h1”)
>>> diagram = Diagram([f, g, h, k, h1])
>>> grid = DiagramGrid(diagram)
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} \ar@/^1cm/[rr]^{h_{1}} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_2cm/[ll]_
,→{h} \\

& C &
}

The default value of default_curving_step is 4 units.

See also:
draw (page 1830), ArrowStringDescription (page 1826)
draw(diagram, grid, masked=None, diagram_format=”)
Returns the Xy-pic representation of diagram laid out in grid.
Consider the following simple triangle diagram.

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy.categories import DiagramGrid, XypicDiagramDrawer
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g], {g * f: ”unique”})

To draw this diagram, its objects need to be laid out with a DiagramGrid (page 1823):

>>> grid = DiagramGrid(diagram)

Finally, the drawing:

>>> drawer = XypicDiagramDrawer()

>>> print(drawer.draw(diagram, grid))
(continues on next page)

1830 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

The argument masked can be used to skip morphisms in the presentation of the
diagram:

>>> print(drawer.draw(diagram, grid, masked=[g * f]))

\xymatrix{
A \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

Finally, the diagram_format argument can be used to specify the format string of
the diagram. For example, to increase the spacing by 1 cm, proceeding as follows:

>>> print(drawer.draw(diagram, grid, diagram_format=”@+1cm”))

\xymatrix@+1cm{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

sympy.categories.diagram_drawing.xypic_draw_diagram(diagram, masked=None,
diagram_format=”,
groups=None, **hints)
Provides a shortcut combining DiagramGrid (page 1823) and XypicDiagramDrawer
(page 1828). Returns an Xy-pic presentation of diagram. The argument masked is a
list of morphisms which will be not be drawn. The argument diagram_format is the
format string inserted after “xymatrix”. groups should be a set of logical groups. The
hints will be passed directly to the constructor of DiagramGrid (page 1823).
For more information about the arguments, see the docstrings of DiagramGrid
(page 1823) and XypicDiagramDrawer.draw.
See also:
XypicDiagramDrawer (page 1828), DiagramGrid (page 1823)

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy.categories import xypic_draw_diagram
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> diagram = Diagram([f, g], {g * f: ”unique”})
>>> print(xypic_draw_diagram(diagram))
\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

5.41. Category Theory Module 1831

SymPy Documentation, Release 1.3

sympy.categories.diagram_drawing.preview_diagram(diagram, masked=None,
diagram_format=”,
groups=None, output=’png’,
viewer=None, euler=True,
**hints)
Combines the functionality of xypic_draw_diagram and sympy.printing.preview.
The arguments masked, diagram_format, groups, and hints are passed to
xypic_draw_diagram, while output, viewer, and ``euler are passed to preview.
See also:
xypic_diagram_drawer

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram

>>> from sympy.categories import preview_diagram
>>> A = Object(”A”)
>>> B = Object(”B”)
>>> C = Object(”C”)
>>> f = NamedMorphism(A, B, ”f”)
>>> g = NamedMorphism(B, C, ”g”)
>>> d = Diagram([f, g], {g * f: ”unique”})
>>> preview_diagram(d)

5.42 Differential Geometry Module

5.42.1 Introduction

5.42.2 Base Class Reference

class sympy.diffgeom.Manifold
Object representing a mathematical manifold.
The only role that this object plays is to keep a list of all patches defined on the manifold.
It does not provide any means to study the topological characteristics of the manifold
that it represents.
class sympy.diffgeom.Patch
Object representing a patch on a manifold.
On a manifold one can have many patches that do not always include the whole manifold.
On these patches coordinate charts can be defined that permit the parameterization of
any point on the patch in terms of a tuple of real numbers (the coordinates).
This object serves as a container/parent for all coordinate system charts that can be
defined on the patch it represents.

Examples

Define a Manifold and a Patch on that Manifold:

1832 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.diffgeom import Manifold, Patch

>>> m = Manifold('M', 3)
>>> p = Patch('P', m)
>>> p in m.patches
True

class sympy.diffgeom.CoordSystem
Contains all coordinate transformation logic.

Examples

Define a Manifold and a Patch, and then define two coord systems on that patch:

>>> from sympy import symbols, sin, cos, pi

>>> from sympy.diffgeom import Manifold, Patch, CoordSystem
>>> from sympy.simplify import simplify
>>> r, theta = symbols('r, theta')
>>> m = Manifold('M', 2)
>>> patch = Patch('P', m)
>>> rect = CoordSystem('rect', patch)
>>> polar = CoordSystem('polar', patch)
>>> rect in patch.coord_systems
True

Connect the coordinate systems. An inverse transformation is automatically found by

solve when possible:

>>> polar.connect_to(rect, [r, theta], [r*cos(theta), r*sin(theta)])

>>> polar.coord_tuple_transform_to(rect, [0, 2])
Matrix([
[0],
[0]])
>>> polar.coord_tuple_transform_to(rect, [2, pi/2])
Matrix([
[0],
[2]])
>>> rect.coord_tuple_transform_to(polar, [1, 1]).applyfunc(simplify)
Matrix([
[sqrt(2)],
[ pi/4]])

Calculate the jacobian of the polar to cartesian transformation:

>>> polar.jacobian(rect, [r, theta])

Matrix([
[cos(theta), -r*sin(theta)],
[sin(theta), r*cos(theta)]])

Define a point using coordinates in one of the coordinate systems:

>>> p = polar.point([1, 3*pi/4])

>>> rect.point_to_coords(p)
Matrix([
[-sqrt(2)/2],
[ sqrt(2)/2]])

5.42. Differential Geometry Module 1833

SymPy Documentation, Release 1.3

Define a basis scalar field (i.e. a coordinate function), that takes a point and returns its
coordinates. It is an instance of BaseScalarField.

>>> rect.coord_function(0)(p)
-sqrt(2)/2
>>> rect.coord_function(1)(p)
sqrt(2)/2

Define a basis vector field (i.e. a unit vector field along the coordinate line). Vectors are
also differential operators on scalar fields. It is an instance of BaseVectorField.

>>> v_x = rect.base_vector(0)

>>> x = rect.coord_function(0)
>>> v_x(x)
1
>>> v_x(v_x(x))
0

Define a basis oneform field:

>>> dx = rect.base_oneform(0)
>>> dx(v_x)
1

If you provide a list of names the fields will print nicely: - without provided names:

>>> x, v_x, dx
(rect_0, e_rect_0, drect_0)

• with provided names

>>> rect = CoordSystem('rect', patch, ['x', 'y'])

>>> rect.coord_function(0), rect.base_vector(0), rect.base_oneform(0)
(x, e_x, dx)

base_oneform(coord_index)
Return a basis 1-form field.
The basis one-form field for this coordinate system. It is also an operator on vector
fields.
See the docstring of CoordSystem for examples.
base_oneforms()
Returns a list of all base oneforms.
For more details see the base_oneform method of this class.
base_vector(coord_index)
Return a basis vector field.
The basis vector field for this coordinate system. It is also an operator on scalar
fields.
See the docstring of CoordSystem for examples.
base_vectors()
Returns a list of all base vectors.
For more details see the base_vector method of this class.

1834 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

connect_to(to_sys, from_coords, to_exprs, inverse=True, fill_in_gaps=False)

Register the transformation used to switch to another coordinate system.
Parameters to_sys
another instance of CoordSystem
from_coords
list of symbols in terms of which to_exprs is given
to_exprs
list of the expressions of the new coordinate tuple
inverse
try to deduce and register the inverse transformation
fill_in_gaps
try to deduce other transformation that are made possible by compos-
ing the present transformation with other already registered transfor-
mation
coord_function(coord_index)
Return a BaseScalarField that takes a point and returns one of the coords.
Takes a point and returns its coordinate in this coordinate system.
See the docstring of CoordSystem for examples.
coord_functions()
Returns a list of all coordinate functions.
For more details see the coord_function method of this class.
coord_tuple_transform_to(to_sys, coords)
Transform coords to coord system to_sys.
See the docstring of CoordSystem for examples.
jacobian(to_sys, coords)
Return the jacobian matrix of a transformation.
point(coords)
Create a Point with coordinates given in this coord system.
See the docstring of CoordSystem for examples.
point_to_coords(point)
Calculate the coordinates of a point in this coord system.
See the docstring of CoordSystem for examples.
class sympy.diffgeom.Point(coord_sys, coords)
Point in a Manifold object.
To define a point you must supply coordinates and a coordinate system.
The usage of this object after its definition is independent of the coordinate system that
was used in order to define it, however due to limitations in the simplification routines
you can arrive at complicated expressions if you use inappropriate coordinate systems.

5.42. Differential Geometry Module 1835

SymPy Documentation, Release 1.3

Examples

Define the boilerplate Manifold, Patch and coordinate systems:

>>> from sympy import symbols, sin, cos, pi
>>> from sympy.diffgeom import (
... Manifold, Patch, CoordSystem, Point)
>>> r, theta = symbols('r, theta')
>>> m = Manifold('M', 2)
>>> p = Patch('P', m)
>>> rect = CoordSystem('rect', p)
>>> polar = CoordSystem('polar', p)
>>> polar.connect_to(rect, [r, theta], [r*cos(theta), r*sin(theta)])

Define a point using coordinates from one of the coordinate systems:

>>> p = Point(polar, [r, 3*pi/4])
>>> p.coords()
Matrix([
[ r],
[3*pi/4]])
>>> p.coords(rect)
Matrix([
[-sqrt(2)*r/2],
[ sqrt(2)*r/2]])

coords(to_sys=None)
Coordinates of the point in a given coordinate system.
If to_sys is None it returns the coordinates in the system in which the point was
defined.
class sympy.diffgeom.BaseScalarField
Base Scalar Field over a Manifold for a given Coordinate System.
A scalar field takes a point as an argument and returns a scalar.
A base scalar field of a coordinate system takes a point and returns one of the coordinates
of that point in the coordinate system in question.
To define a scalar field you need to choose the coordinate system and the index of the
coordinate.
The use of the scalar field after its definition is independent of the coordinate system in
which it was defined, however due to limitations in the simplification routines you may
arrive at more complicated expression if you use unappropriate coordinate systems.
You can build complicated scalar fields by just building up SymPy expressions containing
BaseScalarField instances.

Examples

Define boilerplate Manifold, Patch and coordinate systems:

>>> from sympy import symbols, sin, cos, pi, Function
>>> from sympy.diffgeom import (
... Manifold, Patch, CoordSystem, Point, BaseScalarField)
>>> r0, theta0 = symbols('r0, theta0')
(continues on next page)

1836 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> m = Manifold('M', 2)
>>> p = Patch('P', m)
>>> rect = CoordSystem('rect', p)
>>> polar = CoordSystem('polar', p)
>>> polar.connect_to(rect, [r0, theta0], [r0*cos(theta0), r0*sin(theta0)])

Point to be used as an argument for the filed:

>>> point = polar.point([r0, 0])

Examples of fields:

>>> fx = BaseScalarField(rect, 0)
>>> fy = BaseScalarField(rect, 1)
>>> (fx**2+fy**2).rcall(point)
r0**2

>>> g = Function('g')
>>> ftheta = BaseScalarField(polar, 1)
>>> fg = g(ftheta-pi)
>>> fg.rcall(point)
g(-pi)

class sympy.diffgeom.BaseVectorField
Vector Field over a Manifold.
A vector field is an operator taking a scalar field and returning a directional derivative
(which is also a scalar field).
A base vector field is the same type of operator, however the derivation is specifically
done with respect to a chosen coordinate.
To define a base vector field you need to choose the coordinate system and the index of
the coordinate.
The use of the vector field after its definition is independent of the coordinate system in
which it was defined, however due to limitations in the simplification routines you may
arrive at more complicated expression if you use unappropriate coordinate systems.

Examples

Use the predefined R2 manifold, setup some boilerplate.

>>> from sympy import symbols, pi, Function

>>> from sympy.diffgeom.rn import R2, R2_p, R2_r
>>> from sympy.diffgeom import BaseVectorField
>>> from sympy import pprint
>>> x0, y0, r0, theta0 = symbols('x0, y0, r0, theta0')

Points to be used as arguments for the field:

>>> point_p = R2_p.point([r0, theta0])

>>> point_r = R2_r.point([x0, y0])

Scalar field to operate on:

5.42. Differential Geometry Module 1837

SymPy Documentation, Release 1.3

>>> g = Function('g')
>>> s_field = g(R2.x, R2.y)
>>> s_field.rcall(point_r)
g(x0, y0)
>>> s_field.rcall(point_p)
g(r0*cos(theta0), r0*sin(theta0))

Vector field:

>>> v = BaseVectorField(R2_r, 1)
>>> pprint(v(s_field))
/ d \|
|-----(g(x, xi_2))||
\dxi_2 /|xi_2=y
>>> pprint(v(s_field).rcall(point_r).doit())
d
---(g(x0, y0))
dy0
>>> pprint(v(s_field).rcall(point_p).doit())
/ d \|
|-----(g(r0*cos(theta0), xi_2))||
\dxi_2 /|xi_2=r0*sin(theta0)

class sympy.diffgeom.Commutator(v1, v2)

Commutator of two vector fields.
The commutator of two vector fields v1 and v2 is defined as the vector field [v1 , v2 ] that
evaluated on each scalar field f is equal to v1 (v2 (f )) − v2 (v1 (f )).

Examples

Use the predefined R2 manifold, setup some boilerplate.

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import Commutator
>>> from sympy import pprint
>>> from sympy.simplify import simplify

Vector fields:

>>> e_x, e_y, e_r = R2.e_x, R2.e_y, R2.e_r

>>> c_xy = Commutator(e_x, e_y)
>>> c_xr = Commutator(e_x, e_r)
>>> c_xy
0

Unfortunately, the current code is not able to compute everything:

>>> c_xr
Commutator(e_x, e_r)

>>> simplify(c_xr(R2.y**2).doit())
-2*y**2*cos(theta)/(x**2 + y**2)

class sympy.diffgeom.Differential(form_field)
Return the differential (exterior derivative) of a form field.

1838 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The differential of a form (i.e. the exterior derivative) has a complicated definition in the
general case.
The differential df of the 0-form f is defined for any vector field v as df (v) = v(f ).

Examples

Use the predefined R2 manifold, setup some boilerplate.

>>> from sympy import Function
>>> from sympy.diffgeom.rn import R2
>>> from sympy.diffgeom import Differential
>>> from sympy import pprint

Scalar field (0-forms):

>>> g = Function('g')
>>> s_field = g(R2.x, R2.y)

Vector fields:
>>> e_x, e_y, = R2.e_x, R2.e_y

Differentials:
>>> dg = Differential(s_field)
>>> dg
d(g(x, y))
>>> pprint(dg(e_x))
/ d \|
|-----(g(xi_1, y))||
\dxi_1 /|xi_1=x
>>> pprint(dg(e_y))
/ d \|
|-----(g(x, xi_2))||
\dxi_2 /|xi_2=y

Applying the exterior derivative operator twice always results in:

>>> Differential(dg)
0

class sympy.diffgeom.TensorProduct(*args)
Tensor product of forms.
The tensor product permits the creation of multilinear functionals (i.e. higher order
tensors) out of lower order fields (e.g. 1-forms and vector fields). However, the higher
tensors thus created lack the interesting features provided by the other type of product,
the wedge product, namely they are not antisymmetric and hence are not form fields.

Examples

Use the predefined R2 manifold, setup some boilerplate.

>>> from sympy.diffgeom.rn import R2
>>> from sympy.diffgeom import TensorProduct

5.42. Differential Geometry Module 1839

SymPy Documentation, Release 1.3

>>> TensorProduct(R2.dx, R2.dy)(R2.e_x, R2.e_y)

1
>>> TensorProduct(R2.dx, R2.dy)(R2.e_y, R2.e_x)
0
>>> TensorProduct(R2.dx, R2.x*R2.dy)(R2.x*R2.e_x, R2.e_y)
x**2
>>> TensorProduct(R2.e_x, R2.e_y)(R2.x**2, R2.y**2)
4*x*y
>>> TensorProduct(R2.e_y, R2.dx)(R2.y)
dx

You can nest tensor products.

>>> tp1 = TensorProduct(R2.dx, R2.dy)

>>> TensorProduct(tp1, R2.dx)(R2.e_x, R2.e_y, R2.e_x)
1

You can make partial contraction for instance when ‘raising an index’. Putting None in
the second argument of rcall means that the respective position in the tensor product
is left as it is.

>>> TP = TensorProduct
>>> metric = TP(R2.dx, R2.dx) + 3*TP(R2.dy, R2.dy)
>>> metric.rcall(R2.e_y, None)
3*dy

Or automatically pad the args with None without specifying them.

>>> metric.rcall(R2.e_y)
3*dy

class sympy.diffgeom.WedgeProduct(*args)
Wedge product of forms.
In the context of integration only completely antisymmetric forms make sense. The
wedge product permits the creation of such forms.

Examples

Use the predefined R2 manifold, setup some boilerplate.

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import WedgeProduct

>>> WedgeProduct(R2.dx, R2.dy)(R2.e_x, R2.e_y)

1
>>> WedgeProduct(R2.dx, R2.dy)(R2.e_y, R2.e_x)
-1
>>> WedgeProduct(R2.dx, R2.x*R2.dy)(R2.x*R2.e_x, R2.e_y)
x**2
>>> WedgeProduct(R2.e_x,R2.e_y)(R2.y,None)
-e_x

You can nest wedge products.

1840 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> wp1 = WedgeProduct(R2.dx, R2.dy)

>>> WedgeProduct(wp1, R2.dx)(R2.e_x, R2.e_y, R2.e_x)
0

class sympy.diffgeom.LieDerivative(v_field, expr)

Lie derivative with respect to a vector field.
The transport operator that defines the Lie derivative is the pushforward of the field to
be derived along the integral curve of the field with respect to which one derives.

Examples

>>> from sympy.diffgeom import (LieDerivative, TensorProduct)

>>> from sympy.diffgeom.rn import R2
>>> LieDerivative(R2.e_x, R2.y)
0
>>> LieDerivative(R2.e_x, R2.x)
1
>>> LieDerivative(R2.e_x, R2.e_x)
0

The Lie derivative of a tensor field by another tensor field is equal to their commutator:

>>> LieDerivative(R2.e_x, R2.e_r)

Commutator(e_x, e_r)
>>> LieDerivative(R2.e_x + R2.e_y, R2.x)
1
>>> tp = TensorProduct(R2.dx, R2.dy)
>>> LieDerivative(R2.e_x, tp)
LieDerivative(e_x, TensorProduct(dx, dy))
>>> LieDerivative(R2.e_x, tp).doit()
LieDerivative(e_x, TensorProduct(dx, dy))

class sympy.diffgeom.BaseCovarDerivativeOp(coord_sys, index, christoffel)

Covariant derivative operator with respect to a base vector.

Examples

>>> from sympy.diffgeom.rn import R2, R2_r

>>> from sympy.diffgeom import BaseCovarDerivativeOp
>>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
>>> TP = TensorProduct
>>> ch = metric_to_Christoffel_2nd(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
>>> ch
[[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
>>> cvd = BaseCovarDerivativeOp(R2_r, 0, ch)
>>> cvd(R2.x)
1
>>> cvd(R2.x*R2.e_x)
e_x

class sympy.diffgeom.CovarDerivativeOp(wrt, christoffel)

Covariant derivative operator.

5.42. Differential Geometry Module 1841

SymPy Documentation, Release 1.3

Examples

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import CovarDerivativeOp
>>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
>>> TP = TensorProduct
>>> ch = metric_to_Christoffel_2nd(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
>>> ch
[[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
>>> cvd = CovarDerivativeOp(R2.x*R2.e_x, ch)
>>> cvd(R2.x)
x
>>> cvd(R2.x*R2.e_x)
x*e_x

sympy.diffgeom.intcurve_series(vector_field, param, start_point, n=6, co-

ord_sys=None, coeffs=False)
Return the series expansion for an integral curve of the field.
Integral curve is a function γ taking a parameter in R to a point in the manifold. It verifies
the equation:
( ) d
( )
V (f ) γ(t) = dt f γ(t)
where the given vector_field is denoted as V . This holds for any value t for the param-
eter and any scalar field f .
This equation can also be decomposed of a basis of coordinate functions
( ) ( )
d
V (fi ) γ(t) = dt fi γ(t) ∀i
This function returns a series expansion of γ(t) in terms of the coordinate system co-
ord_sys. The equations and expansions are necessarily done in coordinate-system-
dependent way as there is no other way to represent movement between points on the
manifold (i.e. there is no such thing as a difference of points for a general manifold).
Parameters vector_field
the vector field for which an integral curve will be given
param
the argument of the function γ from R to the curve
start_point
the point which corresponds to γ(0)
n
the order to which to expand
coord_sys
the coordinate system in which to expand coeffs (default False) - if
True return a list of elements of the expansion
See also:
intcurve_diffequ (page 1843)

1842 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

Use the predefined R2 manifold:

>>> from sympy.abc import t, x, y
>>> from sympy.diffgeom.rn import R2, R2_p, R2_r
>>> from sympy.diffgeom import intcurve_series

Specify a starting point and a vector field:

>>> start_point = R2_r.point([x, y])
>>> vector_field = R2_r.e_x

Calculate the series:

>>> intcurve_series(vector_field, t, start_point, n=3)
Matrix([
[t + x],
[ y]])

Or get the elements of the expansion in a list:

>>> series = intcurve_series(vector_field, t, start_point, n=3, coeffs=True)
>>> series[0]
Matrix([
[x],
[y]])
>>> series[1]
Matrix([
[t],
[0]])
>>> series[2]
Matrix([
[0],
[0]])

The series in the polar coordinate system:

>>> series = intcurve_series(vector_field, t, start_point,
... n=3, coord_sys=R2_p, coeffs=True)
>>> series[0]
Matrix([
[sqrt(x**2 + y**2)],
[ atan2(y, x)]])
>>> series[1]
Matrix([
[t*x/sqrt(x**2 + y**2)],
[ -t*y/(x**2 + y**2)]])
>>> series[2]
Matrix([
[t**2*(-x**2/(x**2 + y**2)**(3/2) + 1/sqrt(x**2 + y**2))/2],
[ t**2*x*y/(x**2 + y**2)**2]])

sympy.diffgeom.intcurve_diffequ(vector_field, param, start_point, co-

ord_sys=None)
Return the differential equation for an integral curve of the field.
Integral curve is a function γ taking a parameter in R to a point in the manifold. It verifies
the equation:

5.42. Differential Geometry Module 1843

SymPy Documentation, Release 1.3

( ) d
( )
V (f ) γ(t) = dt f γ(t)
where the given vector_field is denoted as V . This holds for any value t for the param-
eter and any scalar field f .
This function returns the differential equation of γ(t) in terms of the coordinate system
coord_sys. The equations and expansions are necessarily done in coordinate-system-
dependent way as there is no other way to represent movement between points on the
manifold (i.e. there is no such thing as a difference of points for a general manifold).
Parameters vector_field
the vector field for which an integral curve will be given
param
the argument of the function γ from R to the curve
start_point
the point which corresponds to γ(0)
coord_sys
the coordinate system in which to give the equations
Returns a tuple of (equations, initial conditions)
See also:
intcurve_series (page 1842)

Examples

Use the predefined R2 manifold:

>>> from sympy.abc import t

>>> from sympy.diffgeom.rn import R2, R2_p, R2_r
>>> from sympy.diffgeom import intcurve_diffequ

Specify a starting point and a vector field:

>>> start_point = R2_r.point([0, 1])

>>> vector_field = -R2.y*R2.e_x + R2.x*R2.e_y

Get the equation:

>>> equations, init_cond = intcurve_diffequ(vector_field, t, start_point)

>>> equations
[f_1(t) + Derivative(f_0(t), t), -f_0(t) + Derivative(f_1(t), t)]
>>> init_cond
[f_0(0), f_1(0) - 1]

The series in the polar coordinate system:

>>> equations, init_cond = intcurve_diffequ(vector_field, t, start_point, R2_p)

>>> equations
[Derivative(f_0(t), t), Derivative(f_1(t), t) - 1]
>>> init_cond
[f_0(0) - 1, f_1(0) - pi/2]

1844 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

sympy.diffgeom.vectors_in_basis(expr, to_sys)
Transform all base vectors in base vectors of a specified coord basis.
While the new base vectors are in the new coordinate system basis, any coefficients are
kept in the old system.

Examples

>>> from sympy.diffgeom import vectors_in_basis

>>> from sympy.diffgeom.rn import R2_r, R2_p
>>> vectors_in_basis(R2_r.e_x, R2_p)
x*e_r/sqrt(x**2 + y**2) - y*e_theta/(x**2 + y**2)
>>> vectors_in_basis(R2_p.e_r, R2_r)
sin(theta)*e_y + cos(theta)*e_x

sympy.diffgeom.twoform_to_matrix(expr)
Return the matrix representing the twoform.
For the twoform w return the matrix M such that M [i, j] = w(ei , ej ), where ei is the i-th
base vector field for the coordinate system in which the expression of w is given.

Examples

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import twoform_to_matrix, TensorProduct
>>> TP = TensorProduct
>>> twoform_to_matrix(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
Matrix([
[1, 0],
[0, 1]])
>>> twoform_to_matrix(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
Matrix([
[x, 0],
[0, 1]])
>>> twoform_to_matrix(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy) - TP(R2.dx, R2.dy)/2)
Matrix([
[ 1, 0],
[-1/2, 1]])

sympy.diffgeom.metric_to_Christoffel_1st(expr)
Return the nested list of Christoffel symbols for the given metric.
This returns the Christoffel symbol of first kind that represents the Levi-Civita connection
for the given metric.

Examples

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import metric_to_Christoffel_1st, TensorProduct
>>> TP = TensorProduct
>>> metric_to_Christoffel_1st(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
(continues on next page)

5.42. Differential Geometry Module 1845

SymPy Documentation, Release 1.3

(continued from previous page)

>>> metric_to_Christoffel_1st(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[[1/2, 0], [0, 0]], [[0, 0], [0, 0]]]

sympy.diffgeom.metric_to_Christoffel_2nd(expr)
Return the nested list of Christoffel symbols for the given metric.
This returns the Christoffel symbol of second kind that represents the Levi-Civita con-
nection for the given metric.

Examples

>>> from sympy.diffgeom.rn import R2

>>> from sympy.diffgeom import metric_to_Christoffel_2nd, TensorProduct
>>> TP = TensorProduct
>>> metric_to_Christoffel_2nd(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[[0, 0], [0, 0]], [[0, 0], [0, 0]]]
>>> metric_to_Christoffel_2nd(R2.x*TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[[1/(2*x), 0], [0, 0]], [[0, 0], [0, 0]]]

sympy.diffgeom.metric_to_Riemann_components(expr)
Return the components of the Riemann tensor expressed in a given basis.
Given a metric it calculates the components of the Riemann tensor in the canonical basis
of the coordinate system in which the metric expression is given.

Examples

>>> from sympy import exp

>>> from sympy.diffgeom.rn import R2
>>> from sympy.diffgeom import metric_to_Riemann_components, TensorProduct
>>> TP = TensorProduct
>>> metric_to_Riemann_components(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[[[0, 0], [0, 0]], [[0, 0], [0, 0]]], [[[0, 0], [0, 0]], [[0, 0], [0, 0]]]]

>>> non_trivial_metric = exp(2*R2.r)*TP(R2.dr, R2.dr) + R2.r**2*TP(R2.

,→dtheta, R2.dtheta)

>>> non_trivial_metric
r**2*TensorProduct(dtheta, dtheta) + exp(2*r)*TensorProduct(dr, dr)
>>> riemann = metric_to_Riemann_components(non_trivial_metric)
>>> riemann[0, :, :, :]
[[[0, 0], [0, 0]], [[0, r*exp(-2*r)], [-r*exp(-2*r), 0]]]
>>> riemann[1, :, :, :]
[[[0, -1/r], [1/r, 0]], [[0, 0], [0, 0]]]

sympy.diffgeom.metric_to_Ricci_components(expr)
Return the components of the Ricci tensor expressed in a given basis.
Given a metric it calculates the components of the Ricci tensor in the canonical basis of
the coordinate system in which the metric expression is given.

1846 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy import exp

>>> from sympy.diffgeom.rn import R2
>>> from sympy.diffgeom import metric_to_Ricci_components, TensorProduct
>>> TP = TensorProduct
>>> metric_to_Ricci_components(TP(R2.dx, R2.dx) + TP(R2.dy, R2.dy))
[[0, 0], [0, 0]]

>>> non_trivial_metric = exp(2*R2.r)*TP(R2.dr, R2.dr) + ␣

,→ R2.r**2*TP(R2.dtheta, R2.dtheta)
>>> non_trivial_metric
r**2*TensorProduct(dtheta, dtheta) + exp(2*r)*TensorProduct(dr, dr)
>>> metric_to_Ricci_components(non_trivial_metric)
[[1/r, 0], [0, r*exp(-2*r)]]

5.43 Vector Module

The vector module provides tools for basic vector math and differential calculus with respect
to 3D Cartesian coordinate systems. This documentation provides an overview of all the
features offered, and relevant API.

5.43.1 Guide to Vector

Introduction

This page gives a brief conceptual overview of the functionality present in sympy.vector.

Vectors and Scalars

In vector math, we deal with two kinds of quantities – scalars and vectors.
A scalar is an entity which only has a magnitude – no direction. Examples of scalar quantities
include mass, electric charge, temperature, distance, etc.
A vector, on the other hand, is an entity that is characterized by a magnitude and a direction.
Examples of vector quantities are displacement, velocity, magnetic field, etc.
A scalar can be depicted just by a number, for e.g. a temperature of 300 K. On the other
hand, vectorial quantities like acceleration are usually denoted by a vector. Given a vector
V, the magnitude of the corresponding quantity can be calculated as the magnitude of the
vector itself ∥V∥, while the direction would be specified by a unit vector in the direction of the
original vector, ^ V
V = ∥V∥ .

For example, consider a displacement of (3^ i + 4^

j + 5^
k) m, where , as per standard convention,
^
i, ^
j and ^
k represent unit vectors along the X, Y and Z axes respectively. Therefore, it can be
√
concluded that the distance traveled is ∥3^ i + 4^ j + 5^
k∥ m = 5 2 m. The direction of travel is
3 ^ 4 ^ 5 ^
given by the unit vector 5√ 2
i + 5√ 2
j + 5√ 2
k.

5.43. Vector Module 1847

SymPy Documentation, Release 1.3

Coordinate Systems

A coordinate system is an abstract mathematical entity used to define the notion of direc-
tions and locations in n-dimensional spaces. This module deals with 3-dimensional spaces,
with the conventional X, Y and Z axes defined with respect to each coordinate system.
Each coordinate system also has a special reference point called the ‘origin’ defined for it.
This point is used either while referring to locations in 3D space, or while calculating the
coordinates of pre-defined points with respect to the system.
It is a pretty well-known concept that there is no absolute notion of location or orientation in
space. Any given coordinate system defines a unique ‘perspective’ of quantifying positions
and directions. Therefore, even if we assume that all systems deal with the same units of mea-
surement, the expression of vectorial and scalar quantities differs according to the coordinate
system a certain observer deals with.
Consider two points P and Q in space. Assuming units to be common throughtout, the distance
between these points remains the same regardless of the coordinate system in which the
measurements are being made. However, the 3-D coordinates of each of the two points, as
well as the position vector of any of the points with respect to the other, do not. In fact, these
two quantities don’t make sense at all, unless they are being measured keeping in mind a
certain location and orientation of the measurer (essentially the coordinate system).
Therefore, it is quite clear that the orientation and location (of the origin) of a coordinate
system define the way different quantities will be expressed with respect to it. Neither of
the two properties can be measured on an absolute scale, but rather with respect to another
coordinate system. The orientation of one system with respect to another is measured using
the rotation matrix, while the relative position can be quantified via the position vector of one
system’s origin with respect to the other.

Fields

A field is a vector or scalar quantity that can be specified everywhere in space as a function
of position (Note that in general a field may also be dependent on time and other custom
variables). Since we only deal with 3D spaces in this module, a field is defined as a function
of the x, y and z coordinates corresponding to a location in the coordinate system. Here, x, y
and z act as scalar variables defining the position of a general point.
For example, temperature in 3 dimensional space (a temperature field) can be written as
T (x, y, z) – a scalar function of the position. An example of a scalar field in electromagnetism
is the electric potential.
In a similar manner, a vector field can be defined as a vectorial function of the location (x, y, z)
of any point in space.
For instance, every point on the earth may be considered to be in the gravitational force field
of the earth. We may specify the field by the magnitude and the direction of acceleration due
to gravity (i.e. force per unit mass ) ⃗g (x, y, z) at every point in space.
To give an example from electromagnetism, consider an electric potential of form 2x2 y, a
scalar field in 3D space. The corresponding conservative electric field can be computed as
the gradient of the electric potential function, and expressed as 4xy^i + 2x 2^
√ j. The magnitude of
this electric field can in turn be expressed as a scalar field of the form 4x4 + 16x2 y 2 .

Basic Implementation details

1848 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Coordinate Systems and Vectors

Currently, sympy.vector is able to deal with the Cartesian (also called rectangular), spherical
and other curvilinear coordinate systems.
A 3D Cartesian coordinate system can be initialized in sympy.vector as
>>> from sympy.vector import CoordSys3D
>>> N = CoordSys3D('N')

The string parameter to the constructor denotes the name assigned to the system, and will
primarily be used for printing purposes.
Once a coordinate system (in essence, a CoordSys3D instance) has been defined, we can
access the orthonormal unit vectors (i.e. the ^
i, ^
j and ^
k vectors) and coordinate variables/base
scalars (i.e. the x, y and z variables) corresponding to it. We will talk about coordinate
variables in the later sections.
The basis vectors for the X, Y and Z axes can be accessed using the i, j and k properties
respectively.
>>> N.i
N.i
>>> type(N.i)
<class 'sympy.vector.vector.BaseVector'>

As seen above, the basis vectors are all instances of a class called BaseVector.
When a BaseVector is multiplied by a scalar (essentially any SymPy Expr), we get a VectorMul
- the product of a base vector and a scalar.
>>> 3*N.i
3*N.i
>>> type(3*N.i)
<class 'sympy.vector.vector.VectorMul'>

Addition of VectorMul and BaseVectors gives rise to formation of VectorAdd - except for
special cases, ofcourse.
>>> v = 2*N.i + N.j
>>> type(v)
<class 'sympy.vector.vector.VectorAdd'>
>>> v - N.j
2*N.i
>>> type(v - N.j)
<class 'sympy.vector.vector.VectorMul'>

What about a zero vector? It can be accessed using the zero attribute assigned to class
Vector. Since the notion of a zero vector remains the same regardless of the coordinate
system in consideration, we use Vector.zero wherever such a quantity is required.
>>> from sympy.vector import Vector
>>> Vector.zero
0
>>> type(Vector.zero)
<class 'sympy.vector.vector.VectorZero'>
>>> N.i + Vector.zero
N.i
(continues on next page)

5.43. Vector Module 1849

SymPy Documentation, Release 1.3

(continued from previous page)

>>> Vector.zero == 2*Vector.zero
True

All the classes shown above - BaseVector, VectorMul, VectorAdd and VectorZero are sub-
classes of Vector.
You should never have to instantiate objects of any of the subclasses of Vector. Using the
BaseVector instances assigned to a CoordSys3D instance and (if needed) Vector.zero as
building blocks, any sort of vectorial expression can be constructed with the basic mathemat-
ical operators +, -, *. and /.

>>> v = N.i - 2*N.j

>>> v/3
1/3*N.i + (-2/3)*N.j
>>> v + N.k
N.i + (-2)*N.j + N.k
>>> Vector.zero/2
0
>>> (v/3)*4
4/3*N.i + (-8/3)*N.j

In addition to the elementary mathematical operations, the vector operations of dot and cross
can also be performed on Vector.

>>> v1 = 2*N.i + 3*N.j - N.k

>>> v2 = N.i - 4*N.j + N.k
>>> v1.dot(v2)
-11
>>> v1.cross(v2)
(-1)*N.i + (-3)*N.j + (-11)*N.k
>>> v2.cross(v1)
N.i + 3*N.j + 11*N.k

The & and ^ operators have been overloaded for the dot and cross methods respectively.

>>> v1 & v2
-11
>>> v1 ^ v2
(-1)*N.i + (-3)*N.j + (-11)*N.k

However, this is not the recommended way of performing these operations. Using the original
methods makes the code clearer and easier to follow.
In addition to these operations, it is also possible to compute the outer products of Vector
instances in sympy.vector. More on that in a little bit.

SymPy operations on Vectors

The SymPy operations of simplify, trigsimp, diff, and factor work on Vector objects, with
the standard SymPy API.
In essence, the methods work on the measure numbers(The coefficients of the basis vectors)
present in the provided vectorial expression.

1850 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.abc import a, b, c

>>> from sympy import sin, cos, trigsimp, diff
>>> v = (a*b + a*c + b**2 + b*c)*N.i + N.j
>>> v.factor()
((a + b)*(b + c))*N.i + N.j
>>> v = (sin(a)**2 + cos(a)**2)*N.i - (2*cos(b)**2 - 1)*N.k
>>> trigsimp(v)
N.i + (-cos(2*b))*N.k
>>> v.simplify()
N.i + (-cos(2*b))*N.k
>>> diff(v, b)
(4*sin(b)*cos(b))*N.k
>>> from sympy import Derivative
>>> Derivative(v, b).doit()
(4*sin(b)*cos(b))*N.k

Integral also works with Vector instances, similar to Derivative.

>>> from sympy import Integral

>>> v1 = a*N.i + sin(a)*N.j - N.k
>>> Integral(v1, a)
(Integral(a, a))*N.i + (Integral(sin(a), a))*N.j + (Integral(-1, a))*N.k
>>> Integral(v1, a).doit()
a**2/2*N.i + (-cos(a))*N.j + (-a)*N.k

Points

As mentioned before, every coordinate system corresponds to a unique origin point. Points,
in general, have been implemented in sympy.vector in the form of the Point class.
To access the origin of system, use the origin property of the CoordSys3D class.

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> N.origin
N.origin
>>> type(N.origin)
<class 'sympy.vector.point.Point'>

You can instantiate new points in space using the locate_new method of Point. The argu-
ments include the name(string) of the new Point, and its position vector with respect to the
‘parent’ Point.

>>> from sympy.abc import a, b, c

>>> P = N.origin.locate_new('P', a*N.i + b*N.j + c*N.k)
>>> Q = P.locate_new('Q', -b*N.j)

Like Vector, a user never has to expressly instantiate an object of Point. This is because any
location in space (albeit relative) can be pointed at by using the origin of a CoordSys3D as
the reference, and then using locate_new on it and subsequent Point instances.
The position vector of a Point with respect to another Point can be computed using the
position_wrt method.

5.43. Vector Module 1851

SymPy Documentation, Release 1.3

>>> P.position_wrt(Q)
b*N.j
>>> Q.position_wrt(N.origin)
a*N.i + c*N.k

Additionally, it is possible to obtain the X, Y and Z coordinates of a Point with respect to a

CoordSys3D in the form of a tuple. This is done using the express_coordinates method.
>>> Q.express_coordinates(N)
(a, 0, c)

Dyadics

A dyadic, or dyadic tensor, is a second-order tensor formed by the juxtaposition of pairs of

vectors. Therefore, the outer products of vectors give rise to the formation of dyadics. Dyadic
tensors have been implemented in sympy.vector in the Dyadic class.
Once again, you never have to instantiate objects of Dyadic. The outer products of vectors
can be computed using the outer method of Vector. The | operator has been overloaded for
outer.
>>> from sympy.vector import CoordSys3D
>>> N = CoordSys3D('N')
>>> N.i.outer(N.j)
(N.i|N.j)
>>> N.i|N.j
(N.i|N.j)

Similar to Vector, Dyadic also has subsequent subclasses like BaseDyadic, DyadicMul, Dyad-
icAdd. As with Vector, a zero dyadic can be accessed from Dyadic.zero.
All basic mathematical operations work with Dyadic too.
>>> dyad = N.i.outer(N.k)
>>> dyad*3
3*(N.i|N.k)
>>> dyad - dyad
0
>>> dyad + 2*(N.j|N.i)
(N.i|N.k) + 2*(N.j|N.i)

dot and cross also work among Dyadic instances as well as between a Dyadic and Vector
(and also vice versa) - as per the respective mathematical definitions. As with Vector, & and
^ have been overloaded for dot and cross.
>>> d = N.i.outer(N.j)
>>> d.dot(N.j|N.j)
(N.i|N.j)
>>> d.dot(N.i)
0
>>> d.dot(N.j)
N.i
>>> N.i.dot(d)
N.j
>>> N.k ^ d
(N.j|N.j)

1852 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

More about Coordinate Systems

We will now look at how we can initialize new coordinate systems in sympy.vector, trans-
formed in user-defined ways with respect to already-existing systems.

Locating new systems

We already know that the origin property of a CoordSys3D corresponds to the Point instance
denoting its origin reference point.
Consider a coordinate system N . Suppose we want to define a new system M , whose origin
is located at 3^
i + 4^
j + 5^
k from N ’s origin. In other words, the coordinates of M ’s origin from
N’s perspective happen to be (3, 4, 5). Moreover, this would also mean that the coordinates of
N ’s origin with respect to M would be (−3, −4, −5).
This can be achieved programmatically as follows -

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> M = N.locate_new('M', 3*N.i + 4*N.j + 5*N.k)
>>> M.position_wrt(N)
3*N.i + 4*N.j + 5*N.k
>>> N.origin.express_coordinates(M)
(-3, -4, -5)

It is worth noting that M ’s orientation is the same as that of N . This means that the rotation
matrix of :math: N with respect to M , and also vice versa, is equal to the identity matrix of
dimensions 3x3. The locate_new method initializes a CoordSys3D that is only translated in
space, not re-oriented, relative to the ‘parent’ system.

Orienting new systems

Similar to ‘locating’ new systems, sympy.vector also allows for initialization of new Co-
ordSys3D instances that are oriented in user-defined ways with respect to existing systems.
Suppose you have a coordinate system A.

>>> from sympy.vector import CoordSys3D

>>> A = CoordSys3D('A')

You want to initialize a new coordinate system B, that is rotated with respect to A’s Z-axis by
an angle θ.

>>> from sympy import Symbol

>>> theta = Symbol('theta')

The orientation is shown in the diagram below:

5.43. Vector Module 1853

SymPy Documentation, Release 1.3

az
bz

B
by
A θ
ay
θ
ax bx
There are two ways to achieve this.

Using a method of CoordSys3D directly

This is the easiest, cleanest, and hence the recommended way of doing it.

>>> B = A.orient_new_axis('B', theta, A.k)

This initializes B with the required orientation information with respect to A.

CoordSys3D provides the following direct orientation methods in its API-
1. orient_new_axis
2. orient_new_body
3. orient_new_space
4. orient_new_quaternion
Please look at the CoordSys3D class API given in the docs of this module, to know their func-
tionality and required arguments in detail.

Using Orienter(s) and the orient_new method

You would first have to initialize an AxisOrienter instance for storing the rotation informa-
tion.

>>> from sympy.vector import AxisOrienter

>>> axis_orienter = AxisOrienter(theta, A.k)

And then apply it using the orient_new method, to obtain B.

>>> B = A.orient_new('B', axis_orienter)

orient_new also lets you orient new systems using multiple Orienter instances, provided
in an iterable. The rotations/orientations are applied to the new system in the order the
Orienter instances appear in the iterable.

1854 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import BodyOrienter

>>> from sympy.abc import a, b, c
>>> body_orienter = BodyOrienter(a, b, c, 'XYZ')
>>> C = A.orient_new('C', (axis_orienter, body_orienter))

The sympy.vector API provides the following four Orienter classes for orientation purposes-
1. AxisOrienter
2. BodyOrienter
3. SpaceOrienter
4. QuaternionOrienter
Please refer to the API of the respective classes in the docs of this module to know more.
In each of the above examples, the origin of the new coordinate system coincides with the
origin of the ‘parent’ system.

>>> B.position_wrt(A)
0

To compute the rotation matrix of any coordinate system with respect to another one, use the
rotation_matrix method.

>>> B = A.orient_new_axis('B', a, A.k)

>>> B.rotation_matrix(A)
Matrix([
[ cos(a), sin(a), 0],
[-sin(a), cos(a), 0],
[ 0, 0, 1]])
>>> B.rotation_matrix(B)
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

Orienting AND Locating new systems

What if you want to initialize a new system that is not only oriented in a pre-defined way, but
also translated with respect to the parent?
Each of the orient_new_<method of orientation> methods, as well as the orient_new
method, support a location keyword argument.
If a Vector is supplied as the value for this kwarg, the new system’s origin is automatically
defined to be located at that position vector with respect to the parent coordinate system.
Thus, the orientation methods also act as methods to support orientation+ location of the
new systems.

>>> C = A.orient_new_axis('C', a, A.k, location=2*A.j)

>>> C.position_wrt(A)
2*A.j
>>> from sympy.vector import express
>>> express(A.position_wrt(C), C)
(-2*sin(a))*C.i + (-2*cos(a))*C.j

5.43. Vector Module 1855

SymPy Documentation, Release 1.3

More on the express function in a bit.

Transforming new system

The most general way of creating user-defined system is to use transformation parameter
in CoordSys3D. Here we can define any transformation equations. If we are interested in
some typical curvilinear coordinate system different that Cartesian, we can also use some
predefined ones. It could be also possible to translate or rotate system by setting appropriate
transformation equations.

>>> from sympy.vector import CoordSys3D

>>> from sympy import sin, cos
>>> A = CoordSys3D('A', transformation='spherical')
>>> B = CoordSys3D('A', transformation=lambda x,y,z: (x*sin(y), x*cos(y), z))

In CoordSys3D is also dedicated method, create_new which works similarly to methods like
locate_new, orient_new_axis etc.

>>> from sympy.vector import CoordSys3D

>>> A = CoordSys3D('A')
>>> B = A.create_new('B', transformation='spherical')

Expression of quantities in different coordinate systems

Vectors and Dyadics

As mentioned earlier, the same vector attains different expressions in different coordinate
systems. In general, the same is true for scalar expressions and dyadic tensors.
sympy.vector supports the expression of vector/scalar quantities in different coordinate sys-
tems using the express function.
For purposes of this section, assume the following initializations-

>>> from sympy.vector import CoordSys3D, express

>>> from sympy.abc import a, b, c
>>> N = CoordSys3D('N')
>>> M = N.orient_new_axis('M', a, N.k)

Vector instances can be expressed in user defined systems using express.

>>> v1 = N.i + N.j + N.k

>>> express(v1, M)
(sin(a) + cos(a))*M.i + (-sin(a) + cos(a))*M.j + M.k
>>> v2 = N.i + M.j
>>> express(v2, N)
(-sin(a) + 1)*N.i + (cos(a))*N.j

Apart from Vector instances, express also supports reexpression of scalars (general SymPy
Expr) and Dyadic objects.
express also accepts a second coordinate system for re-expressing Dyadic instances.

1856 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> d = 2*(M.i | N.j) + 3* (M.j | N.k)

>>> express(d, M)
(2*sin(a))*(M.i|M.i) + (2*cos(a))*(M.i|M.j) + 3*(M.j|M.k)
>>> express(d, M, N)
2*(M.i|N.j) + 3*(M.j|N.k)

Coordinate Variables

The location of a coordinate system’s origin does not affect the re-expression of BaseVector
instances. However, it does affect the way BaseScalar instances are expressed in different
systems.
BaseScalar instances, are coordinate ‘symbols’ meant to denote the variables used in the
definition of vector/scalar fields in sympy.vector.
For example, consider the scalar field TN (x, y, z) = x + y + z defined in system N . Thus, at a
point with coordinates (a, b, c), the value of the field would be a + b + c. Now consider system
R, whose origin is located at (1, 2, 3) with respect to N (no change of orientation). A point with
coordinates (a, b, c) in R has coordinates (a + 1, b + 2, c + 3) in N . Therefore, the expression for
TN in R becomes TR (x, y, z) = x + y + z + 6.
Coordinate variables, if present in a vector/scalar/dyadic expression, can also be re-expressed
in a given coordinate system, by setting the variables keyword argument of express to True.
The above mentioned example, done programmatically, would look like this -

>>> R = N.locate_new('R', N.i + 2*N.j + 3*N.k)

>>> T_N = N.x + N.y + N.z
>>> express(T_N, R, variables=True)
R.x + R.y + R.z + 6

Other expression-dependent methods

The to_matrix method of Vector and express_coordinates method of Point also return
different results depending on the coordinate system being provided.

>>> P = R.origin.locate_new('P', a*R.i + b*R.j + c*R.k)

>>> P.express_coordinates(N)
(a + 1, b + 2, c + 3)
>>> P.express_coordinates(R)
(a, b, c)
>>> v = N.i + N.j + N.k
>>> v.to_matrix(M)
Matrix([
[ sin(a) + cos(a)],
[-sin(a) + cos(a)],
[ 1]])
>>> v.to_matrix(N)
Matrix([
[1],
[1],
[1]])

5.43. Vector Module 1857

SymPy Documentation, Release 1.3

Scalar and Vector Field Functionality

Implementation in sympy.vector

Scalar and vector fields

In sympy.vector, every CoordSysCartesian instance is assigned basis vectors correspond-

ing to the X, Y and Z axes. These can be accessed using the properties named i, j and k
respectively. Hence, to define a vector v of the form 3^
i + 4^
j + 5^
k with respect to a given frame
R, you would do

>>> from sympy.vector import CoordSys3D

>>> R = CoordSys3D('R')
>>> v = 3*R.i + 4*R.j + 5*R.k

Vector math and basic calculus operations with respect to vectors have already been elabo-
rated upon in the earlier section of this module’s documentation.
On the other hand, base scalars (or coordinate variables) are implemented in a special class
called BaseScalar, and are assigned to every coordinate system, one for each axis from X, Y
and Z. These coordinate variables are used to form the expressions of vector or scalar fields
in 3D space. For a system R, the X, Y and Z BaseScalars instances can be accessed using
the R.x, R.y and R.z expressions respectively.
Therefore, to generate the expression for the aforementioned electric potential field 2x2 y, you
would have to do

>>> from sympy.vector import CoordSys3D

>>> R = CoordSys3D('R')
>>> electric_potential = 2*R.x**2*R.y
>>> electric_potential
2*R.x**2*R.y

It is to be noted that BaseScalar instances can be used just like any other SymPy Symbol,
except that they store the information about the coordinate system and axis they correspond
to.
Scalar fields can be treated just as any other SymPy expression, for any math/calculus func-
tionality. Hence, to differentiate the above electric potential with respect to x (i.e. R.x), you
would use the diff method.

>>> from sympy.vector import CoordSys3D

>>> R = CoordSys3D('R')
>>> electric_potential = 2*R.x**2*R.y
>>> from sympy import diff
>>> diff(electric_potential, R.x)
4*R.x*R.y

It is worth noting that having a BaseScalar in the expression implies that a ‘field’ changes
with position, in 3D space. Technically speaking, a simple Expr with no BaseScalar s is still
a field, though constant.
Like scalar fields, vector fields that vary with position can also be constructed using
BaseScalar s in the measure-number expressions.

1858 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D

>>> R = CoordSys3D('R')
>>> v = R.x**2*R.i + 2*R.x*R.z*R.k

The Del operator

The Del, or ‘Nabla’ operator - written as ∇ is commonly known as the vector differential
operator. Depending on its usage in a mathematical expression, it may denote the gradient
of a scalar field, the divergence of a vector field, or the curl of a vector field.
Essentially, ∇ is not technically an ‘operator’, but a convenient mathematical notation to de-
note any one of the aforementioned field operations.
In sympy.vector, ∇ has been implemented as the Del() class. The instance of this class is
independent of coordinate system. Hence, the ∇ operator would be accessible as Del().
Given below is an example of usage of the Del() class.

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> gradient_field = delop(C.x*C.y*C.z)
>>> gradient_field
(Derivative(C.x*C.y*C.z, C.x))*C.i + (Derivative(C.x*C.y*C.z, C.y))*C.j
+ (Derivative(C.x*C.y*C.z, C.z))*C.k

The above expression can be evaluated using the SymPy doit() routine.

>>> gradient_field.doit()
C.y*C.z*C.i + C.x*C.z*C.j + C.x*C.y*C.k

Usage of the ∇ notation in sympy.vector has been described in greater detail in the subse-
quent subsections.

Field operators and related functions

Here we describe some basic field-related functionality implemented in sympy.vector.

Curl

A curl is a mathematical operator that describes an infinitesimal rotation of a vector in 3D

space. The direction is determined by the right-hand rule (along the axis of rotation), and the
magnitude is given by the magnitude of rotation.
In the 3D Cartesian system, the curl of a 3D vector F , denoted by ∇ × F is given by:
( ) ( )
∂Fy ^ ( ∂Fx )
∂Fz ^ ∂Fy ∂Fx ^
∇ × F = ∂F∂y
z
− ∂z i + ∂z − ∂x j + ∂x − ∂y k

where Fx denotes the X component of vector F.

Computing the curl of a vector field in sympy.vector can be accomplished in two ways.
One, by using the Del() class

5.43. Vector Module 1859

SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> delop.cross(C.x*C.y*C.z*C.i).doit()
C.x*C.y*C.j + (-C.x*C.z)*C.k
>>> (delop ^ C.x*C.y*C.z*C.i).doit()
C.x*C.y*C.j + (-C.x*C.z)*C.k

Or by using the dedicated function

>>> from sympy.vector import curl

>>> curl(C.x*C.y*C.z*C.i)
C.x*C.y*C.j + (-C.x*C.z)*C.k

Divergence

Divergence is a vector operator that measures the magnitude of a vector field’s source or sink
at a given point, in terms of a signed scalar.
The divergence operator always returns a scalar after operating on a vector.
In the 3D Cartesian system, the divergence of a 3D vector F, denoted by ∇ · F is given by:
∇·F= ∂U
∂x + ∂V
∂y + ∂W
∂z

where U , V and W denote the X, Y and Z components of F respectively.

Computing the divergence of a vector field in sympy.vector can be accomplished in two ways.
One, by using the Del() class

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> delop.dot(C.x*C.y*C.z*(C.i + C.j + C.k)).doit()
C.x*C.y + C.x*C.z + C.y*C.z
>>> (delop & C.x*C.y*C.z*(C.i + C.j + C.k)).doit()
C.x*C.y + C.x*C.z + C.y*C.z

Or by using the dedicated function

>>> from sympy.vector import divergence

>>> divergence(C.x*C.y*C.z*(C.i + C.j + C.k))
C.x*C.y + C.x*C.z + C.y*C.z

Gradient

Consider a scalar field f (x, y, z) in 3D space. The gradient of this field is defined as the vector
of the 3 partial derivatives of f with respect to x, y and z in the X, Y and Z axes respectively.
In the 3D Cartesian system, the divergence of a scalar field f , denoted by ∇f is given by -
∂f^ ∂f^ ∂f ^
∇f = ∂x i + ∂y j + ∂z k

Computing the divergence of a vector field in sympy.vector can be accomplished in two ways.
One, by using the Del() class

1860 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> delop.gradient(C.x*C.y*C.z).doit()
C.y*C.z*C.i + C.x*C.z*C.j + C.x*C.y*C.k
>>> delop(C.x*C.y*C.z).doit()
C.y*C.z*C.i + C.x*C.z*C.j + C.x*C.y*C.k

Or by using the dedicated function

>>> from sympy.vector import gradient

>>> gradient(C.x*C.y*C.z)
C.y*C.z*C.i + C.x*C.z*C.j + C.x*C.y*C.k

Directional Derivative

Apart from the above three common applications of ∇, it is also possible to compute the
directional derivative of a field wrt a Vector in sympy.vector.
By definition, the directional derivative of a field F along a vector v at point x represents the
instantaneous rate of change of F moving through x with the velocity v. It is represented
mathematically as: (⃗v · ∇) F(x).
Directional derivatives of vector and scalar fields can be computed in sympy.vector using
the Del() class

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> vel = C.i + C.j + C.k
>>> scalar_field = C.x*C.y*C.z
>>> vector_field = C.x*C.y*C.z*C.i
>>> (vel.dot(delop))(scalar_field)
C.x*C.y + C.x*C.z + C.y*C.z
>>> (vel & delop)(vector_field)
(C.x*C.y + C.x*C.z + C.y*C.z)*C.i

Or by using the dedicated function

>>> from sympy.vector import directional_derivative

>>> directional_derivative(C.x*C.y*C.z, 3*C.i + 4*C.j + C.k)
C.x*C.y + 4*C.x*C.z + 3*C.y*C.z

Field operator in orthogonal curvilinear coordinate system

vector package supports calculation in different kind of orthogonal curvilinear coordinate

system. To do that, scaling factor (also known as Lame coefficients) are used to express curl,
divergence or gradient in desired type of coordinate system.
For example if we want to calculate gradient in cylindrical coordinate system all we need to
do is to create proper coordinate system

5.43. Vector Module 1861

SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D

>>> c = CoordSys3D('c', transformation='cylindrical', variable_names=(”r”, ”theta”, ”z
,→”))

>>> gradient(c.r*c.theta*c.z)
c.theta*c.z*c.i + c.z*c.j + c.r*c.theta*c.k

Conservative and Solenoidal fields

In vector calculus, a conservative field is a field that is the gradient of some scalar field.
Conservative fields have the property that their line integral over any path depends only on
the end-points, and is independent of the path travelled. A conservative vector field is also
said to be ‘irrotational’, since the curl of a conservative field is always zero.
In physics, conservative fields represent forces in physical systems where energy is con-
served.
To check if a vector field is conservative in sympy.vector, the is_conservative function can
be used.

>>> from sympy.vector import CoordSys3D, is_conservative

>>> R = CoordSys3D('R')
>>> field = R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> is_conservative(field)
True
>>> curl(field)
0

A solenoidal field, on the other hand, is a vector field whose divergence is zero at all points
in space.
To check if a vector field is solenoidal in sympy.vector, the is_solenoidal function can be
used.

>>> from sympy.vector import CoordSys3D, is_solenoidal

>>> R = CoordSys3D('R')
>>> field = R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> is_solenoidal(field)
True
>>> divergence(field)
0

Scalar potential functions

We have previously mentioned that every conservative field can be defined as the gradient of
some scalar field. This scalar field is also called the ‘scalar potential field’ corresponding to
the aforementioned conservative field.
The scalar_potential function in sympy.vector calculates the scalar potential field cor-
responding to a given conservative vector field in 3D space - minus the extra constant of
integration, of course.
Example of usage -

1862 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D, scalar_potential

>>> R = CoordSys3D('R')
>>> conservative_field = 4*R.x*R.y*R.z*R.i + 2*R.x**2*R.z*R.j + 2*R.x**2*R.y*R.k
>>> scalar_potential(conservative_field, R)
2*R.x**2*R.y*R.z

Providing a non-conservative vector field as an argument to scalar_potential raises a Val-

ueError.
The scalar potential difference, or simply ‘potential difference’, corresponding to a conser-
vative vector field can be defined as the difference between the values of its scalar potential
function at two points in space. This is useful in calculating a line integral with respect to a
conservative function, since it depends only on the endpoints of the path.
This computation is performed as follows in sympy.vector.

>>> from sympy.vector import CoordSys3D, Point

>>> from sympy.vector import scalar_potential_difference
>>> R = CoordSys3D('R')
>>> P = R.origin.locate_new('P', 1*R.i + 2*R.j + 3*R.k)
>>> vectfield = 4*R.x*R.y*R.i + 2*R.x**2*R.j
>>> scalar_potential_difference(vectfield, R, R.origin, P)
4

If provided with a scalar expression instead of a vector field, scalar_potential_difference

returns the difference between the values of that scalar field at the two given points in space.

General examples of usage

This section details the solution of two basic problems in vector math/calculus using the
sympy.vector package.

Quadrilateral problem

The Problem

OABC is any quadrilateral in 3D space. P is the midpoint of OA, Q is the midpoint of AB, R is
the midpoint of BC and S is the midpoint of OC. Prove that PQ is parallel to SR

Solution

The solution to this problem demonstrates the usage of Point, and basic operations on Vec-
tor.
Define a coordinate system

>>> from sympy.vector import CoordSys3D

>>> Sys = CoordSys3D('Sys')

Define point O to be Sys’ origin. We can do this without loss of generality

>>> O = Sys.origin

5.43. Vector Module 1863

SymPy Documentation, Release 1.3

Define point A with respect to O

>>> from sympy import symbols

>>> a1, a2, a3 = symbols('a1 a2 a3')
>>> A = O.locate_new('A', a1*Sys.i + a2*Sys.j + a3*Sys.k)

Similarly define points B and C

>>> b1, b2, b3 = symbols('b1 b2 b3')

>>> B = O.locate_new('B', b1*Sys.i + b2*Sys.j + b3*Sys.k)
>>> c1, c2, c3 = symbols('c1 c2 c3')
>>> C = O.locate_new('C', c1*Sys.i + c2*Sys.j + c3*Sys.k)

P is the midpoint of OA. Lets locate it with respect to O (you could also define it with respect
to A).

>>> P = O.locate_new('P', A.position_wrt(O) + (O.position_wrt(A) / 2))

Similarly define points Q, R and S as per the problem definitions.

>>> Q = A.locate_new('Q', B.position_wrt(A) / 2)

>>> R = B.locate_new('R', C.position_wrt(B) / 2)
>>> S = O.locate_new('R', C.position_wrt(O) / 2)

Now compute the vectors in the directions specified by PQ and SR.

>>> PQ = Q.position_wrt(P)
>>> SR = R.position_wrt(S)

Compute cross product

>>> PQ.cross(SR)
0

Since the cross product is a zero vector, the two vectors have to be parallel, thus proving that
PQ || SR.

Third product rule for Del operator

See

The Problem

Prove the third rule - ∇ · (f⃗v ) = f (∇ · ⃗v ) + ⃗v · (∇f )

Solution

Start with a coordinate system

>>> from sympy.vector import CoordSys3D, Del

>>> delop = Del()
>>> C = CoordSys3D('C')

1864 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The scalar field f and the measure numbers of the vector field ⃗v are all functions of the
coordinate variables of the coordinate system in general. Hence, define SymPy functions
that way.

>>> from sympy import symbols, Function

>>> v1, v2, v3, f = symbols('v1 v2 v3 f', cls=Function)

v1, v2 and v3 are the X, Y and Z components of the vector field respectively.
Define the vector field as vfield and the scalar field as sfield.

>>> vfield = v1(C.x, C.y, C.z)*C.i + v2(C.x, C.y, C.z)*C.j + v3(C.x, C.y, C.z)*C.k
>>> ffield = f(C.x, C.y, C.z)

Construct the expression for the LHS of the equation using Del().

>>> lhs = (delop.dot(ffield * vfield)).doit()

Similarly, the RHS would be defined.

>>> rhs = ((vfield.dot(delop(ffield))) + (ffield * (delop.dot(vfield)))).doit()

Now, to prove the product rule, we would just need to equate the expanded and simplified
versions of the lhs and the rhs, so that the SymPy expressions match.

>>> lhs.expand().simplify() == rhs.expand().doit().simplify()

True

Thus, the general form of the third product rule mentioned above can be proven using sympy.
vector.

5.43.2 Vector API

Essential Classes in sympy.vector (docstrings)

CoordSys3D

class sympy.vector.coordsysrect.CoordSys3D(name, location=None, ro-

tation_matrix=None, par-
ent=None, vector_names=None,
variable_names=None,
latex_vects=None,
pretty_vects=None, la-
tex_scalars=None,
pretty_scalars=None, transfor-
mation=None)
Represents a coordinate system in 3-D space.
__init__(name, location=None, rotation_matrix=None, parent=None,
vector_names=None, variable_names=None, latex_vects=None,
pretty_vects=None, latex_scalars=None, pretty_scalars=None, transfor-
mation=None)
The orientation/location parameters are necessary if this system is being defined at
a certain orientation or location wrt another.
Parameters name : str

5.43. Vector Module 1865

SymPy Documentation, Release 1.3

The name of the new CoordSys3D instance.

transformation : Lambda, Tuple, str
Transformation defined by transformation equations or chosen from
predefined ones.
location : Vector
The position vector of the new system’s origin wrt the parent in-
stance.
rotation_matrix : SymPy ImmutableMatrix
The rotation matrix of the new coordinate system with
respect to the parent. In other words, the output of
new_system.rotation_matrix(parent).
parent : CoordSys3D
The coordinate system wrt which the orientation/location (or both) is
being defined.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.
create_new(name, transformation, variable_names=None, vector_names=None)
Returns a CoordSys3D which is connected to self by transformation.
Parameters name : str
The name of the new CoordSys3D instance.
transformation : Lambda, Tuple, str
Transformation defined by transformation equations or chosen from
predefined ones.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> a = CoordSys3D('a')
>>> b = a.create_new('b', transformation='spherical')
>>> b.transformation_to_parent()
(b.r*sin(b.theta)*cos(b.phi), b.r*sin(b.phi)*sin(b.theta), b.r*cos(b.theta))
>>> b.transformation_from_parent()
(sqrt(a.x**2 + a.y**2 + a.z**2), acos(a.z/sqrt(a.x**2 + a.y**2 + a.z**2)),␣
,→atan2(a.y, a.x))

locate_new(name, position, vector_names=None, variable_names=None)

Returns a CoordSys3D with its origin located at the given position wrt this coordi-
nate system’s origin.

1866 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Parameters name : str

The name of the new CoordSys3D instance.
position : Vector
The position vector of the new system’s origin wrt this one.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> A = CoordSys3D('A')
>>> B = A.locate_new('B', 10 * A.i)
>>> B.origin.position_wrt(A.origin)
10*A.i

orient_new(name, orienters, location=None, vector_names=None, vari-

able_names=None)
Creates a new CoordSys3D oriented in the user-specified way with respect to this
system.
Please refer to the documentation of the orienter classes for more information about
the orientation procedure.
Parameters name : str
The name of the new CoordSys3D instance.
orienters : iterable/Orienter
An Orienter or an iterable of Orienters for orienting the new coordi-
nate system. If an Orienter is provided, it is applied to get the new
system. If an iterable is provided, the orienters will be applied in the
order in which they appear in the iterable.
location : Vector(optional)
The location of the new coordinate system’s origin wrt this system’s
origin. If not specified, the origins are taken to be coincident.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q0, q1, q2, q3 = symbols('q0 q1 q2 q3')
>>> N = CoordSys3D('N')

5.43. Vector Module 1867

SymPy Documentation, Release 1.3

Using an AxisOrienter

>>> from sympy.vector import AxisOrienter

>>> axis_orienter = AxisOrienter(q1, N.i + 2 * N.j)
>>> A = N.orient_new('A', (axis_orienter, ))

Using a BodyOrienter

>>> from sympy.vector import BodyOrienter

>>> body_orienter = BodyOrienter(q1, q2, q3, '123')
>>> B = N.orient_new('B', (body_orienter, ))

Using a SpaceOrienter

>>> from sympy.vector import SpaceOrienter

>>> space_orienter = SpaceOrienter(q1, q2, q3, '312')
>>> C = N.orient_new('C', (space_orienter, ))

Using a QuaternionOrienter

>>> from sympy.vector import QuaternionOrienter

>>> q_orienter = QuaternionOrienter(q0, q1, q2, q3)
>>> D = N.orient_new('D', (q_orienter, ))

orient_new_axis(name, angle, axis, location=None, vector_names=None, vari-

able_names=None)
Axis rotation is a rotation about an arbitrary axis by some angle. The angle is sup-
plied as a SymPy expr scalar, and the axis is supplied as a Vector.
Parameters name : string
The name of the new coordinate system
angle : Expr
The angle by which the new system is to be rotated
axis : Vector
The axis around which the rotation has to be performed
location : Vector(optional)
The location of the new coordinate system’s origin wrt this system’s
origin. If not specified, the origins are taken to be coincident.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = CoordSys3D('N')
>>> B = N.orient_new_axis('B', q1, N.i + 2 * N.j)

1868 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

orient_new_body(name, angle1, angle2, angle3, rotation_order, location=None,

vector_names=None, variable_names=None)
Body orientation takes this coordinate system through three successive simple ro-
tations.
Body fixed rotations include both Euler Angles and Tait-Bryan Angles, see http://en.
wikipedia.org/wiki/Euler_angles.
Parameters name : string
The name of the new coordinate system
angle1, angle2, angle3 : Expr
Three successive angles to rotate the coordinate system by
rotation_order : string
String defining the order of axes for rotation
location : Vector(optional)
The location of the new coordinate system’s origin wrt this system’s
origin. If not specified, the origins are taken to be coincident.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q1, q2, q3 = symbols('q1 q2 q3')
>>> N = CoordSys3D('N')

A ‘Body’ fixed rotation is described by three angles and three body-fixed rotation
axes. To orient a coordinate system D with respect to N, each sequential rotation is
always about the orthogonal unit vectors fixed to D. For example, a ‘123’ rotation will
specify rotations about N.i, then D.j, then D.k. (Initially, D.i is same as N.i) Therefore,

>>> D = N.orient_new_body('D', q1, q2, q3, '123')

is same as

>>> D = N.orient_new_axis('D', q1, N.i)

>>> D = D.orient_new_axis('D', q2, D.j)
>>> D = D.orient_new_axis('D', q3, D.k)

Acceptable rotation orders are of length 3, expressed in XYZ or 123, and cannot
have a rotation about about an axis twice in a row.

>>> B = N.orient_new_body('B', q1, q2, q3, '123')

>>> B = N.orient_new_body('B', q1, q2, 0, 'ZXZ')
>>> B = N.orient_new_body('B', 0, 0, 0, 'XYX')

5.43. Vector Module 1869

SymPy Documentation, Release 1.3

orient_new_quaternion(name, q0, q1, q2, q3, location=None, vec-

tor_names=None, variable_names=None)
Quaternion orientation orients the new CoordSys3D with Quaternions, defined as a
finite rotation about lambda, a unit vector, by some amount theta.
This orientation is described by four parameters:
q0 = cos(theta/2)
q1 = lambda_x sin(theta/2)
q2 = lambda_y sin(theta/2)
q3 = lambda_z sin(theta/2)
Quaternion does not take in a rotation order.
Parameters name : string
The name of the new coordinate system
q0, q1, q2, q3 : Expr
The quaternions to rotate the coordinate system by
location : Vector(optional)
The location of the new coordinate system’s origin wrt this system’s
origin. If not specified, the origins are taken to be coincident.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q0, q1, q2, q3 = symbols('q0 q1 q2 q3')
>>> N = CoordSys3D('N')
>>> B = N.orient_new_quaternion('B', q0, q1, q2, q3)

orient_new_space(name, angle1, angle2, angle3, rotation_order, location=None,

vector_names=None, variable_names=None)
Space rotation is similar to Body rotation, but the rotations are applied in the oppo-
site order.
Parameters name : string
The name of the new coordinate system
angle1, angle2, angle3 : Expr
Three successive angles to rotate the coordinate system by
rotation_order : string
String defining the order of axes for rotation
location : Vector(optional)

1870 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

The location of the new coordinate system’s origin wrt this system’s
origin. If not specified, the origins are taken to be coincident.
vector_names, variable_names : iterable(optional)
Iterables of 3 strings each, with custom names for base vectors and
base scalars of the new system respectively. Used for simple str print-
ing.
See also:

CoordSys3D.orient_new_body (page 1868) method to orient via Euler angles

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q1, q2, q3 = symbols('q1 q2 q3')
>>> N = CoordSys3D('N')

To orient a coordinate system D with respect to N, each sequential rotation is al-

ways about N’s orthogonal unit vectors. For example, a ‘123’ rotation will specify
rotations about N.i, then N.j, then N.k. Therefore,

>>> D = N.orient_new_space('D', q1, q2, q3, '312')

is same as

>>> B = N.orient_new_axis('B', q1, N.i)

>>> C = B.orient_new_axis('C', q2, N.j)
>>> D = C.orient_new_axis('D', q3, N.k)

position_wrt(other)
Returns the position vector of the origin of this coordinate system with respect to
another Point/CoordSys3D.
Parameters other : Point/CoordSys3D
If other is a Point, the position of this system’s origin wrt it is re-
turned. If its an instance of CoordSyRect, the position wrt its origin
is returned.

Examples

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> N1 = N.locate_new('N1', 10 * N.i)
>>> N.position_wrt(N1)
(-10)*N.i

rotation_matrix(other)
Returns the direction cosine matrix(DCM), also known as the ‘rotation matrix’ of
this coordinate system with respect to another system.
If v_a is a vector defined in system ‘A’ (in matrix format) and v_b is the same vector
defined in system ‘B’, then v_a = A.rotation_matrix(B) * v_b.

5.43. Vector Module 1871

SymPy Documentation, Release 1.3

A SymPy Matrix is returned.

Parameters other : CoordSys3D
The system which the DCM is generated to.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = CoordSys3D('N')
>>> A = N.orient_new_axis('A', q1, N.i)
>>> N.rotation_matrix(A)
Matrix([
[1, 0, 0],
[0, cos(q1), -sin(q1)],
[0, sin(q1), cos(q1)]])

scalar_map(other)
Returns a dictionary which expresses the coordinate variables (base scalars) of this
frame in terms of the variables of otherframe.
Parameters otherframe : CoordSys3D
The other system to map the variables to.

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import Symbol
>>> A = CoordSys3D('A')
>>> q = Symbol('q')
>>> B = A.orient_new_axis('B', q, A.k)
>>> A.scalar_map(B)
{A.x: B.x*cos(q) - B.y*sin(q), A.y: B.x*sin(q) + B.y*cos(q), A.z: B.z}

Vector

class sympy.vector.vector.Vector
Super class for all Vector classes. Ideally, neither this class nor any of its subclasses
should be instantiated by the user.
components
Returns the components of this vector in the form of a Python dictionary mapping
BaseVector instances to the corresponding measure numbers.

Examples

1872 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D

>>> C = CoordSys3D('C')
>>> v = 3*C.i + 4*C.j + 5*C.k
>>> v.components
{C.i: 3, C.j: 4, C.k: 5}

cross(other)
Returns the cross product of this Vector with another Vector or Dyadic instance. The
cross product is a Vector, if ‘other’ is a Vector. If ‘other’ is a Dyadic, this returns a
Dyadic instance.
Parameters other: Vector/Dyadic
The Vector or Dyadic we are crossing with.

Examples

>>> from sympy.vector import CoordSys3D

>>> C = CoordSys3D('C')
>>> C.i.cross(C.j)
C.k
>>> C.i ^ C.i
0
>>> v = 3*C.i + 4*C.j + 5*C.k
>>> v ^ C.i
5*C.j + (-4)*C.k
>>> d = C.i.outer(C.i)
>>> C.j.cross(d)
(-1)*(C.k|C.i)

dot(other)
Returns the dot product of this Vector, either with another Vector, or a Dyadic, or
a Del operator. If ‘other’ is a Vector, returns the dot product scalar (Sympy expres-
sion). If ‘other’ is a Dyadic, the dot product is returned as a Vector. If ‘other’ is an
instance of Del, returns the directional derivative operator as a Python function. If
this function is applied to a scalar expression, it returns the directional derivative
of the scalar field wrt this Vector.
Parameters other: Vector/Dyadic/Del
The Vector or Dyadic we are dotting with, or a Del operator .

Examples

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> C.i.dot(C.j)
0
>>> C.i & C.i
1
>>> v = 3*C.i + 4*C.j + 5*C.k
>>> v.dot(C.k)
5
(continues on next page)

5.43. Vector Module 1873

SymPy Documentation, Release 1.3

(continued from previous page)

>>> (C.i & delop)(C.x*C.y*C.z)
C.y*C.z
>>> d = C.i.outer(C.i)
>>> C.i.dot(d)
C.i

magnitude()
Returns the magnitude of this vector.
normalize()
Returns the normalized version of this vector.
outer(other)
Returns the outer product of this vector with another, in the form of a Dyadic in-
stance.
Parameters other : Vector
The Vector with respect to which the outer product is to be computed.

Examples

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> N.i.outer(N.j)
(N.i|N.j)

projection(other, scalar=False)
Returns the vector or scalar projection of the ‘other’ on ‘self’.

Examples

>>> from sympy.vector.coordsysrect import CoordSys3D

>>> from sympy.vector.vector import Vector, BaseVector
>>> C = CoordSys3D('C')
>>> i, j, k = C.base_vectors()
>>> v1 = i + j + k
>>> v2 = 3*i + 4*j
>>> v1.projection(v2)
7/3*C.i + 7/3*C.j + 7/3*C.k
>>> v1.projection(v2, scalar=True)
7/3

separate()
The constituents of this vector in different coordinate systems, as per its definition.
Returns a dict mapping each CoordSys3D to the corresponding constituent Vector.

Examples

1874 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D

>>> R1 = CoordSys3D('R1')
>>> R2 = CoordSys3D('R2')
>>> v = R1.i + R2.i
>>> v.separate() == {R1: R1.i, R2: R2.i}
True

to_matrix(system)
Returns the matrix form of this vector with respect to the specified coordinate sys-
tem.
Parameters system : CoordSys3D
The system wrt which the matrix form is to be computed

Examples

>>> from sympy.vector import CoordSys3D

>>> C = CoordSys3D('C')
>>> from sympy.abc import a, b, c
>>> v = a*C.i + b*C.j + c*C.k
>>> v.to_matrix(C)
Matrix([
[a],
[b],
[c]])

Dyadic

class sympy.vector.dyadic.Dyadic
Super class for all Dyadic-classes.

References

[R600], [R601]
components
Returns the components of this dyadic in the form of a Python dictionary mapping
BaseDyadic instances to the corresponding measure numbers.
cross(other)
Returns the cross product between this Dyadic, and a Vector, as a Vector instance.
Parameters other : Vector
The Vector that we are crossing this Dyadic with

Examples

5.43. Vector Module 1875

SymPy Documentation, Release 1.3

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> d = N.i.outer(N.i)
>>> d.cross(N.j)
(N.i|N.k)

dot(other)
Returns the dot product(also called inner product) of this Dyadic, with another
Dyadic or Vector. If ‘other’ is a Dyadic, this returns a Dyadic. Else, it returns a
Vector (unless an error is encountered).
Parameters other : Dyadic/Vector
The other Dyadic or Vector to take the inner product with

Examples

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> D1 = N.i.outer(N.j)
>>> D2 = N.j.outer(N.j)
>>> D1.dot(D2)
(N.i|N.j)
>>> D1.dot(N.j)
N.i

to_matrix(system, second_system=None)
Returns the matrix form of the dyadic with respect to one or two coordinate systems.
Parameters system : CoordSys3D
The coordinate system that the rows and columns of the matrix cor-
respond to. If a second system is provided, this only corresponds to
the rows of the matrix.
second_system : CoordSys3D, optional, default=None
The coordinate system that the columns of the matrix correspond to.

Examples

>>> from sympy.vector import CoordSys3D

>>> N = CoordSys3D('N')
>>> v = N.i + 2*N.j
>>> d = v.outer(N.i)
>>> d.to_matrix(N)
Matrix([
[1, 0, 0],
[2, 0, 0],
[0, 0, 0]])
>>> from sympy import Symbol
>>> q = Symbol('q')
>>> P = N.orient_new_axis('P', q, N.k)
>>> d.to_matrix(N, P)
Matrix([
(continues on next page)

1876 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

[ cos(q), -sin(q), 0],
[2*cos(q), -2*sin(q), 0],
[ 0, 0, 0]])

Del

class sympy.vector.deloperator.Del
Represents the vector differential operator, usually represented in mathematical expres-
sions as the ‘nabla’ symbol.
cross(vect, doit=False)
Represents the cross product between this operator and a given vector - equal to
the curl of the vector field.
Parameters vect : Vector
The vector whose curl is to be calculated.
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> v = C.x*C.y*C.z * (C.i + C.j + C.k)
>>> delop.cross(v, doit = True)
(-C.x*C.y + C.x*C.z)*C.i + (C.x*C.y - C.y*C.z)*C.j +
(-C.x*C.z + C.y*C.z)*C.k
>>> (delop ^ C.i).doit()
0

dot(vect, doit=False)
Represents the dot product between this operator and a given vector - equal to the
divergence of the vector field.
Parameters vect : Vector
The vector whose divergence is to be calculated.
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, Del

>>> delop = Del()
>>> C = CoordSys3D('C')
(continues on next page)

5.43. Vector Module 1877

SymPy Documentation, Release 1.3

(continued from previous page)

>>> delop.dot(C.x*C.i)
Derivative(C.x, C.x)
>>> v = C.x*C.y*C.z * (C.i + C.j + C.k)
>>> (delop & v).doit()
C.x*C.y + C.x*C.z + C.y*C.z

gradient(scalar_field, doit=False)
Returns the gradient of the given scalar field, as a Vector instance.
Parameters scalar_field : SymPy expression
The scalar field to calculate the gradient of.
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, Del

>>> C = CoordSys3D('C')
>>> delop = Del()
>>> delop.gradient(9)
0
>>> delop(C.x*C.y*C.z).doit()
C.y*C.z*C.i + C.x*C.z*C.j + C.x*C.y*C.k

Orienter classes (docstrings)

Orienter

class sympy.vector.orienters.Orienter
Super-class for all orienter classes.
rotation_matrix()
The rotation matrix corresponding to this orienter instance.

AxisOrienter

class sympy.vector.orienters.AxisOrienter(angle, axis)

Class to denote an axis orienter.
__init__(angle, axis)
Axis rotation is a rotation about an arbitrary axis by some angle. The angle is sup-
plied as a SymPy expr scalar, and the axis is supplied as a Vector.
Parameters angle : Expr
The angle by which the new system is to be rotated
axis : Vector
The axis around which the rotation has to be performed

1878 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q1 = symbols('q1')
>>> N = CoordSys3D('N')
>>> from sympy.vector import AxisOrienter
>>> orienter = AxisOrienter(q1, N.i + 2 * N.j)
>>> B = N.orient_new('B', (orienter, ))

rotation_matrix(system)
The rotation matrix corresponding to this orienter instance.
Parameters system : CoordSys3D
The coordinate system wrt which the rotation matrix is to be com-
puted

BodyOrienter

class sympy.vector.orienters.BodyOrienter(angle1, angle2, angle3, rot_order)

Class to denote a body-orienter.
__init__(angle1, angle2, angle3, rot_order)
Body orientation takes this coordinate system through three successive simple ro-
tations.
Body fixed rotations include both Euler Angles and Tait-Bryan Angles, see http://en.
wikipedia.org/wiki/Euler_angles.
Parameters angle1, angle2, angle3 : Expr
Three successive angles to rotate the coordinate system by
rotation_order : string
String defining the order of axes for rotation

Examples

>>> from sympy.vector import CoordSys3D, BodyOrienter

>>> from sympy import symbols
>>> q1, q2, q3 = symbols('q1 q2 q3')
>>> N = CoordSys3D('N')

A ‘Body’ fixed rotation is described by three angles and three body-fixed rotation
axes. To orient a coordinate system D with respect to N, each sequential rotation is
always about the orthogonal unit vectors fixed to D. For example, a ‘123’ rotation will
specify rotations about N.i, then D.j, then D.k. (Initially, D.i is same as N.i) Therefore,

>>> body_orienter = BodyOrienter(q1, q2, q3, '123')

>>> D = N.orient_new('D', (body_orienter, ))

is same as

5.43. Vector Module 1879

SymPy Documentation, Release 1.3

>>> from sympy.vector import AxisOrienter

>>> axis_orienter1 = AxisOrienter(q1, N.i)
>>> D = N.orient_new('D', (axis_orienter1, ))
>>> axis_orienter2 = AxisOrienter(q2, D.j)
>>> D = D.orient_new('D', (axis_orienter2, ))
>>> axis_orienter3 = AxisOrienter(q3, D.k)
>>> D = D.orient_new('D', (axis_orienter3, ))

Acceptable rotation orders are of length 3, expressed in XYZ or 123, and cannot
have a rotation about about an axis twice in a row.
>>> body_orienter1 = BodyOrienter(q1, q2, q3, '123')
>>> body_orienter2 = BodyOrienter(q1, q2, 0, 'ZXZ')
>>> body_orienter3 = BodyOrienter(0, 0, 0, 'XYX')

SpaceOrienter

class sympy.vector.orienters.SpaceOrienter(angle1, angle2, angle3, rot_order)

Class to denote a space-orienter.
__init__(angle1, angle2, angle3, rot_order)
Space rotation is similar to Body rotation, but the rotations are applied in the oppo-
site order.
Parameters angle1, angle2, angle3 : Expr
Three successive angles to rotate the coordinate system by
rotation_order : string
String defining the order of axes for rotation
See also:

BodyOrienter (page 1879) Orienter to orient systems wrt Euler angles.

Examples

>>> from sympy.vector import CoordSys3D, SpaceOrienter

>>> from sympy import symbols
>>> q1, q2, q3 = symbols('q1 q2 q3')
>>> N = CoordSys3D('N')

To orient a coordinate system D with respect to N, each sequential rotation is al-

ways about N’s orthogonal unit vectors. For example, a ‘123’ rotation will specify
rotations about N.i, then N.j, then N.k. Therefore,
>>> space_orienter = SpaceOrienter(q1, q2, q3, '312')
>>> D = N.orient_new('D', (space_orienter, ))

is same as
>>> from sympy.vector import AxisOrienter
>>> axis_orienter1 = AxisOrienter(q1, N.i)
>>> B = N.orient_new('B', (axis_orienter1, ))
(continues on next page)

1880 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

>>> axis_orienter2 = AxisOrienter(q2, N.j)
>>> C = B.orient_new('C', (axis_orienter2, ))
>>> axis_orienter3 = AxisOrienter(q3, N.k)
>>> D = C.orient_new('C', (axis_orienter3, ))

QuaternionOrienter

class sympy.vector.orienters.QuaternionOrienter(angle1, angle2, angle3,

rot_order)
Class to denote a quaternion-orienter.
__init__(angle1, angle2, angle3, rot_order)
Quaternion orientation orients the new CoordSys3D with Quaternions, defined as a
finite rotation about lambda, a unit vector, by some amount theta.
This orientation is described by four parameters:
q0 = cos(theta/2)
q1 = lambda_x sin(theta/2)
q2 = lambda_y sin(theta/2)
q3 = lambda_z sin(theta/2)
Quaternion does not take in a rotation order.
Parameters q0, q1, q2, q3 : Expr
The quaternions to rotate the coordinate system by

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import symbols
>>> q0, q1, q2, q3 = symbols('q0 q1 q2 q3')
>>> N = CoordSys3D('N')
>>> from sympy.vector import QuaternionOrienter
>>> q_orienter = QuaternionOrienter(q0, q1, q2, q3)
>>> B = N.orient_new('B', (q_orienter, ))

Essential Functions in sympy.vector (docstrings)

matrix_to_vector

sympy.vector.matrix_to_vector(matrix, system)
Converts a vector in matrix form to a Vector instance.
It is assumed that the elements of the Matrix represent the measure numbers of the
components of the vector along basis vectors of ‘system’.
Parameters matrix : SymPy Matrix, Dimensions: (3, 1)
The matrix to be converted to a vector

5.43. Vector Module 1881

SymPy Documentation, Release 1.3

system : CoordSys3D
The coordinate system the vector is to be defined in

Examples

>>> from sympy import ImmutableMatrix as Matrix

>>> m = Matrix([1, 2, 3])
>>> from sympy.vector import CoordSys3D, matrix_to_vector
>>> C = CoordSys3D('C')
>>> v = matrix_to_vector(m, C)
>>> v
C.i + 2*C.j + 3*C.k
>>> v.to_matrix(C) == m
True

express

sympy.vector.express(expr, system, system2=None, variables=False)

Global function for ‘express’ functionality.
Re-expresses a Vector, Dyadic or scalar(sympyfiable) in the given coordinate system.
If ‘variables’ is True, then the coordinate variables (base scalars) of other coordinate
systems present in the vector/scalar field or dyadic are also substituted in terms of the
base scalars of the given system.
Parameters expr : Vector/Dyadic/scalar(sympyfiable)
The expression to re-express in CoordSys3D ‘system’
system: CoordSys3D
The coordinate system the expr is to be expressed in
system2: CoordSys3D
The other coordinate system required for re-expression (only for a
Dyadic Expr)
variables : boolean
Specifies whether to substitute the coordinate variables present in
expr, in terms of those of parameter system

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy import Symbol, cos, sin
>>> N = CoordSys3D('N')
>>> q = Symbol('q')
>>> B = N.orient_new_axis('B', q, N.k)
>>> from sympy.vector import express
>>> express(B.i, N)
(cos(q))*N.i + (sin(q))*N.j
>>> express(N.x, B, variables=True)
(continues on next page)

1882 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

(continued from previous page)

B.x*cos(q) - B.y*sin(q)
>>> d = N.i.outer(N.i)
>>> express(d, B, N) == (cos(q))*(B.i|N.i) + (-sin(q))*(B.j|N.i)
True

curl

sympy.vector.curl(vect, coord_sys=None, doit=True)

Returns the curl of a vector field computed wrt the base scalars of the given coordinate
system.
Parameters vect : Vector
The vector operand
coord_sys : CoordSys3D
The coordinate system to calculate the gradient in. Deprecated since
version 1.1
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, curl

>>> R = CoordSys3D('R')
>>> v1 = R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> curl(v1)
0
>>> v2 = R.x*R.y*R.z*R.i
>>> curl(v2)
R.x*R.y*R.j + (-R.x*R.z)*R.k

divergence

sympy.vector.divergence(vect, coord_sys=None, doit=True)

Returns the divergence of a vector field computed wrt the base scalars of the given
coordinate system.
Parameters vector : Vector
The vector operand
coord_sys : CoordSys3D
The coordinate system to calculate the gradient in Deprecated since
version 1.1
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

5.43. Vector Module 1883

SymPy Documentation, Release 1.3

Examples

>>> from sympy.vector import CoordSys3D, divergence

>>> R = CoordSys3D('R')
>>> v1 = R.x*R.y*R.z * (R.i+R.j+R.k)

>>> divergence(v1)
R.x*R.y + R.x*R.z + R.y*R.z
>>> v2 = 2*R.y*R.z*R.j
>>> divergence(v2)
2*R.z

gradient

sympy.vector.gradient(scalar_field, coord_sys=None, doit=True)

Returns the vector gradient of a scalar field computed wrt the base scalars of the given
coordinate system.
Parameters scalar_field : SymPy Expr
The scalar field to compute the gradient of
coord_sys : CoordSys3D
The coordinate system to calculate the gradient in Deprecated since
version 1.1
doit : bool
If True, the result is returned after calling .doit() on each component.
Else, the returned expression contains Derivative instances

Examples

>>> from sympy.vector import CoordSys3D, gradient

>>> R = CoordSys3D('R')
>>> s1 = R.x*R.y*R.z
>>> gradient(s1)
R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k
>>> s2 = 5*R.x**2*R.z
>>> gradient(s2)
10*R.x*R.z*R.i + 5*R.x**2*R.k

is_conservative

sympy.vector.is_conservative(field)
Checks if a field is conservative.
Parameters field : Vector
The field to check for conservative property

1884 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy.vector import is_conservative
>>> R = CoordSys3D('R')
>>> is_conservative(R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k)
True
>>> is_conservative(R.z*R.j)
False

is_solenoidal

sympy.vector.is_solenoidal(field)
Checks if a field is solenoidal.
Parameters field : Vector
The field to check for solenoidal property

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy.vector import is_solenoidal
>>> R = CoordSys3D('R')
>>> is_solenoidal(R.y*R.z*R.i + R.x*R.z*R.j + R.x*R.y*R.k)
True
>>> is_solenoidal(R.y * R.j)
False

scalar_potential

sympy.vector.scalar_potential(field, coord_sys)
Returns the scalar potential function of a field in a given coordinate system (without the
added integration constant).
Parameters field : Vector
The vector field whose scalar potential function is to be calculated
coord_sys : CoordSys3D
The coordinate system to do the calculation in

Examples

>>> from sympy.vector import CoordSys3D

>>> from sympy.vector import scalar_potential, gradient
>>> R = CoordSys3D('R')
>>> scalar_potential(R.k, R) == R.z
True
>>> scalar_field = 2*R.x**2*R.y*R.z
(continues on next page)

5.43. Vector Module 1885

SymPy Documentation, Release 1.3

(continued from previous page)

>>> grad_field = gradient(scalar_field)
>>> scalar_potential(grad_field, R)
2*R.x**2*R.y*R.z

scalar_potential_difference

sympy.vector.scalar_potential_difference(field, coord_sys, point1, point2)

Returns the scalar potential difference between two points in a certain coordinate sys-
tem, wrt a given field.
If a scalar field is provided, its values at the two points are considered. If a conservative
vector field is provided, the values of its scalar potential function at the two points are
used.
Returns (potential at point2) - (potential at point1)
The position vectors of the two Points are calculated wrt the origin of the coordinate
system provided.
Parameters field : Vector/Expr
The field to calculate wrt
coord_sys : CoordSys3D
The coordinate system to do the calculations in
point1 : Point
The initial Point in given coordinate system
position2 : Point
The second Point in the given coordinate system

Examples

>>> from sympy.vector import CoordSys3D, Point

>>> from sympy.vector import scalar_potential_difference
>>> R = CoordSys3D('R')
>>> P = R.origin.locate_new('P', R.x*R.i + R.y*R.j + R.z*R.k)
>>> vectfield = 4*R.x*R.y*R.i + 2*R.x**2*R.j
>>> scalar_potential_difference(vectfield, R, R.origin, P)
2*R.x**2*R.y
>>> Q = R.origin.locate_new('O', 3*R.i + R.j + 2*R.k)
>>> scalar_potential_difference(vectfield, R, P, Q)
-2*R.x**2*R.y + 18

1886 Chapter 5. SymPy Modules Reference

 SymPy Documentation, Release 1.3

5.43.3 References for Vector

5.44 Contributions to docs

All contributions are welcome. If you’d like to improve something, look into the sources if
they contain the information you need (if not, please fix them), otherwise the documentation
generation needs to be improved (look in the doc/ directory).

5.44. Contributions to docs 1887

SymPy Documentation, Release 1.3

1888 Chapter 5. SymPy Modules Reference

 CHAPTER

SIX

SYMPY SPECIAL TOPICS

6.1 Introduction

The purpose of this collection of documents is to provide users of SymPy with topics which
are not strictly tutorial or are longer than tutorials and tests. The documents will hopefully
fill a gap as SymPy matures and users find more ways to show how SymPy can be used in
more advanced topics.

6.2 Finite Difference Approximations to Derivatives

6.2.1 Introduction

Finite difference approximations to derivatives is quite important in numerical analysis and in

computational physics. In this tutorial we show how to use SymPy to compute approximations
of varying accuracy. The hope is that these notes could be useful for the practicing researcher
who is developing code in some language and needs to be able to efficiently generate finite
difference formulae for various approximations.
In order to establish notation, we first state that we envision that there exists a continuous
function F of a single variable x, with F having as many derivatives as desired. We sample x
values uniformly at points along the real line separated by h. In most cases we want h to be
small in some sense. F(x) may be expanded about some point x0 via the usual Taylor series
expansion. Let x = x0 + h. Then the Taylor expansion is

( dF ) 1 ( d2 F ) 1 ( d3 F )
F (x0 + h) = F (x0 ) + ∗ h + ∗ h2
+ ∗ h3 + ...
dx x0 2! dx2 x0 3! dx3 x0
In order to simplify the notation, we now define a set of coefficients cn , where

1 ( dn F )
cn := .
n! dxn x0
So now our series has the form:

F (x0 + h) = F (x0 ) + c1 ∗ h + c2 ∗ h2 + c3 ∗ h3 + ...

In the following we will only use a finite grid of values xi with i running from 1, ..., N and the
corresponding values of our function F at these grid points denoted by Fi . So the problem is
how to generate approximate values for the derivatives of F with the constraint that we use
a subset of the finite set of pairs (xi , Fi ) of size N.

1889
SymPy Documentation, Release 1.3

What follows are manipulations using SymPy to formulate approximations for derivatives of
a given order and to assess its accuracy. First, we use SymPy to derive the approximations
by using a rather brute force method frequently covered in introductory treatments. Later
we shall make use of other SymPy functions which get the job done with more efficiency.

6.2.2 A Direct Method Using SymPy Matrices

If we let x0 = xi , evaluate the series at xi+1 = xi + h and truncate all terms above O(h1 ) we can
solve for the single coefficient c1 and obtain an approximation to the first derivative:
( dF ) Fi+1 − Fi
≈ + O(h)
dx x0 h
where the O(h) refers to the lowest order term in the series in h. This establishes that the
derivative approximation is of first order accuracy. Put another way, if we decide that we can
only use the two pairs (xi , Fi ) and (xi+1 , Fi+1 ) we obtain a “first order accurate” derivative.
In addition to (xi , Fi ) we next use the two points (xi+1 , Fi+1 ) and (xi+2 , Fi+2 ). Then we have two
equations:
1 1
Fi+1 = Fi + c1 ∗ h + ∗ c2 ∗ h2 + ∗ c3 ∗ h3 + ...
2 3!
1 1
Fi+2 = Fi + c1 ∗ (2h) +
∗ c2 ∗ (2h)2 + ∗ c3 ∗ (2h)3 + ...
2 3!
If we again want to find the first derivative (c1 ), we can do that by eliminating the term in-
volving c2 from the two equations. We show how to do it using SymPy.

>>> from __future__ import print_function

>>> from sympy import *
>>> x, x0, h = symbols('x, x_0, h')
>>> Fi, Fip1, Fip2 = symbols('F_{i}, F_{i+1}, F_{i+2}')
>>> n = 3 # there are the coefficients c_0=Fi, c_1=dF/dx, c_2=d**2F/dx**2
>>> c = symbols('c:3')
>>> def P(x, x0, c, n):
... return sum( ((1/factorial(i))*c[i] * (x-x0)**i for i in range(n)) )

Vector of right hand sides:

>>> R = Matrix([[Fi], [Fip1], [Fip2]])

Now we make a matrix consisting of the coefficients of the c_i in the nth degree polynomial P.
Coefficients of ci evaluated at xi :

>>> m11 = P(x0 , x0, c, n).diff(c[0])

>>> m12 = P(x0 , x0, c, n).diff(c[1])
>>> m13 = P(x0 , x0, c, n).diff(c[2])

Coefficients of ci evaluated at xi + h:

>>> m21 = P(x0+h, x0, c, n).diff(c[0])

>>> m22 = P(x0+h, x0, c, n).diff(c[1])
>>> m23 = P(x0+h, x0, c, n).diff(c[2])

Coefficients of ci evaluated at xi + 2 ∗ h:

1890 Chapter 6. SymPy Special Topics

 SymPy Documentation, Release 1.3

>>> m31 = P(x0+2*h, x0, c, n).diff(c[0])

>>> m32 = P(x0+2*h, x0, c, n).diff(c[1])
>>> m33 = P(x0+2*h, x0, c, n).diff(c[2])

Matrix of the coeffcients is 3x3 in this case:

>>> M = Matrix([[m11, m12, m13], [m21, m22, m23], [m31, m32, m33]])

Matrix form of the three equations for the ci is M*X = R:

The solution is obtained by directly inverting the 3x3 matrix M:

>>> X = M.inv() * R

Note that all three coefficients make up the solution. The desired first derivative is coefficient
c1 which is X[1].

>>> print(together(X[1]))
(4*F_{i+1} - F_{i+2} - 3*F_{i})/(2*h)

It is instructive to compute another three-point approximation to the first derivative, except

centering the approximation at xi and thus using points at xi−1 , xi , and xi+1 . So here is how
this can be done using the ‘brute force’ method:

>>> from __future__ import print_function

>>> from sympy import *
>>> x, x0, h = symbols('x, x_i, h')
>>> Fi, Fim1, Fip1 = symbols('F_{i}, F_{i-1}, F_{i+1}')
>>> n = 3 # there are the coefficients c_0=Fi, c_1=dF/h, c_2=d**2F/h**2
>>> c = symbols('c:3')
>>> # define a polynomial of degree n
>>> def P(x, x0, c, n):
... return sum( ((1/factorial(i))*c[i] * (x-x0)**i for i in range(n)) )
>>> # now we make a matrix consisting of the coefficients
>>> # of the c_i in the nth degree polynomial P
>>> # coefficients of c_i evaluated at x_i
>>> m11 = P(x0 , x0, c, n).diff(c[0])
>>> m12 = P(x0 , x0, c, n).diff(c[1])
>>> m13 = P(x0 , x0, c, n).diff(c[2])
>>> # coefficients of c_i evaluated at x_i - h
>>> m21 = P(x0-h, x0, c, n).diff(c[0])
>>> m22 = P(x0-h, x0, c, n).diff(c[1])
>>> m23 = P(x0-h, x0, c, n).diff(c[2])
>>> # coefficients of c_i evaluated at x_i + h
>>> m31 = P(x0+h, x0, c, n).diff(c[0])
>>> m32 = P(x0+h, x0, c, n).diff(c[1])
>>> m33 = P(x0+h, x0, c, n).diff(c[2])
>>> # matrix of the coeffcients is 3x3 in this case
>>> M = Matrix([[m11, m12, m13], [m21, m22, m23], [m31, m32, m33]])

Now that we have the matrix of coefficients we next form the right-hand-side and solve by
inverting M :

>>> # matrix of the function values...actually a vector of right hand sides

>>> R = Matrix([[Fi], [Fim1], [Fip1]])
>>> # matrix form of the three equations for the c_i is M*X = R
>>> # solution directly inverting the 3x3 matrix M:
(continues on next page)

6.2. Finite Difference Approximations to Derivatives 1891

SymPy Documentation, Release 1.3

(continued from previous page)

>>> X = M.inv() * R
>>> # note that all three coefficients make up the solution
>>> # the first derivative is coefficient c_1 which is X[1].
>>> print(”The second-order accurate approximation for the first derivative is: ”)
The second-order accurate approximation for the first derivative is:
>>> print(together(X[1]))
(F_{i+1} - F_{i-1})/(2*h)

These two examples serve to show how one can directly find second order accurate first
derivatives using SymPy. The first example uses values of x and F at all three points xi , xi+1 ,
and xi+2 whereas the second example only uses values of x at the two points xi−1 and xi+1 and
thus is a bit more efficient.
From these two simple examples a general rule is that if one wants a first derivative to be
accurate to O(hn ) then one needs n+1 function values in the approximating polynomial (here
provided via the function P (x, x0, c, n)).
Now let’s assess the question of the accuracy of the centered difference result to see how we
determine that it is really second order. To do this we take the result for dF /dx and substitute
in the polynomial expansion for a higher order polynomial and see what we get. To this end,
we make a set of eight coefficients d and use them to perform the check:

>>> d = symbols('c:8')
>>> dfdxcheck = (P(x0+h, x0, d, 8) - P(x0-h, x0, d, 8))/(2*h)
>>> print(simplify(dfdxcheck)) # so the appropriate cancellation of terms involving␣
,→`h` happens

c1 + c3*h**2/6 + c5*h**4/120 + c7*h**6/5040

Thus we see that indeed the derivative is c1 with the next term in the series of order h2 .
However, it can quickly become rather tedious to generalize the direct method as presented
above when attempting to generate a derivative approximation to high order, such as 6 or 8
although the method certainly works and using the present method is certainly less tedious
than performing the calculations by hand.
As we have seen in the discussion above, the simple centered approximation for the first
derivative only uses two point values of the (xi , Fi ) pairs. This works fine until one encounters
the last point in the domain, say at i = N . Since our centered derivative approximation would
use data at the point (xN +1 , FN +1 ) we see that the derivative formula will not work. So, what to
do? Well, a simple way to handle this is to devise a different formula for this last point which
uses points for which we do have values. This is the so-called backward difference formula.
To obtain it, we can use the same direct approach, except now us the three points (xN , FN ),
(xN −1 , FN −1 ), and (xN −2 , FN −2 ) and center the approximation at (xN , FN ). Here is how it can be
done using SymPy:

>>> from __future__ import print_function

>>> from sympy import *
>>> x, xN, h = symbols('x, x_N, h')
>>> FN, FNm1, FNm2 = symbols('F_{N}, F_{N-1}, F_{N-2}')
>>> n = 8 # there are the coefficients c_0=Fi, c_1=dF/h, c_2=d**2F/h**2
>>> c = symbols('c:8')
>>> # define a polynomial of degree d
>>> def P(x, x0, c, n):
... return sum( ((1/factorial(i))*c[i] * (x-x0)**i for i in range(n)) )

Now we make a matrix consisting of the coefficients of the ci in the dth degree polynomial P
coefficients of ci evaluated at xi , xi−1 , and xi+1 :

1892 Chapter 6. SymPy Special Topics

 SymPy Documentation, Release 1.3

>>> m11 = P(xN , xN, c, n).diff(c[0])

>>> m12 = P(xN, xN, c, n).diff(c[1])
>>> m13 = P(xN , xN, c, n).diff(c[2])
>>> # coefficients of c_i evaluated at x_i - h
>>> m21 = P(xN-h, xN, c, n).diff(c[0])
>>> m22 = P(xN-h, xN, c, n).diff(c[1])
>>> m23 = P(xN-h, xN, c, n).diff(c[2])
>>> # coefficients of c_i evaluated at x_i + h
>>> m31 = P(xN-2*h, xN, c, n).diff(c[0])
>>> m32 = P(xN-2*h, xN, c, n).diff(c[1])
>>> m33 = P(xN-2*h, xN, c, n).diff(c[2])

Next we construct the 3 × 3 matrix of the coeffcients:

>>> M = Matrix([[m11, m12, m13], [m21, m22, m23], [m31, m32, m33]])
>>> # matrix of the function values...actually a vector of right hand sides
>>> R = Matrix([[FN], [FNm1], [FNm2]])

Then we invert M and write the solution to the 3 × 3 system.

The matrix form of the three equations for the c_i is M ∗ C = R. The solution is obtained by
directly inverting M :

>>> X = M.inv() * R

The first derivative is coefficient c1 which is X[1]. Thus the second order accurate approxima-
tion for the first derivative is:

>>> print(”The first derivative centered at the last point on the right is:”)
The first derivative centered at the last point on the right is:
>>> print(together(X[1]))
(-4*F_{N-1} + F_{N-2} + 3*F_{N})/(2*h)

Of course, we can devise a similar formula for the value of the derivative at the left end of the
set of points at (x1 , F1 ) in terms of values at (x2 , F2 ) and (x3 , F3 ).
Also, we note that output of formats appropriate to Fortran, C, etc. may be done in the
examples given above.
Next we show how to perform these and many other discritizations of derivatives, but using
a much more efficient approach originally due to Bengt Fornberg and now incorported into
SymPy.

6.2. Finite Difference Approximations to Derivatives 1893

SymPy Documentation, Release 1.3

1894 Chapter 6. SymPy Special Topics

 CHAPTER

SEVEN

DEVELOPMENT TIPS: COMPARISONS IN PYTHON

7.1 Introduction

When debugging comparisons and hashes in SymPy, it is necessary to understand when ex-
actly Python calls each method. Unfortunately, the official Python documentation for this is
not very detailed (see the docs for rich comparison, __cmp__() and __hash__() methods).
We wrote this guide to fill in the missing gaps. After reading it, you should be able to under-
stand which methods do (and do not) get called and the order in which they are called.

7.2 Hashing

Every Python class has a __hash__() method, the default implementation of which is:

def __hash__(self):
return id(self)

You can reimplement it to return a different integer that you compute on your own. hash(x)
just calls x.__hash__(). Python builtin classes usually redefine the __hash__() method. For
example, an int has something like this:

def __hash__(self):
return int(self)

and a list does something like this:

def __hash__(self):
raise TypeError(”list objects are unhashable”)

The general idea about hashes is that if two objects have a different hash, they are not equal,
but if they have the same hash, they might be equal. (This is usually called a “hash collision”
and you need to use the methods described in the next section to determine if the objects
really are equal).
The only requirement from the Python side is that the hash value mustn’t change after it is
returned by the __hash__() method.
Please be aware that hashing is platform-dependent. This means that you can get different
hashes for the same SymPy object on different platforms. This affects for instance sorting of
sympy expressions. You can also get SymPy objects printed in different order.

1895
SymPy Documentation, Release 1.3

When developing, you have to be careful about this, especially when writing tests. It is pos-
sible that your test runs on a 32-bit platform, but not on 64-bit. An example:

>> from sympy import *

>> x = Symbol('x')
>> r = rootfinding.roots_quartic(Poly(x**4 - 6*x**3 + 17*x**2 - 26*x + 20, x))
>> [i.evalf(2) for i in r]
[1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I]

If you get this order of solutions, you are probably running 32-bit system. On a 64-bit system
you would get the following:

>> [i.evalf(2) for i in r]

[1.0 - 1.7*I, 1.0 + 1.7*I, 2.0 + I, 2.0 - 1.0*I

When you now write a test like this:

r = [i.evalf(2) for i in r]
assert r == [1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I]

it will fail on a 64-bit platforms, even if it works for your 32-bit system. You can avoid this by
using the sorted() or set() Python built-in:

r = [i.evalf(2) for i in r]
assert set(r) == set([1.0 + 1.7*I, 2.0 - 1.0*I, 2.0 + I, 1.0 - 1.7*I])

This approach does not work for doctests since they always compare strings that would be
printed after a prompt. In that case you could make your test print results using a combination
of str() and sorted():

>> sorted([str(i.evalf(2)) for i in r])

['1.0 + 1.7*I', '1.0 - 1.7*I', '2.0 + I', '2.0 - 1.0*I']

or, if you don’t want to show the values as strings, then sympify the results or the sorted list:

>> [S(s) for s in sorted([str(i.evalf(2)) for i in r])]

[1.0 + 1.7*I, 1.0 - 1.7*I, 2.0 + I, 2.0 - I]

The printing of SymPy expressions might be also affected, so be careful with doctests. If you
get the following on a 32-bit system:

>> print dsolve(f(x).diff(x, 2) + 2*f(x).diff(x) - f(x), f(x))

f(x) == C1*exp(-x + x*sqrt(2)) + C2*exp(-x - x*sqrt(2))

you might get the following on a 64-bit platform:

>> print dsolve(f(x).diff(x, 2) + 2*f(x).diff(x) - f(x), f(x))

f(x) == C1*exp(-x - x*sqrt(2)) + C2*exp(-x + x*sqrt(2))

7.3 Method Resolution

Let a, b and c be instances of any one of the Python classes. As can be easily checked by the
Python script (page 1898) at the end of this guide, if you write:

1896 Chapter 7. Development Tips: Comparisons in Python

 SymPy Documentation, Release 1.3

a == b

Python calls the following – in this order:

a.__eq__(b)
b.__eq__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) == id(b)

If a particular method is not implemented (or a method returns NotImplemented1 ) Python

skips it and tries the next one until it succeeds (i.e. until the method returns something
meaningful). The last line is a catch-all method that always succeeds.
If you write:

a != b

Python tries to call:

a.__ne__(b)
b.__ne__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) == id(b)

If you write:

a < b

Python tries to call:

a.__lt__(b)
b.__gt__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) < id(b)

If you write:

a <= b

Python tries to call:

a.__le__(b)
b.__ge__(a)
a.__cmp__(b)
b.__cmp__(a)
id(a) <= id(b)

And similarly for a > b and a >= b.

If you write:
1 There is also the similar NotImplementedError exception, which one may be tempted to raise to obtain the same

effect as returning NotImplemented.

But these are not the same, and Python will completely ignore NotImplementedError with respect to choosing
appropriate comparison method, and will just propagate this exception upwards, to the caller.
So return NotImplemented is not the same as raise NotImplementedError.

7.3. Method Resolution 1897

SymPy Documentation, Release 1.3

sorted([a, b, c])

Python calls the same chain of methods as for the b < a and c < b comparisons.
If you write any of the following:
a in {d: 5}
a in set([d, d, d])
set([a, b]) == set([a, b])

Python first compares hashes, e.g.:

a.__hash__()
d.__hash__()

If hash(a) != hash(d) then the result of the statement a in {d: 5} is immediately False
(remember how hashes work in general). If hash(a) == hash(d)) Python goes through the
method resolution of the == operator as shown above.

7.4 General Notes and Caveats

In the method resolution for <, <=, ==, !=, >=, > and sorted([a, b, c]) operators the
__hash__() method is not called, so in these cases it doesn’t matter what it returns. The
__hash__() method is only called for sets and dictionaries.
In the official Python documentation you can read about hashable and non-hashable objects.
In reality, you don’t have to think about it, you just follow the method resolution described
here. E.g. if you try to use lists as dictionary keys, the list’s __hash__() method will be called
and it returns an exception.
In SymPy, every instance of any subclass of Basic is immutable. Technically this means,
that its behavior through all the methods above mustn’t change once the instance is created.
Especially, the hash value mustn’t change (as already stated above) or else objects will get
mixed up in dictionaries and wrong values will be returned for a given key, etc….

7.5 Script To Verify This Guide

The above method resolution can be verified using the following program:
class A(object):

def __init__(self, a, hash):

self.a = a
self._hash = hash

def __lt__(self, o):

print ”%s.__lt__(%s)” % (self.a, o.a)
return NotImplemented

def __le__(self, o):

print ”%s.__le__(%s)” % (self.a, o.a)
return NotImplemented
(continues on next page)

1898 Chapter 7. Development Tips: Comparisons in Python

 SymPy Documentation, Release 1.3

(continued from previous page)

def __gt__(self, o):

print ”%s.__gt__(%s)” % (self.a, o.a)
return NotImplemented

def __ge__(self, o):

print ”%s.__ge__(%s)” % (self.a, o.a)
return NotImplemented

def __cmp__(self, o):

print ”%s.__cmp__(%s)” % (self.a, o.a)
#return cmp(self._hash, o._hash)
return NotImplemented

def __eq__(self, o):

print ”%s.__eq__(%s)” % (self.a, o.a)
return NotImplemented

def __ne__(self, o):

print ”%s.__ne__(%s)” % (self.a, o.a)
return NotImplemented

def __hash__(self):
print ”%s.__hash__()” % (self.a)
return self._hash

def show(s):
print ”--- %s ” % s + ”-”*40
eval(s)

a = A(”a”, 1)
b = A(”b”, 2)
c = A(”c”, 3)
d = A(”d”, 1)

show(”a == b”)
show(”a != b”)
show(”a < b”)
show(”a <= b”)
show(”a > b”)
show(”a >= b”)
show(”sorted([a, b, c])”)
show(”{d: 5}”)
show(”a in {d: 5}”)
show(”set([d, d, d])”)
show(”a in set([d, d, d])”)
show(”set([a, b])”)

print ”--- x = set([a, b]); y = set([a, b]); ---”

x = set([a, b])
y = set([a, b])
print ” x == y :”
x == y

print ”--- x = set([a, b]); y = set([b, d]); ---”

x = set([a, b])

(continues on next page)

7.5. Script To Verify This Guide 1899

SymPy Documentation, Release 1.3

(continued from previous page)

y = set([b, d])
print ” x == y :”
x == y

and its output:

--- a == b ----------------------------------------
a.__eq__(b)
b.__eq__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a != b ----------------------------------------
a.__ne__(b)
b.__ne__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a < b ----------------------------------------
a.__lt__(b)
b.__gt__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a <= b ----------------------------------------
a.__le__(b)
b.__ge__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a > b ----------------------------------------
a.__gt__(b)
b.__lt__(a)
a.__cmp__(b)
b.__cmp__(a)
--- a >= b ----------------------------------------
a.__ge__(b)
b.__le__(a)
a.__cmp__(b)
b.__cmp__(a)
--- sorted([a, b, c]) ----------------------------------------
b.__lt__(a)
a.__gt__(b)
b.__cmp__(a)
a.__cmp__(b)
c.__lt__(b)
b.__gt__(c)
c.__cmp__(b)
b.__cmp__(c)
--- {d: 5} ----------------------------------------
d.__hash__()
--- a in {d: 5} ----------------------------------------
d.__hash__()
a.__hash__()
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)
--- set([d, d, d]) ----------------------------------------
d.__hash__()
(continues on next page)

1900 Chapter 7. Development Tips: Comparisons in Python

 SymPy Documentation, Release 1.3

(continued from previous page)

d.__hash__()
d.__hash__()
--- a in set([d, d, d]) ----------------------------------------
d.__hash__()
d.__hash__()
d.__hash__()
a.__hash__()
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)
--- set([a, b]) ----------------------------------------
a.__hash__()
b.__hash__()
--- x = set([a, b]); y = set([a, b]); ---
a.__hash__()
b.__hash__()
a.__hash__()
b.__hash__()
x == y :
--- x = set([a, b]); y = set([b, d]); ---
a.__hash__()
b.__hash__()
b.__hash__()
d.__hash__()
x == y :
d.__eq__(a)
a.__eq__(d)
d.__cmp__(a)
a.__cmp__(d)

7.5. Script To Verify This Guide 1901

SymPy Documentation, Release 1.3

1902 Chapter 7. Development Tips: Comparisons in Python

 CHAPTER

EIGHT

WIKI

SymPy has a public wiki located at http://wiki.sympy.org. Users should feel free to contribute
to this wiki anything interesting/useful.

8.1 FAQ

FAQ is one of the most useful wiki pages. It has answers to frequently-asked questions.

1903
SymPy Documentation, Release 1.3

1904 Chapter 8. Wiki

 CHAPTER

NINE

SYMPY PAPERS

A list of papers which either use or mention SymPy, as well as presentations given about
SymPy at conferences can be seen at SymPy Papers.

1905
SymPy Documentation, Release 1.3

1906 Chapter 9. SymPy Papers

 CHAPTER

TEN

PLANET SYMPY

We have a blog aggregator at http://planet.sympy.org.

1907
SymPy Documentation, Release 1.3

1908 Chapter 10. Planet SymPy

 CHAPTER

ELEVEN

SYMPY LOGOS

SymPy has a collection of official logos, which can be generated from sympy.svg in your local
copy of SymPy by:

$ cd doc
$ make logo # will be stored in the _build/logo subdirectory

The license of all the logos is the same as SymPy: BSD. See the LICENSE file in the trunk for
more information.

1909
SymPy Documentation, Release 1.3

1910 Chapter 11. SymPy logos

 CHAPTER

TWELVE

BLOGS, NEWS, MAGAZINES

You can see a list of blogs/news/magazines mentioning SymPy (that we know of) on our wiki
page.

1911
SymPy Documentation, Release 1.3

1912 Chapter 12. Blogs, News, Magazines

 CHAPTER

THIRTEEN

ABOUT

13.1 SymPy Development Team

All people who contributed to SymPy by sending at least a patch or

more (in the order of the date of their first contribution), except
those who explicitly didn't want to be mentioned. People with a * next
to their names are not found in the metadata of the git history. This
file is generated automatically by running `./bin/authors_update.py`.

There are a total of 749 authors.

Ondřej Čertík <[email protected]>

Fabian Pedregosa <[email protected]>
Jurjen N.E. Bos <[email protected]>
Mateusz Paprocki <[email protected]>
*Marc-Etienne M.Leveille <[email protected]>
Brian Jorgensen <[email protected]>
Jason Gedge <[email protected]>
Robert Schwarz <[email protected]>
Pearu Peterson <[email protected]>
Fredrik Johansson <[email protected]>
Chris Wu <[email protected]>
*Ulrich Hecht <[email protected]>
Goutham Lakshminarayan <[email protected]>
David Lawrence <[email protected]>
Jaroslaw Tworek <[email protected]>
David Marek <[email protected]>
Bernhard R. Link <[email protected]>
Andrej Tokarčík <[email protected]>
Or Dvory <[email protected]>
Saroj Adhikari <[email protected]>
Pauli Virtanen <[email protected]>
Robert Kern <[email protected]>
James Aspnes <[email protected]>
Nimish Telang <[email protected]>
Abderrahim Kitouni <[email protected]>
Pan Peng <[email protected]>
Friedrich Hagedorn <[email protected]>
Elrond der Elbenfuerst <[email protected]>
Rizgar Mella <[email protected]>
Felix Kaiser <[email protected]>
Roberto Nobrega <[email protected]>
David Roberts <[email protected]>
(continues on next page)

1913
SymPy Documentation, Release 1.3

(continued from previous page)

Sebastian Krämer <[email protected]>
Vinzent Steinberg <[email protected]>
Riccardo Gori <[email protected]>
Case Van Horsen <[email protected]>
Stepan Roucka <[email protected]>
Ali Raza Syed <[email protected]>
Stefano Maggiolo <[email protected]>
Robert Cimrman <[email protected]>
Bastian Weber <[email protected]>
Sebastian Krause <[email protected]>
Sebastian Kreft <[email protected]>
*Dan <[email protected]>
Alan Bromborsky <[email protected]>
Boris Timokhin <[email protected]>
Robert <[email protected]>
Andy R. Terrel <[email protected]>
Hubert Tsang <[email protected]>
Konrad Meyer <[email protected]>
Henrik Johansson <[email protected]>
Priit Laes <[email protected]>
Freddie Witherden <[email protected]>
Brian E. Granger <[email protected]>
Andrew Straw <[email protected]>
Kaifeng Zhu <[email protected]>
Ted Horst <[email protected]>
Andrew Docherty <[email protected]>
Akshay Srinivasan <[email protected]>
Aaron Meurer <[email protected]>
Barry Wardell <[email protected]>
Tomasz Buchert <[email protected]>
Vinay Kumar <[email protected]>
Johann Cohen-Tanugi <[email protected]>
Jochen Voss <[email protected]>
Luke Peterson <[email protected]>
Chris Smith <[email protected]>
Thomas Sidoti <[email protected]>
Florian Mickler <[email protected]>
Nicolas Pourcelot <[email protected]>
Ben Goodrich <[email protected]>
Toon Verstraelen <[email protected]>
Ronan Lamy <[email protected]>
James Abbatiello <[email protected]>
Ryan Krauss <[email protected]>
Bill Flynn <[email protected]>
Kevin Goodsell <[email protected]>
Jorn Baayen <[email protected]>
Eh Tan <[email protected]>
Renato Coutinho <[email protected]>
Oscar Benjamin <[email protected]>
Øyvind Jensen <[email protected]>
Julio Idichekop Filho <[email protected]>
Łukasz Pankowski <[email protected]>
*Chu-Ching Huang <[email protected]>
Fernando Perez <[email protected]>
Raffaele De Feo <[email protected]>
Christian Muise <[email protected]>

(continues on next page)

1914 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Matt Curry <[email protected]>
Kazuo Thow <[email protected]>
Christian Schubert <[email protected]>
Jezreel Ng <[email protected]>
James Pearson <[email protected]>
Matthew Brett <[email protected]>
Addison Cugini <[email protected]>
Nicholas J.S. Kinar <[email protected]>
Harold Erbin <[email protected]>
Thomas Dixon <[email protected]>
Cristóvão Sousa <[email protected]>
Andre de Fortier Smit <[email protected]>
Mark Dewing <[email protected]>
Alexey U. Gudchenko <[email protected]>
Gary Kerr <[email protected]>
Sherjil Ozair <[email protected]>
Oleksandr Gituliar <[email protected]>
Sean Vig <[email protected]>
Prafullkumar P. Tale <[email protected]>
Vladimir Perić <[email protected]>
Tom Bachmann <[email protected]>
Yuri Karadzhov <[email protected]>
Vladimir Lagunov <[email protected]>
Matthew Rocklin <[email protected]>
Saptarshi Mandal <[email protected]>
Gilbert Gede <[email protected]>
Anatolii Koval <[email protected]>
Tomo Lazovich <[email protected]>
Pavel Fedotov <[email protected]>
Jack McCaffery <[email protected]>
Jeremias Yehdegho <[email protected]>
Kibeom Kim <[email protected]>
Gregory Ksionda <[email protected]>
Tomáš Bambas <[email protected]>
Raymond Wong <[email protected]>
Luca Weihs <[email protected]>
Shai 'Deshe' Wyborski <[email protected]>
Thomas Wiecki <[email protected]>
Óscar Nájera <[email protected]>
Mario Pernici <[email protected]>
Benjamin McDonald <[email protected]>
Sam Magura <[email protected]>
Stefan Krastanov <[email protected]>
Bradley Froehle <[email protected]>
Min Ragan-Kelley <[email protected]>
Emma Hogan <[email protected]>
Nikhil Sarda <[email protected]>
Julien Rioux <[email protected]>
Roberto Colistete, Jr. <[email protected]>
Raoul Bourquin <[email protected]>
Gert-Ludwig Ingold <[email protected]>
Srinivas Vasudevan <[email protected]>
Jason Moore <[email protected]>
Miha Marolt <[email protected]>
Tim Lahey <[email protected]>
Luis Garcia <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1915

SymPy Documentation, Release 1.3

(continued from previous page)

Matt Rajca <[email protected]>
David Li <[email protected]>
Alexandr Gudulin <[email protected]>
Bilal Akhtar <[email protected]>
Grzegorz Świrski <[email protected]>
Matt Habel <[email protected]>
David Ju <[email protected]>
Nichita Utiu <[email protected]>
Nikolay Lazarov <[email protected]>
Steve Anton <[email protected]>
Imran Ahmed Manzoor <[email protected]>
Ljubiša Moćić <[email protected]>
Piotr Korgul <[email protected]>
Jim Zhang <[email protected]>
Sam Sleight <[email protected]>
tborisova <[email protected]>
Chancellor Arkantos <[email protected]>
Stepan Simsa <[email protected]>
Tobias Lenz <[email protected]>
Siddhanathan Shanmugam <[email protected]>
Tiffany Zhu <[email protected]>
Tristan Hume <[email protected]>
Alexey Subach <[email protected]>
Joan Creus <[email protected]>
Geoffry Song <[email protected]>
Puneeth Chaganti <[email protected]>
Marcin Kostrzewa <>
Natalia Nawara <[email protected]>
vishal <[email protected]>
Shruti Mangipudi <[email protected]>
Davy Mao <[email protected]>
Swapnil Agarwal <[email protected]>
Dhia Kennouche <[email protected]>
jerryma1121 <[email protected]>
Joachim Durchholz <[email protected]>
Martin Povišer <[email protected]>
Siddhant Jain <[email protected]>
Kevin Hunter <[email protected]>
Michael Mayorov <[email protected]>
Nathan Alison <[email protected]>
Christian Bühler <[email protected]>
Carsten Knoll <[email protected]>
Bharath M R <[email protected]>
Matthias Toews <[email protected]>
Sergiu Ivanov <[email protected]>
Jorge E. Cardona <[email protected]>
Sanket Agarwal <[email protected]>
Manoj Babu K. <[email protected]>
Sai Nikhil <[email protected]>
Aleksandar Makelov <[email protected]>
Sachin Irukula <[email protected]>
Raphael Michel <[email protected]>
Ashwini Oruganti <[email protected]>
Andreas Kloeckner <[email protected]>
Prateek Papriwal <[email protected]>
Arpit Goyal <[email protected]>

(continues on next page)

1916 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Angadh Nanjangud <[email protected]>
Comer Duncan <[email protected]>
Jens H. Nielsen <[email protected]>
Joseph Dougherty <[email protected]>
Elliot Marshall <[email protected]>
Guru Devanla <[email protected]>
George Waksman <[email protected]>
Alexandr Popov <[email protected]>
Tarun Gaba <[email protected]>
Takafumi Arakaki <[email protected]>
Saurabh Jha <[email protected]>
Rom le Clair <[email protected]>
Angus Griffith <[email protected]>
Timothy Reluga <[email protected]>
Brian Stephanik <[email protected]>
Alexander Eberspächer <[email protected]>
Sachin Joglekar <[email protected]>
Tyler Pirtle <[email protected]>
Vasily Povalyaev <[email protected]>
Colleen Lee <[email protected]>
Matthew Hoff <[email protected]>
Niklas Thörne <[email protected]>
Huijun Mai <[email protected]>
Marek Šuppa <[email protected]>
Ramana Venkata <[email protected]>
Prasoon Shukla <[email protected]>
Stefen Yin <[email protected]>
Thomas Hisch <[email protected]>
Madeleine Ball <[email protected]>
Mary Clark <[email protected]>
Rishabh Dixit <[email protected]>
Manoj Kumar <[email protected]>
Akshit Agarwal <[email protected]>
CJ Carey <[email protected]>
Patrick Lacasse <[email protected]>
Ananya H <[email protected]>
Tarang Patel <[email protected]>
Christopher Dembia <[email protected]>
Benjamin Fishbein <[email protected]>
Sean Ge <[email protected]>
Amit Jamadagni <[email protected]>
Ankit Agrawal <[email protected]>
Björn Dahlgren <[email protected]>
Christophe Saint-Jean <[email protected]>
Demian Wassermann <[email protected]>
Khagesh Patel <[email protected]>
Stephen Loo <[email protected]>
hm <[email protected]>
Patrick Poitras <[email protected]>
Katja Sophie Hotz <[email protected]>
Varun Joshi <[email protected]>
Chetna Gupta <[email protected]>
Thilina Rathnayake <[email protected]>
Max Hutchinson <[email protected]>
Shravas K Rao <[email protected]>
Matthew Tadd <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1917

SymPy Documentation, Release 1.3

(continued from previous page)

Alexander Hirzel <[email protected]>
Randy Heydon <[email protected]>
Oliver Lee <[email protected]>
Seshagiri Prabhu <[email protected]>
Pradyumna <[email protected]>
Erik Welch <[email protected]>
Eric Nelson <[email protected]>
Roland Puntaier <[email protected]>
Chris Conley <[email protected]>
Tim Swast <[email protected]>
Dmitry Batkovich <[email protected]>
Francesco Bonazzi <[email protected]>
Yuriy Demidov <[email protected]>
Rick Muller <[email protected]>
Manish Gill <[email protected]>
Markus Müller <[email protected]>
Amit Saha <[email protected]>
Jeremy <[email protected]>
QuaBoo <[email protected]>
Stefan van der Walt <[email protected]>
David Joyner <[email protected]>
Lars Buitinck <[email protected]>
Alkiviadis G. Akritas <[email protected]>
Vinit Ravishankar <[email protected]>
Mike Boyle <[email protected]>
Heiner Kirchhoffer <[email protected]>
Pablo Puente <[email protected]>
James Fiedler <[email protected]>
Harsh Gupta <[email protected]>
Tuomas Airaksinen <[email protected]>
Paul Strickland <[email protected]>
James Goppert <[email protected]>
rathmann <[email protected]>
Avichal Dayal <[email protected]>
Paul Scott <[email protected]>
Shipra Banga <[email protected]>
Pramod Ch <[email protected]>
Akshay <[email protected]>
Buck Shlegeris <[email protected]>
Jonathan Miller <[email protected]>
Edward Schembor <[email protected]>
Rajath Shashidhara <[email protected]>
Zamrath Nizam <[email protected]>
Aditya Shah <[email protected]>
Rajat Aggarwal <[email protected]>
Sambuddha Basu <[email protected]>
Zeel Shah <[email protected]>
Abhinav Chanda <[email protected]>
Jim Crist <[email protected]>
Sudhanshu Mishra <[email protected]>
Anurag Sharma <[email protected]>
Soumya Dipta Biswas <[email protected]>
Sushant Hiray <[email protected]>
Ben Lucato <[email protected]>
Kunal Arora <[email protected]>
Henry Gebhardt <[email protected]>

(continues on next page)

1918 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Dammina Sahabandu <[email protected]>
Manish Shukla <manish.shukla393@gmail>
Ralph Bean <[email protected]>
richierichrawr <[email protected]>
John Connor <[email protected]>
Juan Luis Cano Rodríguez <[email protected]>
Sahil Shekhawat <[email protected]>
Kundan Kumar <[email protected]>
Stas Kelvich <[email protected]>
sevaader <[email protected]>
Dhruvesh Vijay Parikh <[email protected]>
Venkatesh Halli <[email protected]>
Lennart Fricke <[email protected]>
Vlad Seghete <[email protected]>
Shashank Agarwal <[email protected]>
carstimon <[email protected]>
Pierre Haessig <[email protected]>
Maciej Baranski <[email protected]>
Benjamin Gudehus <[email protected]>
Faisal Anees <[email protected]>
Mark Shoulson <[email protected]>
Robert Johansson <[email protected]>
Kalevi Suominen <[email protected]>
Kaushik Varanasi <[email protected]>
Fawaz Alazemi <[email protected]>
Ambar Mehrotra <[email protected]>
David P. Sanders <[email protected]>
Peter Brady <[email protected]>
John V. Siratt <[email protected]>
Sarwar Chahal <[email protected]>
Nathan Woods <[email protected]>
Colin B. Macdonald <[email protected]>
Marcus Näslund <[email protected]>
Clemens Novak <[email protected]>
Mridul Seth <[email protected]>
Craig A. Stoudt <[email protected]>
Raj <[email protected]>
Mihai A. Ionescu <[email protected]>
immerrr <[email protected]>
Chai Wah Wu <[email protected]>
Leonid Blouvshtein <[email protected]>
Peleg Michaeli <[email protected]>
ck Lux <[email protected]>
zsc347 <[email protected]>
Hamish Dickson <[email protected]>
Michael Gallaspy <[email protected]>
Roman Inflianskas <[email protected]>
Duane Nykamp <[email protected]>
Ted Dokos <[email protected]>
Sunny Aggarwal <[email protected]>
Victor Brebenar <[email protected]>
Akshat Jain <[email protected]>
Shivam Vats <[email protected]>
Longqi Wang <[email protected]>
Juan Felipe Osorio <[email protected]>
Ray Cathcart <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1919

SymPy Documentation, Release 1.3

(continued from previous page)

Lukas Zorich <[email protected]>
Eric Miller <[email protected]>
Cody Herbst <[email protected]>
Nishith Shah <[email protected]>
Amit Kumar <[email protected]>
Yury G. Kudryashov <[email protected]>
Guillaume Gay <[email protected]>
Mihir Wadwekar <[email protected]>
Tuan Manh Lai <[email protected]>
Asish Panda <[email protected]>
Darshan Chaudhary <[email protected]>
Alec Kalinin <[email protected]>
Ralf Stephan <[email protected]>
Aaditya Nair <[email protected]>
Jayesh Lahori <[email protected]>
Harshil Goel <[email protected]>
Luv Agarwal <[email protected]>
Jason Ly <[email protected]>
Lokesh Sharma <[email protected]>
Sartaj Singh <[email protected]>
Chris Swierczewski <[email protected]>
Konstantin Togoi <[email protected]>
Param Singh <[email protected]>
Sumith Kulal <[email protected]>
Juha Remes <[email protected]>
Philippe Bouafia <[email protected]>
Peter Schmidt <[email protected]>
Jiaxing Liang <[email protected]>
Lucas Jones <[email protected]>
Gregory Ashton <[email protected]>
Jennifer White <[email protected]>
Renato Orsino <[email protected]>
Michael Boyle <[email protected]>
Alistair Lynn <[email protected]>
Govind Sahai <[email protected]>
Adam Bloomston <[email protected]>
Kyle McDaniel <[email protected]>
Nguyen Truong Duy <[email protected]>
Alex Lindsay <[email protected]>
Mathew Chong <[email protected]>
Jason Siefken <[email protected]>
Gaurav Dhingra <[email protected]>
Gao, Xiang <[email protected]>
Kevin Ventullo <[email protected]>
mao8 <[email protected]>
Isuru Fernando <[email protected]>
Shivam Tyagi <[email protected]>
Richard Otis <[email protected]>
Rich LaSota <[email protected]>
dustyrockpyle <[email protected]>
Anton Akhmerov <[email protected]>
Michael Zingale <[email protected]>
Chak-Pong Chung <[email protected]>
David T <[email protected]>
Phil Ruffwind <[email protected]>
Sebastian Koslowski <[email protected]>

(continues on next page)

1920 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Kumar Krishna Agrawal <[email protected]>
Dustin Gadal <[email protected]>
João Moura <[email protected]>
Yu Kobayashi <[email protected]>
Shashank Kumar <[email protected]>
Timothy Cyrus <[email protected]>
Devyani Kota <[email protected]>
Keval Shah <[email protected]>
Dzhelil Rufat <[email protected]>
Pastafarianist <[email protected]>
Sourav Singh <[email protected]>
Jacob Garber <[email protected]>
Vinay Singh <[email protected]>
GolimarOurHero <[email protected]>
Prashant Tyagi <[email protected]>
Matthew Davis <[email protected]>
Tschijnmo TSCHAU <[email protected]>
Alexander Bentkamp <[email protected]>
Jack Kemp <[email protected]>
Kshitij Saraogi <[email protected]>
Thomas Baruchel <[email protected]>
Nicolás Guarín-Zapata <[email protected]>
Jens Jørgen Mortensen <[email protected]>
Sampad Kumar Saha <[email protected]>
Eva Charlotte Mayer <[email protected]>
Laura Domine <[email protected]>
Justin Blythe <[email protected]>
Meghana Madhyastha <[email protected]>
Tanu Hari Dixit <[email protected]>
Shekhar Prasad Rajak <[email protected]>
Aqnouch Mohammed <[email protected]>
Arafat Dad Khan <[email protected]>
Boris Atamanovskiy <[email protected]>
Sam Tygier <[email protected]>
Jai Luthra <[email protected]>
Guo Xingjian <[email protected]>
Sandeep Veethu <[email protected]>
Archit Verma <[email protected]>
Shubham Tibra <[email protected]>
Ashutosh Saboo <[email protected]>
Michael S. Hansen <[email protected]>
Anish Shah <[email protected]>
Guillaume Jacquenot <[email protected]>
Bhautik Mavani <[email protected]>
Michał Radwański <[email protected]>
Jerry Li <[email protected]>
Pablo Zubieta <[email protected]>
Shivam Agarwal <[email protected]>
Chaitanya Sai Alaparthi <[email protected]>
Arihant Parsoya <[email protected]>
Ruslan Pisarev <[email protected]>
Akash Trehan <[email protected]>
Nishant Nikhil <[email protected]>
Vladimir Poluhsin <[email protected]>
Akshay Nagar <[email protected]>
James Brandon Milam <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1921

SymPy Documentation, Release 1.3

(continued from previous page)

Abhinav Agarwal <[email protected]>
Rishabh Daal <[email protected]>
Sanya Khurana <[email protected]>
Aman Deep <[email protected]>
Aravind Reddy <[email protected]>
Abhishek Verma <[email protected]>
Matthew Parnell <[email protected]>
Thomas Hickman <[email protected]>
Akshay Siramdas <[email protected]>
YiDing Jiang <[email protected]>
Jatin Yadav <[email protected]>
Matthew Thomas <[email protected]>
Rehas Sachdeva <[email protected]>
Michael Mueller <[email protected]>
Srajan Garg <[email protected]>
Prabhjot Singh <[email protected]>
Haruki Moriguchi <[email protected]>
Tom Gijselinck <[email protected]>
Nitin Chaudhary <[email protected]>
Alex Argunov <[email protected]>
Nathan Musoke <[email protected]>
Abhishek Garg <[email protected]>
Dana Jacobsen <[email protected]>
Vasiliy Dommes <[email protected]>
Phillip Berndt <[email protected]>
Haimo Zhang <[email protected]>
Anthony Scopatz <[email protected]>
bluebrook <[email protected]>
Leonid Kovalev <[email protected]>
Josh Burkart <[email protected]>
Dimitra Konomi <[email protected]>
Christina Zografou <[email protected]>
Fiach Antaw <[email protected]>
Langston Barrett <[email protected]>
Krit Karan <[email protected]>
G. D. McBain <[email protected]>
Prempal Singh <[email protected]>
Gabriel Orisaka <[email protected]>
Matthias Bussonnier <[email protected]>
rahuldan <[email protected]>
Colin Marquardt <[email protected]>
Andrew Taber <[email protected]>
Yash Reddy <[email protected]>
Peter Stangl <[email protected]>
elvis-sik <[email protected]>
Nikos Karagiannakis <[email protected]>
Jainul Vaghasia <[email protected]>
Dennis Meckel <[email protected]>
Harshil Meena <[email protected]>
Micky <[email protected]>
Nick Curtis <[email protected]>
Michele Zaffalon <[email protected]>
Martha Giannoudovardi <[email protected]>
Devang Kulshreshtha <[email protected]>
Steph Papanik <[email protected]>
Mohammad Sadeq Dousti <[email protected]>

(continues on next page)

1922 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Arif Ahmed <[email protected]>
Abdullah Javed Nesar <[email protected]>
Lakshya Agrawal <[email protected]>
shruti <[email protected]>
Rohit Rango <[email protected]>
Hong Xu <[email protected]>
Ivan Petuhov <[email protected]>
Alsheh <[email protected]>
Marcel Stimberg <[email protected]>
Alexey Pakhocmhik <[email protected]>
Tommy Olofsson <[email protected]>
Zulfikar <[email protected]>
Blair Azzopardi <[email protected]>
Danny Hermes <[email protected]>
Sergey Pestov <[email protected]>
Mohit Chandra <[email protected]>
Karthik Chintapalli <[email protected]>
Marcin Briański <[email protected]>
andreo <[email protected]>
Flamy Owl <[email protected]>
Yicong Guo <[email protected]>
Varun Garg <[email protected]>
Rishabh Madan <[email protected]>
Aditya Kapoor <[email protected]>
Karan Sharma <[email protected]>
Vedant Rathore <[email protected]>
Johan Blåbäck <[email protected]>
Pranjal Tale <[email protected]>
Jason Tokayer <[email protected]>
Raghav Jajodia <[email protected]>
Rajat Thakur <[email protected]>
Dhruv Bhanushali <[email protected]>
Anjul Kumar Tyagi <[email protected]>
Barun Parruck <[email protected]>
Bao Chau <[email protected]>
Tanay Agrawal <[email protected]>
Ranjith Kumar <[email protected]>
Shikhar Makhija <[email protected]>
Yathartha Joshi <[email protected]>
Valeriia Gladkova <[email protected]>
Sagar Bharadwaj <[email protected]>
Daniel Mahler <[email protected]>
Ka Yi <[email protected]>
Rishat Iskhakov <[email protected]>
Szymon Mieszczak <[email protected]>
Sachin Agarwal <[email protected]>
Priyank Patel <[email protected]>
Satya Prakash Dwibedi <[email protected]>
tools4origins <[email protected]>
Nico Schlömer <[email protected]>
Fermi Paradox <[email protected]>
Ekansh Purohit <[email protected]>
Vedarth Sharma <[email protected]>
Peeyush Kushwaha <[email protected]>
Jayjayyy <[email protected]>
Christopher J. Wright <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1923

SymPy Documentation, Release 1.3

(continued from previous page)

Jakub Wilk <[email protected]>
Mauro Garavello <[email protected]>
Chris Tefer <[email protected]>
Shikhar Jaiswal <[email protected]>
Chiu-Hsiang Hsu <[email protected]>
Carlos Cordoba <[email protected]>
Fabian Ball <[email protected]>
Yerniyaz <[email protected]>
Christiano Anderson <[email protected]>
Robin Neatherway <[email protected]>
Thomas Hunt <[email protected]>
Theodore Han <[email protected]>
Duc-Minh Phan <[email protected]>
Lejla Metohajrova <[email protected]>
Samyak Jain <[email protected]>
Aditya Rohan <[email protected]>
Vincent Delecroix <[email protected]>
Michael Sparapany <[email protected]>
Harsh Jain <[email protected]>
Nathan Goldbaum <[email protected]>
latot <[email protected]>
Kenneth Lyons <[email protected]>
Stan Schymanski <[email protected]>
David Daly <[email protected]>
Ayush Shridhar <[email protected]>
Javed Nissar <[email protected]>
Jiri Kuncar <[email protected]>
vedantc98 <[email protected]>
Rupesh Harode <[email protected]>
Rob Zinkov <[email protected]>
James Harrop <[email protected]>
James Taylor <[email protected]>
Ishan Joshi <[email protected]>
Marco Mancini <[email protected]>
Boris Ettinger <[email protected]>
Micah Fitch <[email protected]>
Daniel Wennberg <[email protected]>
ylemkimon <[email protected]>
Akash Vaish <[email protected]>
Peter Enenkel <[email protected]>
Waldir Pimenta <[email protected]>
Jithin D. George <[email protected]>
Lev Chelyadinov <[email protected]>
Lucas Wiman <[email protected]>
Rhea Parekh <[email protected]>
James Cotton <[email protected]>
Robert Pollak <[email protected]>
anca-mc <[email protected]>
Sourav Ghosh <[email protected]>
Jonathan Allan <[email protected]>
Nikhil Pappu <[email protected]>
Ethan Ward <[email protected]>
Cezary Marczak <[email protected]>
dps7ud <[email protected]>
Nilabja Bhattacharya <[email protected]>
Itay4 <[email protected]>

(continues on next page)

1924 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

Poom Chiarawongse <[email protected]>
Yang Yang <[email protected]>
Cavendish McKay <[email protected]>
Bradley Gannon <[email protected]>
B McG <[email protected]>
Rob Drynkin <[email protected]>
Seth Ebner <[email protected]>
Akash Kundu <[email protected]>
Mark Jeromin <[email protected]>
Roberto Díaz Pérez <[email protected]>
Gleb Siroki <[email protected]>
Segev Finer <[email protected]>
Alex Lubbock <[email protected]>
Ayodeji Ige <[email protected]>
Matthew Wardrop <[email protected]>
Hugo <[email protected]>
Austin Palmer <[email protected]>
der-blaue-elefant <[email protected]>
Filip Gokstorp <[email protected]>
Yuki Matsuda <[email protected]>
Aaron Miller <[email protected]>
Salil Vishnu Kapur <[email protected]>
Atharva Khare <[email protected]>
Shubham Maheshwari <[email protected]>
Pavel Tkachenko <[email protected]>
Ashish Kumar Gaurav <[email protected]>
Rajeev Singh <[email protected]>
Keno Goertz <[email protected]>
Lucas Gallindo <[email protected]>
Himanshu <[email protected]>
David Menéndez Hurtado <[email protected]>
Amit Manchanda <[email protected]>
Rohit Jain <[email protected]>
Jonathan A. Gross <[email protected]>
Unknown <[email protected]>
Sayan Goswami <[email protected]>
Subhash Saurabh <[email protected]>
Rastislav Rabatin <[email protected]>
Vishal <[email protected]>
Jeremey Gluck <[email protected]>
Akshat Maheshwari <[email protected]>
symbolique <[email protected]>
Saloni Jain <[email protected]>
Arighna Chakrabarty <[email protected]>
Abhigyan Khaund <[email protected]>
Jashanpreet Singh <[email protected]>
Saurabh Agarwal <[email protected]>
luz.paz <[email protected]>
P. Sai Prasanth <[email protected]>
Nirmal Sarswat <[email protected]>
Cristian Di Pietrantonio <[email protected]>
Ravi charan <[email protected]>
Nityananda Gohain <[email protected]>
Cédric Travelletti <[email protected]>
Nicholas Bollweg <[email protected]>
Himanshu Ladia <[email protected]>

(continues on next page)

13.1. SymPy Development Team 1925

SymPy Documentation, Release 1.3

(continued from previous page)

eward <[email protected]>
Adwait Baokar <[email protected]>
Mihail Tarigradschi <[email protected]>
Saketh <[email protected]>
rushyam <[email protected]>
sfoo <[email protected]>
Rahil Hastu <[email protected]>
Zach Raines <[email protected]>
Sidhant Nagpal <[email protected]>
Gagandeep Singh <[email protected]>
Rishav Chakraborty <[email protected]>
Malkhan Singh <[email protected]>
Joaquim Monserrat <[email protected]>
Mayank Singh <[email protected]>
Rémy Léone <[email protected]>
Maxence Mayrand <[email protected]>
Nikoleta Glynatsi <[email protected]>
helo9 <[email protected]>
Ken Wakita <[email protected]>
Carl Sandrock <[email protected]>
Fredrik Eriksson <[email protected]>
Ian Swire <[email protected]>
Bulat <[email protected]>
Ehren Metcalfe <[email protected]>
Dmitry Savransky <[email protected]>
Kiyohito Yamazaki <[email protected]>
Caley Finn <[email protected]>
zhouzq-thu <[email protected]>
Alexander Pozdneev <[email protected]>
Wes Turner <[email protected]>
JMSS-Unknown <[email protected]>
Arshdeep Singh <[email protected]>
cym1 <[email protected]>
Stewart Wadsworth <[email protected]>
Jared Lumpe <[email protected]>
Avi Shrivastava <[email protected]>
ramvenkat98 <[email protected]>
Bilal Ahmed <[email protected]>
Dimas Abreu Archanjo Dutra <[email protected]>
czgdp1807 <[email protected]>
Yatna Verma <[email protected]>
S.Y. Lee <[email protected]>
Miro Hrončok <[email protected]>
Sudarshan Kamath <[email protected]>
Ayushman Koul <[email protected]>

You can find a brief history of SymPy in the README.

13.2 Financial and Infrastructure Support

• Google: SymPy has received generous financial support from Google in various years
through the Google Summer of Code program by providing stipends:
– in 2007 for 5 students (GSoC 2007)

1926 Chapter 13. About

 SymPy Documentation, Release 1.3

– in 2008 for 1 student (GSoC 2008)

– in 2009 for 5 students (GSoC 2009)
– in 2010 for 5 students (GSoC 2010)
– in 2011 for 9 students (GSoC 2011)
– in 2012 for 6 students (GSoC 2012)
– in 2013 for 7 students (GSoC 2013)
– in 2014 for 10 students (GSoC 2014)
– in 2015 for 7 students (GSoC 2015)
– in 2016 for 9 students (GSoC 2016)
Of these, we would like to thank these organizations for hosting GSoC students under
their umbrella organizations:
– Python Software Foundation (PSF) has hosted various GSoC students over the years:
∗ 3 GSoC 2007 students (Brian, Robert and Jason)
∗ 1 GSoC 2008 student (Fredrik)
∗ 2 GSoC 2009 students (Freddie and Priit)
∗ 4 GSoC 2010 students (Aaron, Christian, Matthew and Øyvind)
∗ 6 GSoC 2015 students
∗ 1 GSoC 2016 student (James)
– Portland State University (PSU) has hosted following GSoC students:
∗ 1 student (Chris) in 2007
∗ 3 students (Aaron, Dale and Fabian) in 2009
∗ 1 student (Addison) in 2010
– The Space Telescope Science Institute: STScI hosted 1 GSoC 2007 student (Ma-
teusz)
– The Ruby Science Foundation has hosted following GSoC students:
∗ 1 student (Abinash) in 2015
∗ 1 student (Rajith) in 2016
• Several 13-17 year old pre-university students contributed as part of Google’s Code-In
2011. (GCI 2011)
• Simula Research Laboratory: supports Pearu Peterson work in SymPy/SymPy Core
projects
• GitHub is providing us with development and collaboration tools

13.3 License

Unless stated otherwise, all files in the SymPy project, SymPy’s webpage (and wiki), all images
and all documentation including this User’s Guide are licensed using the new BSD license:

13.3. License 1927

SymPy Documentation, Release 1.3

Copyright (c) 2006-2018 SymPy Development Team

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

a. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.
b. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
c. Neither the name of SymPy nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ”AS IS”
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

--------------------------------------------------------------------------------

Patches taken from the Diofant project (https://github.com/diofant/diofant)

are licensed as:

Copyright (c) 2006-2017 SymPy Development Team,

2013-2017 Sergey B Kirpichev

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

a. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.
b. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
c. Neither the name of Diofant, or SymPy nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ”AS IS”
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
(continues on next page)

1928 Chapter 13. About

 SymPy Documentation, Release 1.3

(continued from previous page)

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

--------------------------------------------------------------------------------

Submodule taken from the multipledispatch project (https://github.com/mrocklin/

,→multipledispatch)

are licensed as:

Copyright (c) 2014 Matthew Rocklin

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

a. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.
b. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
c. Neither the name of multipledispatch nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ”AS IS”
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

13.3. License 1929

SymPy Documentation, Release 1.3

1930 Chapter 13. About

 CHAPTER

FOURTEEN

CITING SYMPY

To cite SymPy in publications use

Meurer A, Smith CP, Paprocki M, Čertík O, Kirpichev SB, Rocklin M, Kumar A,
Ivanov S, Moore JK, Singh S, Rathnayake T, Vig S, Granger BE, Muller RP, Bonazzi
F, Gupta H, Vats S, Johansson F, Pedregosa F, Curry MJ, Terrel AR, Roučka Š, Saboo
A, Fernando I, Kulal S, Cimrman R, Scopatz A. (2017) SymPy: symbolic computing
in Python. PeerJ Computer Science 3:e103 https://doi.org/10.7717/peerj-cs.103
A BibTeX entry for LaTeX users is

@article{10.7717/peerj-cs.103,
title = {SymPy: symbolic computing in Python},
author = {Meurer, Aaron and Smith, Christopher P. and Paprocki, Mateusz and \v{C}ert\
,→'{i}k, Ond\v{r}ej and Kirpichev, Sergey B. and Rocklin, Matthew and Kumar, AMiT and␣

,→Ivanov, Sergiu and Moore, Jason K. and Singh, Sartaj and Rathnayake, Thilina and␣

,→Vig, Sean and Granger, Brian E. and Muller, Richard P. and Bonazzi, Francesco and␣

,→Gupta, Harsh and Vats, Shivam and Johansson, Fredrik and Pedregosa, Fabian and␣

,→Curry, Matthew J. and Terrel, Andy R. and Rou\v{c}ka, \v{S}t\v{e}p\'{a}n and Saboo,␣

,→Ashutosh and Fernando, Isuru and Kulal, Sumith and Cimrman, Robert and Scopatz,␣

,→Anthony},

year = 2017,
month = jan,
keywords = {Python, Computer algebra system, Symbolics},
abstract = {
SymPy is an open source computer algebra system written in pure Python.␣
,→It is built with a focus on extensibility and ease of use, through both interactive␣

,→and programmatic applications. These characteristics have led SymPy to become a␣

,→popular symbolic library for the scientific Python ecosystem. This paper presents␣

,→the architecture of SymPy, a description of its features, and a discussion of␣

,→select submodules. The supplementary material provide additional examples and␣

,→further outline details of the architecture and features of SymPy.

},
volume = 3,
pages = {e103},
journal = {PeerJ Computer Science},
issn = {2376-5992},
url = {https://doi.org/10.7717/peerj-cs.103},
doi = {10.7717/peerj-cs.103}
}

SymPy is BSD licensed, so you are free to use it whatever you like, be it academic, commercial,
creating forks or derivatives, as long as you copy the BSD statement if you redistribute it
(see the LICENSE file for details). That said, although not required by the SymPy license,
if it is convenient for you, please cite SymPy when using it in your work and also consider

1931
SymPy Documentation, Release 1.3

contributing all your changes back, so that we can incorporate it and all of us will benefit in
the end.

1932 Chapter 14. Citing SymPy

 BIBLIOGRAPHY

[R49] http://en.wikipedia.org/wiki/Negative_number
[R50] http://en.wikipedia.org/wiki/Parity_%28mathematics%29
[R51] http://en.wikipedia.org/wiki/Imaginary_number
[R52] http://en.wikipedia.org/wiki/Composite_number
[R53] http://en.wikipedia.org/wiki/Irrational_number
[R54] http://en.wikipedia.org/wiki/Prime_number
[R55] http://en.wikipedia.org/wiki/Finite
[R56] https://docs.python.org/3/library/math.html#math.isfinite
[R57] http://docs.scipy.org/doc/numpy/reference/generated/numpy.isfinite.html
[R58] http://en.wikipedia.org/wiki/Zero
[R59] http://en.wikipedia.org/wiki/1_%28number%29
[R60] http://en.wikipedia.org/wiki/%E2%88%921_%28number%29
[R61] http://en.wikipedia.org/wiki/One_half
[R62] http://en.wikipedia.org/wiki/NaN
[R63] http://en.wikipedia.org/wiki/Infinity
[R64] http://en.wikipedia.org/wiki/E_%28mathematical_constant%29
[R65] http://en.wikipedia.org/wiki/Imaginary_unit
[R66] http://en.wikipedia.org/wiki/Pi
[R67] http://en.wikipedia.org/wiki/Euler%E2%80%93Mascheroni_constant
[R68] http://en.wikipedia.org/wiki/Catalan%27s_constant
[R69] http://en.wikipedia.org/wiki/Golden_ratio
[R70] https://en.wikipedia.org/wiki/Generalizations_of_Fibonacci_numbers#
Tribonacci_numbers
[R71] http://en.wikipedia.org/wiki/Exponentiation
[R72] http://en.wikipedia.org/wiki/Exponentiation#Zero_to_the_power_of_zero
[R73] http://en.wikipedia.org/wiki/Indeterminate_forms

1933
SymPy Documentation, Release 1.3

[R74] This implementation detail is that Python provides no reliable method to de-
termine 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 be-
ing compared is only evaluated once and the comparison can short-circuit. For
example, 1 > 2 > 3 is evaluated by Python as (1 > 2) and (2 > 3). The and
operator coerces each side into a bool, returning the object itself when it short-
circuits. The bool of the –Than operators will raise TypeError on purpose, be-
cause SymPy cannot determine the mathematical ordering of symbolic expres-
sions. Thus, if we were to compute x > y > z, with x, y, and z being Symbols,
Python converts the statement (roughly) into these steps:
(1) x > y > z
(2) (x > y) and (y > z)
(3) (GreaterThanObject) and (y > z)
(4) (GreaterThanObject.__nonzero__()) and (y > z)
(5) 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 the and operator, or to control
how it short circuits, so it is impossible to make something like x > y >
z work. There was a PEP to change this, PEP 335, but it was officially
closed in March, 2012.
[R75] This implementation detail is that Python provides no reliable method to de-
termine 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 be-
ing compared is only evaluated once and the comparison can short-circuit. For
example, 1 > 2 > 3 is evaluated by Python as (1 > 2) and (2 > 3). The and
operator coerces each side into a bool, returning the object itself when it short-
circuits. The bool of the –Than operators will raise TypeError on purpose, be-
cause SymPy cannot determine the mathematical ordering of symbolic expres-
sions. Thus, if we were to compute x > y > z, with x, y, and z being Symbols,
Python converts the statement (roughly) into these steps:
(1) x > y > z
(2) (x > y) and (y > z)
(3) (GreaterThanObject) and (y > z)
(4) (GreaterThanObject.__nonzero__()) and (y > z)
(5) 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 the and operator, or to control
how it short circuits, so it is impossible to make something like x > y >
z work. There was a PEP to change this, PEP 335, but it was officially
closed in March, 2012.

1934 Bibliography
 SymPy Documentation, Release 1.3

[R76] This implementation detail is that Python provides no reliable method to de-
termine 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 be-
ing compared is only evaluated once and the comparison can short-circuit. For
example, 1 > 2 > 3 is evaluated by Python as (1 > 2) and (2 > 3). The and
operator coerces each side into a bool, returning the object itself when it short-
circuits. The bool of the –Than operators will raise TypeError on purpose, be-
cause SymPy cannot determine the mathematical ordering of symbolic expres-
sions. Thus, if we were to compute x > y > z, with x, y, and z being Symbols,
Python converts the statement (roughly) into these steps:
(1) x > y > z
(2) (x > y) and (y > z)
(3) (GreaterThanObject) and (y > z)
(4) (GreaterThanObject.__nonzero__()) and (y > z)
(5) 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 the and operator, or to control
how it short circuits, so it is impossible to make something like x > y >
z work. There was a PEP to change this, PEP 335, but it was officially
closed in March, 2012.
[R77] This implementation detail is that Python provides no reliable method to de-
termine 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 be-
ing compared is only evaluated once and the comparison can short-circuit. For
example, 1 > 2 > 3 is evaluated by Python as (1 > 2) and (2 > 3). The and
operator coerces each side into a bool, returning the object itself when it short-
circuits. The bool of the –Than operators will raise TypeError on purpose, be-
cause SymPy cannot determine the mathematical ordering of symbolic expres-
sions. Thus, if we were to compute x > y > z, with x, y, and z being Symbols,
Python converts the statement (roughly) into these steps:
(1) x > y > z
(2) (x > y) and (y > z)
(3) (GreaterThanObject) and (y > z)
(4) (GreaterThanObject.__nonzero__()) and (y > z)
(5) 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 the and operator, or to control
how it short circuits, so it is impossible to make something like x > y >
z work. There was a PEP to change this, PEP 335, but it was officially
closed in March, 2012.

Bibliography 1935
SymPy Documentation, Release 1.3

[R29] Skiena, S. ‘Permutations.’ 1.1 in Implementing Discrete Mathematics Combina-

torics and Graph Theory with Mathematica. Reading, MA: Addison-Wesley, pp.
3-16, 1990.
[R30] Knuth, D. E. The Art of Computer Programming, Vol. 4: Combinatorial Algo-
rithms, 1st ed. Reading, MA: Addison-Wesley, 2011.
[R31] Wendy Myrvold and Frank Ruskey. 2001. Ranking and unranking permuta-
tions in linear time. Inf. Process. Lett. 79, 6 (September 2001), 281-284.
DOI=10.1016/S0020-0190(01)00141-7
[R32] D. L. Kreher, D. R. Stinson ‘Combinatorial Algorithms’ CRC Press, 1999
[R33] Graham, R. L.; Knuth, D. E.; and Patashnik, O. Concrete Mathematics: A Foun-
dation for Computer Science, 2nd ed. Reading, MA: Addison-Wesley, 1994.
[R34] http://en.wikipedia.org/wiki/Permutation#Product_and_inverse
[R35] http://en.wikipedia.org/wiki/Lehmer_code
[R36] http://mathworld.wolfram.com/LabeledTree.html
[CDHW73] John J. Cannon, Lucien A. Dimino, George Havas, and Jane M. Watson. Implemen-
tation and analysis of the Todd-Coxeter algorithm. Math. Comp., 27:463– 490,
1973.
[Ho05] Derek F. Holt, Handbook of Computational Group Theory. In the series ‘Discrete
Mathematics and its Applications’, Chapman & Hall/CRC 2005, xvi + 514 p.
[Hav91] George Havas, Coset enumeration strategies. In Proceedings of the International
Symposium on Symbolic and Algebraic Computation (ISSAC‘91), Bonn 1991,
pages 191–199. ACM Press, 1991.
[R433] definition is described in http://oeis.org/A066272/a066272a.html
[R434] formula from https://oeis.org/A066272
[R435] https://en.wikipedia.org/wiki/Euler%27s_totient_function
[R436] http://mathworld.wolfram.com/TotientFunction.html
[R437] https://en.wikipedia.org/wiki/Carmichael_function
[R438] http://mathworld.wolfram.com/CarmichaelFunction.html
[R439] http://en.wikipedia.org/wiki/Divisor_function
[R440] http://mathworld.wolfram.com/UnitaryDivisorFunction.html
[R441] http://en.wikipedia.org/wiki/Square-free_integer#Squarefree_core
[R442] http://mathworld.wolfram.com/PrimeFactor.html
[R443] http://mathworld.wolfram.com/PrimeFactor.html
[R444] http://mathworld.wolfram.com/PartitionFunctionP.html
[R445] W. Stein “Elementary Number Theory” (2011), page 44
[R446] P. Hackman “Elementary Number Theory” (2009), Chapter C
[R447] P. Hackman “Elementary Number Theory” (2009), page 76
[R448] http://mathworld.wolfram.com/DiscreteLogarithm.html
[R449] “Handbook of applied cryptography”, Menezes, A. J., Van, O. P. C., & Vanstone, S.
A. (1997).

1936 Bibliography
 SymPy Documentation, Release 1.3

[R450] http://en.wikipedia.org/wiki/Continued_fraction
[R451] http://en.wikipedia.org/wiki/Periodic_continued_fraction
[R452] K. Rosen. Elementary Number theory and its applications. Addison-Wesley, 3 Sub
edition, pages 379-381, January 1992.
[R453] http://en.wikipedia.org/wiki/M%C3%B6bius_function
[R454] Thomas Koshy “Elementary Number Theory with Applications”
[R455] http://en.wikipedia.org/wiki/Egyptian_fraction
[R456] https://en.wikipedia.org/wiki/Greedy_algorithm_for_Egyptian_fractions
[R457] http://www.ics.uci.edu/~eppstein/numth/egypt/conflict.html
[R458] http://ami.ektf.hu/uploads/papers/finalpdf/AMI_42_from129to134.pdf
[R78] http://en.wikipedia.org/wiki/Vigenere_cipher
[R79] http://web.archive.org/web/20071116100808/ http://filebox.vt.edu/users/
batman/kryptos.html (short URL: https://goo.gl/ijr22d)
[R80] en.wikipedia.org/wiki/Hill_cipher
[R81] Lester S. Hill, Cryptography in an Algebraic Alphabet, The American Mathemat-
ical Monthly Vol.36, June-July 1929, pp.306-312.
[R82] http://en.wikipedia.org/wiki/Morse_code
[R83] http://en.wikipedia.org/wiki/Morse_code
[G83] Solomon Golomb, Shift register sequences, Aegean Park Press, Laguna Hills, Ca,
1967
[M84] James L. Massey, “Shift-Register Synthesis and BCH Decoding.” IEEE Trans. on
Information Theory, vol. 15(1), pp. 122-127, Jan 1969.
[R37] Michael Karr, “Summation in Finite Terms”, Journal of the ACM, Volume 28 Is-
sue 2, April 1981, Pages 305-350 http://dl.acm.org/citation.cfm?doid=322248.
322255
[R38] http://en.wikipedia.org/wiki/Summation#Capital-sigma_notation
[R39] http://en.wikipedia.org/wiki/Empty_sum
[R40] https://en.wikipedia.org/wiki/Absolute_convergence
[R41] https://en.wikipedia.org/wiki/Convergence_tests
[R42] Michael Karr, “Summation in Finite Terms”, Journal of the ACM, Volume 28 Is-
sue 2, April 1981, Pages 305-350 http://dl.acm.org/citation.cfm?doid=322248.
322255
[R43] Michael Karr, “Summation in Finite Terms”, Journal of the ACM, Volume 28 Is-
sue 2, April 1981, Pages 305-350 http://dl.acm.org/citation.cfm?doid=322248.
322255
[R44] http://en.wikipedia.org/wiki/Multiplication#Capital_Pi_notation
[R45] http://en.wikipedia.org/wiki/Empty_product
[R46] https://en.wikipedia.org/wiki/Infinite_product

Bibliography 1937
SymPy Documentation, Release 1.3

[R47] Michael Karr, “Summation in Finite Terms”, Journal of the ACM, Volume 28 Is-
sue 2, April 1981, Pages 305-350 http://dl.acm.org/citation.cfm?doid=322248.
322255
[R48] Marko Petkovsek, Herbert S. Wilf, Doron Zeilberger, A = B, AK Peters, Ltd.,
Wellesley, MA, USA, 1997, pp. 73–100
[R86] https://en.wikipedia.org/wiki/Cooley%E2%80%93Tukey_FFT_algorithm
[R87] http://mathworld.wolfram.com/FastFourierTransform.html
[R88] https://en.wikipedia.org/wiki/Cooley%E2%80%93Tukey_FFT_algorithm
[R89] http://mathworld.wolfram.com/FastFourierTransform.html
[R90] http://www.apfloat.org/ntt.html
[R91] http://mathworld.wolfram.com/NumberTheoreticTransform.html
[R92] https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general%29
[R93] http://www.apfloat.org/ntt.html
[R94] http://mathworld.wolfram.com/NumberTheoreticTransform.html
[R95] https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general%29
[R96] https://en.wikipedia.org/wiki/Hadamard_transform
[R97] https://en.wikipedia.org/wiki/Fast_Walsh%E2%80%93Hadamard_transform
[R98] https://en.wikipedia.org/wiki/Hadamard_transform
[R99] https://en.wikipedia.org/wiki/Fast_Walsh%E2%80%93Hadamard_transform
[R100] https://en.wikipedia.org/wiki/M%C3%B6bius_inversion_formula
[R101] https://people.csail.mit.edu/rrw/presentations/subset-conv.pdf
[R102] https://arxiv.org/pdf/1211.0189.pdf
[R103] https://en.wikipedia.org/wiki/M%C3%B6bius_inversion_formula
[R104] https://people.csail.mit.edu/rrw/presentations/subset-conv.pdf
[R105] https://arxiv.org/pdf/1211.0189.pdf
[R106] https://en.wikipedia.org/wiki/Convolution_theorem
[R107] https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general%29
[R108] https://en.wikipedia.org/wiki/Convolution_theorem
[R109] https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general%29
[R110] https://www.radioeng.cz/fulltexts/2002/02_03_40_42.pdf
[R111] https://en.wikipedia.org/wiki/Hadamard_transform
[R112] https://people.csail.mit.edu/rrw/presentations/subset-conv.pdf
[R113] https://people.csail.mit.edu/rrw/presentations/subset-conv.pdf
[R114] https://people.csail.mit.edu/rrw/presentations/subset-conv.pdf
[R25] https://docs.scipy.org/doc/numpy/user/basics.types.html
[R26] https://en.wikipedia.org/wiki/Newton%27s_method
[R153] http://en.wikipedia.org/wiki/Complex_conjugation

1938 Bibliography
 SymPy Documentation, Release 1.3

[R154] http://en.wikipedia.org/wiki/Trigonometric_functions
[R155] http://dlmf.nist.gov/4.14
[R156] http://functions.wolfram.com/ElementaryFunctions/Sin
[R157] http://mathworld.wolfram.com/TrigonometryAngles.html
[R158] http://en.wikipedia.org/wiki/Trigonometric_functions
[R159] http://dlmf.nist.gov/4.14
[R160] http://functions.wolfram.com/ElementaryFunctions/Cos
[R161] http://en.wikipedia.org/wiki/Trigonometric_functions
[R162] http://dlmf.nist.gov/4.14
[R163] http://functions.wolfram.com/ElementaryFunctions/Tan
[R164] http://en.wikipedia.org/wiki/Trigonometric_functions
[R165] http://dlmf.nist.gov/4.14
[R166] http://functions.wolfram.com/ElementaryFunctions/Cot
[R167] http://en.wikipedia.org/wiki/Trigonometric_functions
[R168] http://dlmf.nist.gov/4.14
[R169] http://functions.wolfram.com/ElementaryFunctions/Sec
[R170] http://en.wikipedia.org/wiki/Trigonometric_functions
[R171] http://dlmf.nist.gov/4.14
[R172] http://functions.wolfram.com/ElementaryFunctions/Csc
[R173] http://en.wikipedia.org/wiki/Sinc_function
[R174] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R175] http://dlmf.nist.gov/4.23
[R176] http://functions.wolfram.com/ElementaryFunctions/ArcSin
[R177] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R178] http://dlmf.nist.gov/4.23
[R179] http://functions.wolfram.com/ElementaryFunctions/ArcCos
[R180] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R181] http://dlmf.nist.gov/4.23
[R182] http://functions.wolfram.com/ElementaryFunctions/ArcTan
[R183] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R184] http://dlmf.nist.gov/4.23
[R185] http://functions.wolfram.com/ElementaryFunctions/ArcCot
[R186] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R187] http://dlmf.nist.gov/4.23
[R188] http://functions.wolfram.com/ElementaryFunctions/ArcSec
[R189] http://reference.wolfram.com/language/ref/ArcSec.html

Bibliography 1939
SymPy Documentation, Release 1.3

[R190] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R191] http://dlmf.nist.gov/4.23
[R192] http://functions.wolfram.com/ElementaryFunctions/ArcCsc
[R193] http://en.wikipedia.org/wiki/Inverse_trigonometric_functions
[R194] http://en.wikipedia.org/wiki/Atan2
[R195] http://functions.wolfram.com/ElementaryFunctions/ArcTan2
[R196] http://en.wikipedia.org/wiki/Hyperbolic_function
[R197] http://dlmf.nist.gov/4.37
[R198] http://functions.wolfram.com/ElementaryFunctions/ArcSech/
[R199] http://en.wikipedia.org/wiki/Hyperbolic_function
[R200] http://dlmf.nist.gov/4.37
[R201] http://functions.wolfram.com/ElementaryFunctions/ArcCsch/
[R202] “Concrete mathematics” by Graham, pp. 87
[R203] http://mathworld.wolfram.com/CeilingFunction.html
[R204] “Concrete mathematics” by Graham, pp. 87
[R205] http://mathworld.wolfram.com/FloorFunction.html
[R206] http://en.wikipedia.org/wiki/Fractional_part
[R207] http://mathworld.wolfram.com/FractionalPart.html
[R208] http://en.wikipedia.org/wiki/Lambert_W_function
[R209] http://en.wikipedia.org/wiki/Directed_complete_partial_order
[R210] http://en.wikipedia.org/wiki/Lattice_%28order%29
[R211] http://en.wikipedia.org/wiki/Square_root
[R212] http://en.wikipedia.org/wiki/Principal_value
[R115] http://en.wikipedia.org/wiki/Bell_number
[R116] http://mathworld.wolfram.com/BellNumber.html
[R117] http://mathworld.wolfram.com/BellPolynomial.html
[R118] http://en.wikipedia.org/wiki/Bernoulli_number
[R119] http://en.wikipedia.org/wiki/Bernoulli_polynomial
[R120] http://mathworld.wolfram.com/BernoulliNumber.html
[R121] http://mathworld.wolfram.com/BernoulliPolynomial.html
[R122] https://www.johndcook.com/blog/binomial_coefficients/
[R123] http://en.wikipedia.org/wiki/Catalan_number
[R124] http://mathworld.wolfram.com/CatalanNumber.html
[R125] http://functions.wolfram.com/GammaBetaErf/CatalanNumber/
[R126] http://geometer.org/mathcircles/catalan.pdf
[R127] http://en.wikipedia.org/wiki/Euler_numbers

1940 Bibliography
 SymPy Documentation, Release 1.3

[R128] http://mathworld.wolfram.com/EulerNumber.html
[R129] http://en.wikipedia.org/wiki/Alternating_permutation
[R130] http://mathworld.wolfram.com/AlternatingPermutation.html
[R131] http://dlmf.nist.gov/24.2#ii
[R132] http://en.wikipedia.org/wiki/Subfactorial
[R133] http://mathworld.wolfram.com/Subfactorial.html
[R134] https://en.wikipedia.org/wiki/Double_factorial
[R135] http://mathworld.wolfram.com/FallingFactorial.html
[R136] http://en.wikipedia.org/wiki/Fibonacci_number
[R137] http://mathworld.wolfram.com/FibonacciNumber.html
[R138] https://en.wikipedia.org/wiki/Generalizations_of_Fibonacci_numbers#
Tribonacci_numbers
[R139] http://mathworld.wolfram.com/TribonacciNumber.html
[R140] https://oeis.org/A000073
[R141] http://en.wikipedia.org/wiki/Harmonic_number
[R142] http://functions.wolfram.com/GammaBetaErf/HarmonicNumber/
[R143] http://functions.wolfram.com/GammaBetaErf/HarmonicNumber2/
[R144] http://en.wikipedia.org/wiki/Lucas_number
[R145] http://mathworld.wolfram.com/LucasNumber.html
[R146] https://en.wikipedia.org/wiki/Genocchi_number
[R147] http://mathworld.wolfram.com/GenocchiNumber.html
[R148] https://en.wikipedia.org/wiki/Partition_(number_theory%29
[R149] https://en.wikipedia.org/wiki/Pentagonal_number_theorem
[R150] https://en.wikipedia.org/wiki/Pochhammer_symbol
[R151] http://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind
[R152] http://en.wikipedia.org/wiki/Stirling_numbers_of_the_second_kind
[R213] http://mathworld.wolfram.com/DeltaFunction.html
[R214] Regarding to the value at 0, Mathematica defines H(0) = 1, but Maple uses H(0)
= undefined. Different application areas may have specific conventions. For ex-
ample, in control theory, it is common practice to assume H(0) == 0 to match
the Laplace transform of a DiracDelta distribution.
[R215] http://mathworld.wolfram.com/HeavisideStepFunction.html
[R216] http://dlmf.nist.gov/1.16#iv
[R217] https://en.wikipedia.org/wiki/Singularity_function
[R218] http://en.wikipedia.org/wiki/Gamma_function
[R219] http://dlmf.nist.gov/5
[R220] http://mathworld.wolfram.com/GammaFunction.html

Bibliography 1941
SymPy Documentation, Release 1.3

[R221] http://functions.wolfram.com/GammaBetaErf/Gamma/
[R222] http://en.wikipedia.org/wiki/Gamma_function
[R223] http://dlmf.nist.gov/5
[R224] http://mathworld.wolfram.com/LogGammaFunction.html
[R225] http://functions.wolfram.com/GammaBetaErf/LogGamma/
[R226] http://en.wikipedia.org/wiki/Polygamma_function
[R227] http://mathworld.wolfram.com/PolygammaFunction.html
[R228] http://functions.wolfram.com/GammaBetaErf/PolyGamma/
[R229] http://functions.wolfram.com/GammaBetaErf/PolyGamma2/
[R230] http://en.wikipedia.org/wiki/Digamma_function
[R231] http://mathworld.wolfram.com/DigammaFunction.html
[R232] http://functions.wolfram.com/GammaBetaErf/PolyGamma2/
[R233] http://en.wikipedia.org/wiki/Trigamma_function
[R234] http://mathworld.wolfram.com/TrigammaFunction.html
[R235] http://functions.wolfram.com/GammaBetaErf/PolyGamma2/
[R236] http://en.wikipedia.org/wiki/Incomplete_gamma_function#Upper_incomplete_
Gamma_function
[R237] Abramowitz, Milton; Stegun, Irene A., eds. (1965), Chapter 6, Section 5, Hand-
book of Mathematical Functions with Formulas, Graphs, and Mathematical Tables
[R238] http://dlmf.nist.gov/8
[R239] http://functions.wolfram.com/GammaBetaErf/Gamma2/
[R240] http://functions.wolfram.com/GammaBetaErf/Gamma3/
[R241] http://en.wikipedia.org/wiki/Exponential_integral#Relation_with_other_
functions
[R242] http://en.wikipedia.org/wiki/Incomplete_gamma_function#Lower_incomplete_
Gamma_function
[R243] Abramowitz, Milton; Stegun, Irene A., eds. (1965), Chapter 6, Section 5, Hand-
book of Mathematical Functions with Formulas, Graphs, and Mathematical Tables
[R244] http://dlmf.nist.gov/8
[R245] http://functions.wolfram.com/GammaBetaErf/Gamma2/
[R246] http://functions.wolfram.com/GammaBetaErf/Gamma3/
[R247] http://en.wikipedia.org/wiki/Beta_function
[R248] http://mathworld.wolfram.com/BetaFunction.html
[R249] http://dlmf.nist.gov/5.12
[R250] http://en.wikipedia.org/wiki/Error_function
[R251] http://dlmf.nist.gov/7
[R252] http://mathworld.wolfram.com/Erf.html
[R253] http://functions.wolfram.com/GammaBetaErf/Erf

1942 Bibliography
 SymPy Documentation, Release 1.3

[R254] http://en.wikipedia.org/wiki/Error_function
[R255] http://dlmf.nist.gov/7
[R256] http://mathworld.wolfram.com/Erfc.html
[R257] http://functions.wolfram.com/GammaBetaErf/Erfc
[R258] http://en.wikipedia.org/wiki/Error_function
[R259] http://mathworld.wolfram.com/Erfi.html
[R260] http://functions.wolfram.com/GammaBetaErf/Erfi
[R261] http://functions.wolfram.com/GammaBetaErf/Erf2/
[R262] http://en.wikipedia.org/wiki/Error_function#Inverse_functions
[R263] http://functions.wolfram.com/GammaBetaErf/InverseErf/
[R264] http://en.wikipedia.org/wiki/Error_function#Inverse_functions
[R265] http://functions.wolfram.com/GammaBetaErf/InverseErfc/
[R266] http://functions.wolfram.com/GammaBetaErf/InverseErf2/
[R267] http://en.wikipedia.org/wiki/Fresnel_integral
[R268] http://dlmf.nist.gov/7
[R269] http://mathworld.wolfram.com/FresnelIntegrals.html
[R270] http://functions.wolfram.com/GammaBetaErf/FresnelS
[R271] The converging factors for the fresnel integrals by John W. Wrench Jr. and Vicki
Alley
[R272] http://en.wikipedia.org/wiki/Fresnel_integral
[R273] http://dlmf.nist.gov/7
[R274] http://mathworld.wolfram.com/FresnelIntegrals.html
[R275] http://functions.wolfram.com/GammaBetaErf/FresnelC
[R276] The converging factors for the fresnel integrals by John W. Wrench Jr. and Vicki
Alley
[R277] http://dlmf.nist.gov/6.6
[R278] http://en.wikipedia.org/wiki/Exponential_integral
[R279] Abramowitz & Stegun, section 5: http://people.math.sfu.ca/~cbm/aands/page_
228.htm
[R280] http://dlmf.nist.gov/8.19
[R281] http://functions.wolfram.com/GammaBetaErf/ExpIntegralE/
[R282] http://en.wikipedia.org/wiki/Exponential_integral
[R283] http://en.wikipedia.org/wiki/Logarithmic_integral
[R284] http://mathworld.wolfram.com/LogarithmicIntegral.html
[R285] http://dlmf.nist.gov/6
[R286] http://mathworld.wolfram.com/SoldnersConstant.html
[R287] http://en.wikipedia.org/wiki/Logarithmic_integral

Bibliography 1943
SymPy Documentation, Release 1.3

[R288] http://mathworld.wolfram.com/LogarithmicIntegral.html
[R289] http://dlmf.nist.gov/6
[R290] http://en.wikipedia.org/wiki/Trigonometric_integral
[R291] http://en.wikipedia.org/wiki/Trigonometric_integral
[R292] http://en.wikipedia.org/wiki/Trigonometric_integral
[R293] http://en.wikipedia.org/wiki/Trigonometric_integral
[R294] Abramowitz, Milton; Stegun, Irene A., eds. (1965), “Chapter 9”, Handbook of
Mathematical Functions with Formulas, Graphs, and Mathematical Tables
[R295] Luke, Y. L. (1969), The Special Functions and Their Approximations, Volume 1
[R296] http://en.wikipedia.org/wiki/Bessel_function
[R297] http://functions.wolfram.com/Bessel-TypeFunctions/BesselJ/
[R298] http://functions.wolfram.com/Bessel-TypeFunctions/BesselY/
[R299] http://functions.wolfram.com/Bessel-TypeFunctions/BesselI/
[R300] http://functions.wolfram.com/Bessel-TypeFunctions/BesselK/
[R301] http://functions.wolfram.com/Bessel-TypeFunctions/HankelH1/
[R302] http://functions.wolfram.com/Bessel-TypeFunctions/HankelH2/
[R303] http://dlmf.nist.gov/10.47
[R304] http://dlmf.nist.gov/10.47
[R305] http://en.wikipedia.org/wiki/Airy_function
[R306] http://dlmf.nist.gov/9
[R307] http://www.encyclopediaofmath.org/index.php/Airy_functions
[R308] http://mathworld.wolfram.com/AiryFunctions.html
[R309] http://en.wikipedia.org/wiki/Airy_function
[R310] http://dlmf.nist.gov/9
[R311] http://www.encyclopediaofmath.org/index.php/Airy_functions
[R312] http://mathworld.wolfram.com/AiryFunctions.html
[R313] http://en.wikipedia.org/wiki/Airy_function
[R314] http://dlmf.nist.gov/9
[R315] http://www.encyclopediaofmath.org/index.php/Airy_functions
[R316] http://mathworld.wolfram.com/AiryFunctions.html
[R317] http://en.wikipedia.org/wiki/Airy_function
[R318] http://dlmf.nist.gov/9
[R319] http://www.encyclopediaofmath.org/index.php/Airy_functions
[R320] http://mathworld.wolfram.com/AiryFunctions.html
[R321] http://en.wikipedia.org/wiki/B-spline
[R322] http://dlmf.nist.gov/25.11

1944 Bibliography
 SymPy Documentation, Release 1.3

[R323] http://en.wikipedia.org/wiki/Hurwitz_zeta_function
[R324] http://en.wikipedia.org/wiki/Dirichlet_eta_function
[R325] Bateman, H.; Erdelyi, A. (1953), Higher Transcendental Functions, Vol. I, New
York: McGraw-Hill. Section 1.11.
[R326] http://dlmf.nist.gov/25.14
[R327] http://en.wikipedia.org/wiki/Lerch_transcendent
[R328] http://en.wikipedia.org/wiki/Stieltjes_constants
[R329] Luke, Y. L. (1969), The Special Functions and Their Approximations, Volume 1
[R330] http://en.wikipedia.org/wiki/Generalized_hypergeometric_function
[R331] Luke, Y. L. (1969), The Special Functions and Their Approximations, Volume 1
[R332] http://en.wikipedia.org/wiki/Meijer_G-function
[R333] http://en.wikipedia.org/wiki/Elliptic_integrals
[R334] http://functions.wolfram.com/EllipticIntegrals/EllipticK
[R335] http://en.wikipedia.org/wiki/Elliptic_integrals
[R336] http://functions.wolfram.com/EllipticIntegrals/EllipticF
[R337] http://en.wikipedia.org/wiki/Elliptic_integrals
[R338] http://functions.wolfram.com/EllipticIntegrals/EllipticE2
[R339] http://functions.wolfram.com/EllipticIntegrals/EllipticE
[R340] http://en.wikipedia.org/wiki/Elliptic_integrals
[R341] http://functions.wolfram.com/EllipticIntegrals/EllipticPi3
[R342] http://functions.wolfram.com/EllipticIntegrals/EllipticPi
[R343] http://en.wikipedia.org/wiki/Mathieu_function
[R344] http://dlmf.nist.gov/28
[R345] http://mathworld.wolfram.com/MathieuBase.html
[R346] http://functions.wolfram.com/MathieuandSpheroidalFunctions/MathieuS/
[R347] http://en.wikipedia.org/wiki/Mathieu_function
[R348] http://dlmf.nist.gov/28
[R349] http://mathworld.wolfram.com/MathieuBase.html
[R350] http://functions.wolfram.com/MathieuandSpheroidalFunctions/MathieuC/
[R351] http://en.wikipedia.org/wiki/Mathieu_function
[R352] http://dlmf.nist.gov/28
[R353] http://mathworld.wolfram.com/MathieuBase.html
[R354] http://functions.wolfram.com/MathieuandSpheroidalFunctions/MathieuSPrime/
[R355] http://en.wikipedia.org/wiki/Mathieu_function
[R356] http://dlmf.nist.gov/28
[R357] http://mathworld.wolfram.com/MathieuBase.html

Bibliography 1945
SymPy Documentation, Release 1.3

[R358] http://functions.wolfram.com/MathieuandSpheroidalFunctions/MathieuCPrime/
[R359] http://en.wikipedia.org/wiki/Jacobi_polynomials
[R360] http://mathworld.wolfram.com/JacobiPolynomial.html
[R361] http://functions.wolfram.com/Polynomials/JacobiP/
[R362] http://en.wikipedia.org/wiki/Jacobi_polynomials
[R363] http://mathworld.wolfram.com/JacobiPolynomial.html
[R364] http://functions.wolfram.com/Polynomials/JacobiP/
[R365] http://en.wikipedia.org/wiki/Gegenbauer_polynomials
[R366] http://mathworld.wolfram.com/GegenbauerPolynomial.html
[R367] http://functions.wolfram.com/Polynomials/GegenbauerC3/
[R368] http://en.wikipedia.org/wiki/Chebyshev_polynomial
[R369] http://mathworld.wolfram.com/ChebyshevPolynomialoftheFirstKind.html
[R370] http://mathworld.wolfram.com/ChebyshevPolynomialoftheSecondKind.html
[R371] http://functions.wolfram.com/Polynomials/ChebyshevT/
[R372] http://functions.wolfram.com/Polynomials/ChebyshevU/
[R373] http://en.wikipedia.org/wiki/Chebyshev_polynomial
[R374] http://mathworld.wolfram.com/ChebyshevPolynomialoftheFirstKind.html
[R375] http://mathworld.wolfram.com/ChebyshevPolynomialoftheSecondKind.html
[R376] http://functions.wolfram.com/Polynomials/ChebyshevT/
[R377] http://functions.wolfram.com/Polynomials/ChebyshevU/
[R378] http://en.wikipedia.org/wiki/Legendre_polynomial
[R379] http://mathworld.wolfram.com/LegendrePolynomial.html
[R380] http://functions.wolfram.com/Polynomials/LegendreP/
[R381] http://functions.wolfram.com/Polynomials/LegendreP2/
[R382] http://en.wikipedia.org/wiki/Associated_Legendre_polynomials
[R383] http://mathworld.wolfram.com/LegendrePolynomial.html
[R384] http://functions.wolfram.com/Polynomials/LegendreP/
[R385] http://functions.wolfram.com/Polynomials/LegendreP2/
[R386] http://en.wikipedia.org/wiki/Hermite_polynomial
[R387] http://mathworld.wolfram.com/HermitePolynomial.html
[R388] http://functions.wolfram.com/Polynomials/HermiteH/
[R389] http://en.wikipedia.org/wiki/Laguerre_polynomial
[R390] http://mathworld.wolfram.com/LaguerrePolynomial.html
[R391] http://functions.wolfram.com/Polynomials/LaguerreL/
[R392] http://functions.wolfram.com/Polynomials/LaguerreL3/
[R393] http://en.wikipedia.org/wiki/Laguerre_polynomial#Assoc_laguerre_polynomials

1946 Bibliography
 SymPy Documentation, Release 1.3

[R394] http://mathworld.wolfram.com/AssociatedLaguerrePolynomial.html
[R395] http://functions.wolfram.com/Polynomials/LaguerreL/
[R396] http://functions.wolfram.com/Polynomials/LaguerreL3/
[R397] http://en.wikipedia.org/wiki/Spherical_harmonics
[R398] http://mathworld.wolfram.com/SphericalHarmonic.html
[R399] http://functions.wolfram.com/Polynomials/SphericalHarmonicY/
[R400] http://dlmf.nist.gov/14.30
[R401] http://en.wikipedia.org/wiki/Spherical_harmonics
[R402] http://mathworld.wolfram.com/SphericalHarmonic.html
[R403] http://functions.wolfram.com/Polynomials/SphericalHarmonicY/
[R404] http://en.wikipedia.org/wiki/Spherical_harmonics
[R405] http://mathworld.wolfram.com/SphericalHarmonic.html
[R406] http://functions.wolfram.com/Polynomials/SphericalHarmonicY/
[R407] http://en.wikipedia.org/wiki/Kronecker_delta
[WikiPappus] “Pappus’s Hexagon Theorem” Wikipedia, the Free Encyclopedia. Web. 26 Apr.
2013. <http://en.wikipedia.org/wiki/Pappus’s_hexagon_theorem>
[R408] https://hal.inria.fr/inria-00070025/document
[R409] http://www.risc.jku.at/publications/download/risc_2244/DIPLFORM.pdf
[BlogPost] http://nessgrh.wordpress.com/2011/07/07/tricky-branch-cuts/
[R410] http://en.wikipedia.org/wiki/Cauchy_principal_value
[R411] http://mathworld.wolfram.com/CauchyPrincipalValue.html
[R412] http://en.wikipedia.org/wiki/Gaussian_quadrature
[R413] http://people.sc.fsu.edu/~jburkardt/cpp_src/legendre_rule/legendre_rule.html
[R414] http://en.wikipedia.org/wiki/Gauss%E2%80%93Laguerre_quadrature
[R415] http://people.sc.fsu.edu/~jburkardt/cpp_src/laguerre_rule/laguerre_rule.html
[R416] http://en.wikipedia.org/wiki/Gauss-Hermite_Quadrature
[R417] http://people.sc.fsu.edu/~jburkardt/cpp_src/hermite_rule/hermite_rule.html
[R418] http://people.sc.fsu.edu/~jburkardt/cpp_src/gen_hermite_rule/gen_hermite_
rule.html
[R419] http://en.wikipedia.org/wiki/Gauss%E2%80%93Laguerre_quadrature
[R420] http://people.sc.fsu.edu/~jburkardt/cpp_src/gen_laguerre_rule/gen_laguerre_
rule.html
[R421] http://en.wikipedia.org/wiki/Chebyshev%E2%80%93Gauss_quadrature
[R422] http://people.sc.fsu.edu/~jburkardt/cpp_src/chebyshev1_rule/chebyshev1_rule.
html
[R423] http://en.wikipedia.org/wiki/Chebyshev%E2%80%93Gauss_quadrature
[R424] http://people.sc.fsu.edu/~jburkardt/cpp_src/chebyshev2_rule/chebyshev2_rule.
html

Bibliography 1947
SymPy Documentation, Release 1.3

[R425] http://en.wikipedia.org/wiki/Gauss%E2%80%93Jacobi_quadrature
[R426] http://people.sc.fsu.edu/~jburkardt/cpp_src/jacobi_rule/jacobi_rule.html
[R427] http://people.sc.fsu.edu/~jburkardt/cpp_src/gegenbauer_rule/gegenbauer_rule.
html
[R428] en.wikipedia.org/wiki/Quine-McCluskey_algorithm
[R429] en.wikipedia.org/wiki/Quine-McCluskey_algorithm
[R430] http://en.wikipedia.org/wiki/Gaussian_elimination
[R431] https://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse
[R432] https://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse#Obtaining_all_
solutions_of_a_linear_system
[Wester1999] Michael J. Wester, A Critique of the Mathematical Abilities of CA Systems, 1999,
http://www.math.unm.edu/~wester/cas/book/Wester.pdf
[Kozen89] D. Kozen, S. Landau, Polynomial decomposition algorithms, Journal of Symbolic
Computation 7 (1989), pp. 445-456
[Liao95] Hsin-Chao Liao, R. Fateman, Evaluation of the heuristic polynomial GCD, Interna-
tional Symposium on Symbolic and Algebraic Computation (ISSAC), ACM Press,
Montreal, Quebec, Canada, 1995, pp. 240–247
[Gathen99] J. von zur Gathen, J. Gerhard, Modern Computer Algebra, First Edition, Cam-
bridge University Press, 1999
[Weisstein09] Eric W. Weisstein, Cyclotomic Polynomial, From MathWorld - A Wolfram Web
Resource, http://mathworld.wolfram.com/CyclotomicPolynomial.html
[Wang78] P. S. Wang, An Improved Multivariate Polynomial Factoring Algorithm, Math. of
Computation 32, 1978, pp. 1215–1231
[Geddes92] K. Geddes, S. R. Czapor, G. Labahn, Algorithms for Computer Algebra, Springer,
1992
[Monagan93] Michael Monagan, In-place Arithmetic for Polynomials over Z_n, Proceedings
of DISCO ‘92, Springer-Verlag LNCS, 721, 1993, pp. 22–34
[Kaltofen98] E. Kaltofen, V. Shoup, Subquadratic-time Factoring of Polynomials over Finite
Fields, Mathematics of Computation, Volume 67, Issue 223, 1998, pp. 1179–1197
[Shoup95] V. Shoup, A New Polynomial Factorization Algorithm and its Implementation,
Journal of Symbolic Computation, Volume 20, Issue 4, 1995, pp. 363–397
[Gathen92] J. von zur Gathen, V. Shoup, Computing Frobenius Maps and Factoring Polyno-
mials, ACM Symposium on Theory of Computing, 1992, pp. 187–224
[Shoup91] V. Shoup, A Fast Deterministic Algorithm for Factoring Polynomials over Finite
Fields of Small Characteristic, In Proceedings of International Symposium on
Symbolic and Algebraic Computation, 1991, pp. 14–21
[Cox97] D. Cox, J. Little, D. O’Shea, Ideals, Varieties and Algorithms, Springer, Second
Edition, 1997
[Ajwa95] I.A. Ajwa, Z. Liu, P.S. Wang, Groebner Bases Algorithm, https://citeseer.ist.psu.
edu/myciteseer/login, 1995
[Bose03] N.K. Bose, B. Buchberger, J.P. Guiver, Multidimensional Systems Theory and Ap-
plications, Springer, 2003

1948 Bibliography
 SymPy Documentation, Release 1.3

[Giovini91] A. Giovini, T. Mora, “One sugar cube, please” or Selection strategies in Buch-
berger algorithm, ISSAC ‘91, ACM
[Bronstein93] M. Bronstein, B. Salvy, Full partial fraction decomposition of rational functions,
Proceedings ISSAC ‘93, ACM Press, Kiev, Ukraine, 1993, pp. 157–160
[Buchberger01] B. Buchberger, Groebner Bases: A Short Introduction for Systems Theorists,
In: R. Moreno-Diaz, B. Buchberger, J. L. Freire, Proceedings of EUROCAST‘01,
February, 2001
[Davenport88] J.H. Davenport, Y. Siret, E. Tournier, Computer Algebra Systems and Algo-
rithms for Algebraic Computation, Academic Press, London, 1988, pp. 124–128
[Greuel2008] G.-M. Greuel, Gerhard Pfister, A Singular Introduction to Commutative Algebra,
Springer, 2008
[Atiyah69] M.F. Atiyah, I.G. MacDonald, Introduction to Commutative Algebra, Addison-
Wesley, 1969
[Collins67] G.E. Collins, Subresultants and Reduced Polynomial Remainder Sequences. J.
ACM 14 (1967) 128-142
[BrownTraub71] W.S. Brown, J.F. Traub, On Euclid’s Algorithm and the Theory of Subresul-
tants. J. ACM 18 (1971) 505-514
[Brown78] W.S. Brown, The Subresultant PRS Algorithm. ACM Transaction of Mathematical
Software 4 (1978) 237-249
[Monagan00] M. Monagan and A. Wittkopf, On the Design and Implementation of Brown’s
Algorithm over the Integers and Number Fields, Proceedings of ISSAC 2000, pp.
225-233, ACM, 2000.
[Brown71] W.S. Brown, On Euclid’s Algorithm and the Computation of Polynomial Greatest
Common Divisors, J. ACM 18, 4, pp. 478-504, 1971.
[Hoeij04] M. van Hoeij and M. Monagan, Algorithms for polynomial GCD computation over
algebraic function fields, Proceedings of ISSAC 2004, pp. 297-304, ACM, 2004.
[Wang81] P.S. Wang, A p-adic algorithm for univariate partial fractions, Proceedings of SYM-
SAC 1981, pp. 212-217, ACM, 1981.
[Hoeij02] M. van Hoeij and M. Monagan, A modular GCD algorithm over number fields
presented with multiple extensions, Proceedings of ISSAC 2002, pp. 109-116,
ACM, 2002
[ManWright94] Yiu-Kwong Man and Francis J. Wright, “Fast Polynomial Dispersion Compu-
tation and its Application to Indefinite Summation”, Proceedings of the Interna-
tional Symposium on Symbolic and Algebraic Computation, 1994, Pages 175-180
http://dl.acm.org/citation.cfm?doid=190347.190413
[Koepf98] Wolfram Koepf, “Hypergeometric Summation: An Algorithmic Approach to Sum-
mation and Special Function Identities”, Advanced lectures in mathematics,
Vieweg, 1998
[Abramov71] S. A. Abramov, “On the Summation of Rational Functions”, USSR Computational
Mathematics and Mathematical Physics, Volume 11, Issue 4, 1971, Pages 324-330
[Man93] Yiu-Kwong Man, “On Computing Closed Forms for Indefinite Summations”, Jour-
nal of Symbolic Computation, Volume 16, Issue 4, 1993, Pages 355-376 http:
//www.sciencedirect.com/science/article/pii/S0747717183710539
[Kapur1994] Deepak Kapur, Tushar Saxena, and Lu Yang. “Algebraic and geometric rea-
soning using Dixon resultants”, In Proceedings of the international symposium

Bibliography 1949
SymPy Documentation, Release 1.3

on Symbolic and algebraic computation (ISSAC ‘94), 1994, pages 99-107.

https://www.researchgate.net/publication/2514261_Algebraic_and_Geometric_
Reasoning_using_Dixon_Resultants
[Palancz08] B Paláncz, P Zaletnyik, JL Awange, EW Grafarend. “Dixon resultant’s solution
of systems of geodetic polynomial equations”, Journal of Geodesy, 2008, Springer,
https://www.researchgate.net/publication/225607735_Dixon_resultant’s_solution_of_systems_o
[Bruce97] Bruce Randall Donald, Deepak Kapur, and Joseph L. Mundy (Eds.). “Symbolic
and Numerical Computation for Artificial Intelligence”, Chapter 2, Academic
Press, Inc., Orlando, FL, USA, 1997, https://www2.cs.duke.edu/donaldlab/Books/
SymbolicNumericalComputation/045-087.pdf.
[Stiller96] P Stiller. “An introduction to the theory of resultants”, Mathematics and Com-
puter Science, T&M University, 1996, Citeseer, http://citeseerx.ist.psu.edu/
viewdoc/download?doi=10.1.1.590.2021&rep=rep1&type=pdf.
[R1] http://en.wikipedia.org/wiki/Algebraic_number
[R2] http://mathworld.wolfram.com/HermitianOperator.html
[R3] https://en.wikipedia.org/wiki/Complex_number
[R4] https://en.wikipedia.org/wiki/Diagonal_matrix
[R5] https://en.wikipedia.org/wiki/Finite
[R6] http://mathworld.wolfram.com/HermitianOperator.html
[R7] https://en.wikipedia.org/wiki/Imaginary_number
[R8] https://en.wikipedia.org/wiki/Integer
[R9] https://en.wikipedia.org/wiki/Invertible_matrix
[R10] https://en.wikipedia.org/wiki/Irrational_number
[R11] http://mathworld.wolfram.com/LowerTriangularMatrix.html
[R12] https://en.wikipedia.org/wiki/Normal_matrix
[R13] https://en.wikipedia.org/wiki/Orthogonal_matrix
[R14] https://en.wikipedia.org/wiki/Positive-definite_matrix
[R15] https://en.wikipedia.org/wiki/Real_number
[R16] http://mathworld.wolfram.com/SingularMatrix.html
[R17] https://en.wikipedia.org/wiki/Square_matrix
[R18] https://en.wikipedia.org/wiki/Symmetric_matrix
[R19] https://en.wikipedia.org/wiki/Triangular_matrix
[R20] https://en.wikipedia.org/wiki/Unitary_matrix
[R21] http://mathworld.wolfram.com/UpperTriangularMatrix.html
[R497] Big O notation
[R492] https://en.wikipedia.org/wiki/Gibbs_phenomenon
[R493] https://en.wikipedia.org/wiki/Sigma_approximation
[R494] mathworld.wolfram.com/FourierSeries.html
[R488] Formal Power Series - Dominik Gruntz, Wolfram Koepf

1950 Bibliography
 SymPy Documentation, Release 1.3

[R489] Power Series in Computer Algebra - Wolfram Koepf

[R490] Formal Power Series - Dominik Gruntz, Wolfram Koepf
[R491] Power Series in Computer Algebra - Wolfram Koepf
[R495] https://reference.wolfram.com/language/ref/DifferenceDelta.html
[R496] Computing Limits of Sequences - Manuel Kauers
[R498] http://en.wikipedia.org/wiki/Disjoint_sets
[R499] http://en.wikipedia.org/wiki/Power_set
[R500] https://en.wikipedia.org/wiki/Symmetric_difference
[R501] http://en.wikipedia.org/wiki/Interval_%28mathematics%29
[R502] http://en.wikipedia.org/wiki/Finite_set
[R503] http://en.wikipedia.org/wiki/Union_%28set_theory%29
[R504] http://en.wikipedia.org/wiki/Intersection_%28set_theory%29
[R505] http://en.wikipedia.org/wiki/Cartesian_product
[R506] http://mathworld.wolfram.com/ComplementSet.html
[R507] http://en.wikipedia.org/wiki/Empty_set
[R508] http://en.wikipedia.org/wiki/Universal_set
[Roach1996] Kelly B. Roach. Hypergeometric Function Representations. In: Proceedings
of the 1996 International Symposium on Symbolic and Algebraic Computation,
pages 301-308, New York, 1996. ACM.
[Roach1997] Kelly B. Roach. Meijer G Function Representations. In: Proceedings of the 1997
International Symposium on Symbolic and Algebraic Computation, pages 205-
211, New York, 1997. ACM.
[Luke1969] Luke, Y. L. (1969), The Special Functions and Their Approximations, Volume 1.
[Prudnikov1990] A. P. Prudnikov, Yu. A. Brychkov and O. I. Marichev (1990). Integrals and
Series: More Special Functions, Vol. 3, Gordon and Breach Science Publisher.
[R538] http://en.wikipedia.org/wiki/Arcsine_distribution
[R539] http://en.wikipedia.org/wiki/Benini_distribution
[R540] http://reference.wolfram.com/legacy/v8/ref/BeniniDistribution.html
[R541] http://en.wikipedia.org/wiki/Beta_distribution
[R542] http://mathworld.wolfram.com/BetaDistribution.html
[R543] http://en.wikipedia.org/wiki/Beta_prime_distribution
[R544] http://mathworld.wolfram.com/BetaPrimeDistribution.html
[R545] http://en.wikipedia.org/wiki/Cauchy_distribution
[R546] http://mathworld.wolfram.com/CauchyDistribution.html
[R547] http://en.wikipedia.org/wiki/Chi_distribution
[R548] http://mathworld.wolfram.com/ChiDistribution.html
[R549] http://en.wikipedia.org/wiki/Noncentral_chi_distribution
[R550] http://en.wikipedia.org/wiki/Chi_squared_distribution

Bibliography 1951
SymPy Documentation, Release 1.3

[R551] http://mathworld.wolfram.com/Chi-SquaredDistribution.html
[R552] http://en.wikipedia.org/wiki/Dagum_distribution
[R553] http://en.wikipedia.org/wiki/Erlang_distribution
[R554] http://mathworld.wolfram.com/ErlangDistribution.html
[R555] http://en.wikipedia.org/wiki/Exponential_distribution
[R556] http://mathworld.wolfram.com/ExponentialDistribution.html
[R557] http://en.wikipedia.org/wiki/F-distribution
[R558] http://mathworld.wolfram.com/F-Distribution.html
[R559] http://en.wikipedia.org/wiki/Fisher%27s_z-distribution
[R560] http://mathworld.wolfram.com/Fishersz-Distribution.html
[R561] http://en.wikipedia.org/wiki/Fr%C3%A9chet_distribution
[R562] http://en.wikipedia.org/wiki/Gamma_distribution
[R563] http://mathworld.wolfram.com/GammaDistribution.html
[R564] http://en.wikipedia.org/wiki/Inverse-gamma_distribution
[R565] http://en.wikipedia.org/wiki/Kumaraswamy_distribution
[R566] http://en.wikipedia.org/wiki/Laplace_distribution
[R567] http://mathworld.wolfram.com/LaplaceDistribution.html
[R568] http://en.wikipedia.org/wiki/Logistic_distribution
[R569] http://mathworld.wolfram.com/LogisticDistribution.html
[R570] http://en.wikipedia.org/wiki/Lognormal
[R571] http://mathworld.wolfram.com/LogNormalDistribution.html
[R572] http://en.wikipedia.org/wiki/Maxwell_distribution
[R573] http://mathworld.wolfram.com/MaxwellDistribution.html
[R574] http://en.wikipedia.org/wiki/Nakagami_distribution
[R575] http://en.wikipedia.org/wiki/Normal_distribution
[R576] http://mathworld.wolfram.com/NormalDistributionFunction.html
[R577] http://en.wikipedia.org/wiki/Pareto_distribution
[R578] http://mathworld.wolfram.com/ParetoDistribution.html
[R579] http://en.wikipedia.org/wiki/U-quadratic_distribution
[R580] http://en.wikipedia.org/wiki/Raised_cosine_distribution
[R581] http://en.wikipedia.org/wiki/Rayleigh_distribution
[R582] http://mathworld.wolfram.com/RayleighDistribution.html
[R583] http://en.wikipedia.org/wiki/Student_t-distribution
[R584] http://mathworld.wolfram.com/Studentst-Distribution.html
[R585] http://en.wikipedia.org/wiki/Triangular_distribution
[R586] http://mathworld.wolfram.com/TriangularDistribution.html

1952 Bibliography
 SymPy Documentation, Release 1.3

[R587] http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29
[R588] http://mathworld.wolfram.com/UniformDistribution.html
[R589] http://en.wikipedia.org/wiki/Uniform_sum_distribution
[R590] http://mathworld.wolfram.com/UniformSumDistribution.html
[R591] http://en.wikipedia.org/wiki/Von_Mises_distribution
[R592] http://mathworld.wolfram.com/vonMisesDistribution.html
[R593] http://en.wikipedia.org/wiki/Weibull_distribution
[R594] http://mathworld.wolfram.com/WeibullDistribution.html
[R595] http://en.wikipedia.org/wiki/Wigner_semicircle_distribution
[R596] http://mathworld.wolfram.com/WignersSemicircleLaw.html
[R532] S. A. Abramov, M. Bronstein and M. Petkovsek, On polynomial solutions of linear
operator equations, in: T. Levelt, ed., Proc. ISSAC ‘95, ACM Press, New York,
1995, 290-296.
[R533] M. Petkovsek, Hypergeometric solutions of linear recurrences with polynomial
coefficients, J. Symbolic Computation, 14 (1992), 243-264.
[R534] M. Petkovsek, H. S. Wilf, D. Zeilberger, A = B, 1996.
[R535] S. A. Abramov, Rational solutions of linear difference and q-difference equations
with polynomial coefficients, in: T. Levelt, ed., Proc. ISSAC ‘95, ACM Press, New
York, 1995, 285-289
[R536] M. Petkovsek, Hypergeometric solutions of linear recurrences with polynomial
coefficients, J. Symbolic Computation, 14 (1992), 243-264.
[R537] M. Petkovsek, H. S. Wilf, D. Zeilberger, A = B, 1996.
[R509] Methods to solve Ax^2 + Bxy + Cy^2 + Dx + Ey + F = 0, [online], Available:
http://www.alpertron.com.ar/METHODS.HTM
[R510] Solving the equation ax^2+ bxy + cy^2 + dx + ey + f= 0, [online], Available:
http://www.jpr2718.org/ax2p.pdf
[R511] Solving the generalized Pell equation x**2 - D*y**2 = N, John P. Robertson, July
31, 2004, Pages 16 - 17. [online], Available: http://www.jpr2718.org/pell.pdf
[R512] A. Nitaj, “L’algorithme de Cornacchia”
[R513] Solving the diophantine equation ax**2 + by**2 = m by Cornacchia’s method,
[online], Available: http://www.numbertheory.org/php/cornacchia.html
[R514] Solving the generalized Pell equation x**2 - D*y**2 = N, John P. Robertson, July
31, 2004, Page 15. http://www.jpr2718.org/pell.pdf
[R515] Solving the equation ax^2 + bxy + cy^2 + dx + ey + f = 0, John P.Robertson,
May 8, 2003, Page 7 - 11. http://www.jpr2718.org/ax2p.pdf
[R516] Solving the equation ax^2 + bxy + cy^2 + dx + ey + f = 0, John P.Robertson,
May 8, 2003, Page 7 - 11. http://www.jpr2718.org/ax2p.pdf
[R517] Efficient Solution of Rational Conices, J. E. Cremona and D. Rusin, Mathematics
of Computation, Volume 00, Number 0.
[R518] Representing an integer as a sum of three squares, [online], Available: http://
www.proofwiki.org/wiki/Integer_as_Sum_of_Three_Squares

Bibliography 1953
SymPy Documentation, Release 1.3

[R519] Representing a number as a sum of three squares, [online], Available: http://

schorn.ch/lagrange.html
[R520] Representing a number as a sum of four squares, [online], Available: http:
//schorn.ch/lagrange.html
[R521] Solving the generalized Pell equation x^2 - Dy^2 = N, John P. Robertson, July 31,
2004, Pages 4 - 8. http://www.jpr2718.org/pell.pdf
[R522] Solving the generalized Pell equation x**2 - D*y**2 = N, John P. Robertson, July
31, 2004, Page 12. http://www.jpr2718.org/pell.pdf
[R523] The algorithmic resolution of Diophantine equations, Nigel P. Smart, London
Mathematical Society Student Texts 41, Cambridge University Press, Cambridge,
1998.
[R524] The algorithmic resolution of Diophantine equations, Nigel P. Smart, London
Mathematical Society Student Texts 41, Cambridge University Press, Cambridge,
1998.
[R525] Efficient Solution of Rational Conices, J. E. Cremona and D. Rusin, [online], Avail-
able: http://eprints.nottingham.ac.uk/60/1/kvxefz87.pdf
[R526] Gaussian lattice Reduction [online]. Available: http://home.ie.cuhk.edu.hk/
~wkshum/wordpress/?p=404
[R527] Efficient Solution of Rational Conices, J. E. Cremona and D. Rusin, Mathematics
of Computation, Volume 00, Number 0.
[R528] Efficient Solution of Rational Conices, J. E. Cremona and D. Rusin, Mathematics
of Computation, Volume 00, Number 0.
[R529] Diophantine Equations, L. J. Mordell, page 48.
[R530] Representing a number as a sum of four squares, [online], Available: http:
//schorn.ch/lagrange.html
[R531] Legendre’s Theorem, Legrange’s Descent, http://public.csusm.edu/aitken_html/
notes/legendre.pdf
[AOCP] Algorithm 7.1.2.5M in Volume 4A, Combinatoral Algorithms, Part 1, of The Art of
Computer Programming, by Donald Knuth.
[Factorisatio] On a Problem of Oppenheim concerning “Factorisatio Numerorum” E. R. Can-
field, Paul Erdos, Carl Pomerance, JOURNAL OF NUMBER THEORY, Vol. 17, No.
1. August 1983. See section 7 for a description of an algorithm similar to Knuth’s.
[Yorgey] Generating Multiset Partitions, Brent Yorgey, The Monad.Reader, Issue 8,
September 2007.
[R597] Generating Integer Partitions, [online], Available: http://jeromekelleher.net/
generating-integer-partitions.html
[R598] Jerome Kelleher and Barry O’Sullivan, “Generating All Partitions: A Comparison
Of Two Encodings”, [online], Available: http://arxiv.org/pdf/0909.2331v2.pdf
[R599] http://stackoverflow.com/questions/6116978/python-replace-multiple-strings
[R22] http://en.wikipedia.org/wiki/Euler%E2%80%93Lagrange_equation
[R23] http://en.wikipedia.org/wiki/Mathematical_singularity

1954 Bibliography
 SymPy Documentation, Release 1.3

[R24] Generation of Finite Difference Formulas on Arbitrarily Spaced Grids,

Bengt Fornberg; Mathematics of computation; 51; 184; (1988); 699-706;
doi:10.1090/S0025-5718-1988-0935077-0
[R462] https://en.wikipedia.org/wiki/DFT_matrix
[R463] http://en.wikipedia.org/wiki/Gamma_matrices
[R464] http://en.wikipedia.org/wiki/Pauli_matrices
[R469] http://en.wikipedia.org/wiki/Pauli_matrices
[R487] http://en.wikipedia.org/wiki/Kronecker_delta
[Rasch03] J. Rasch and A. C. H. Yu, ‘Efficient Storage Scheme for Pre-calculated Wigner 3j, 6j
and Gaunt Coefficients’, SIAM J. Sci. Comput. Volume 25, Issue 4, pp. 1416-1428
(2003)
[Liberatodebrito82] ‘FORTRAN program for the integral of three spherical harmonics’, A.
Liberato de Brito, Comput. Phys. Commun., Volume 25, pp. 81-85 (1982)
[Regge58] ‘Symmetry Properties of Clebsch-Gordan Coefficients’, T. Regge, Nuovo Cimento,
Volume 10, pp. 544 (1958)
[Edmonds74] ‘Angular Momentum in Quantum Mechanics’, A. R. Edmonds, Princeton Uni-
versity Press (1974)
[Regge59] ‘Symmetry Properties of Racah Coefficients’, T. Regge, Nuovo Cimento, Volume
11, pp. 116 (1959)
[Page52] C. H. Page, Classes of units in the SI, Am. J. of Phys. 20, 1 (1952): 1.
[Page78] C. H. Page, Units and Dimensions in Physics, Am. J. of Phys. 46, 1 (1978): 78.
[deBoer79] J. de Boer, Group properties of quantities and units, Am. J. of Phys. 47, 9 (1979):
818.
[LevyLeblond77] J.-M. Lévy-Leblond, On the Conceptual Nature of the Physical Constants, La
Rivista Del Nuovo Cimento 7, no. 2 (1977): 187-214.
[NIST] NIST reference on constants, units and uncertainties.
[WikiDyadics] “Dyadics.” Wikipedia, the Free Encyclopedia. Web. 05 Aug. 2011. <http://en.
wikipedia.org/wiki/Dyadics>.
[WikiDyadicProducts] “Dyadic Product.” Wikipedia, the Free Encyclopedia. Web. 05 Aug.
2011. <http://en.wikipedia.org/wiki/Dyadic_product>.
[Likins1973] Likins, Peter W. Elements of Engineering Mechanics. McGraw-Hill, Inc. 1973.
Print.
[Blajer1994] Blajer, Wojciech, Werner Schiehlen, and Walter Schirm. “A projective criterion to
the coordinate partitioning method for multibody dynamics.” Archive of Applied
Mechanics 64: 86-98. Print.
[Kane1983] Kane, Thomas R., Peter W. Likins, and David A. Levinson. Spacecraft Dynamics.
New York: McGraw-Hill Book, 1983. Print.
[Kane1985] Kane, Thomas R., and David A. Levinson. Dynamics, Theory and Applications.
New York: McGraw-Hill, 1985. Print.
[Meijaard2007] Meijaard, J.P., Jim M. Papadopoulos, Andy Ruina, and A.L. Schwab. “Lin-
earized Dynamics Equations for the Balance and Steer of a Bicycle: a Benchmark
and Review.” Proceedings of the Royal Society A: Mathematical, Physical and
Engineering Sciences 463.2084 (2007): 1955-982. Print.

Bibliography 1955
SymPy Documentation, Release 1.3

[R470] http://en.wikipedia.org/wiki/Commutator
[R471] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
[R472] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
[R473] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
[R474] http://en.wikipedia.org/wiki/Commutator
[R475] http://en.wikipedia.org/wiki/Hermitian_adjoint
[R476] http://en.wikipedia.org/wiki/Hermitian_transpose
[R479] http://en.wikipedia.org/wiki/Inner_product
[R477] http://en.wikipedia.org/wiki/Hilbert_space
[R478] http://en.wikipedia.org/wiki/Fock_space
[R480] http://en.wikipedia.org/wiki/Operator_%28physics%29
[R481] http://en.wikipedia.org/wiki/Observable
[R482] http://en.wikipedia.org/wiki/Outer_product
[R483] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
[R484] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
[R485] http://en.wikipedia.org/wiki/Bra-ket_notation
[R486] http://en.wikipedia.org/wiki/Bra-ket_notation
[R465] http://en.wikipedia.org/wiki/Ray_transfer_matrix_analysis
[R466] http://en.wikipedia.org/wiki/Complex_beam_parameter
[R467] http://en.wikipedia.org/wiki/Gaussian_beam
[R468] http://en.wikipedia.org/wiki/Optical_medium
[R461] http://homes.civil.aau.dk/jc/FemteSemester/Beams3D.pdf
[WikiDel] http://en.wikipedia.org/wiki/Del
[R600] http://en.wikipedia.org/wiki/Dyadic_tensor
[R601] Kane, T., Levinson, D. Dynamics Theory and Applications. 1985 McGraw-Hill
[Dyadics] http://en.wikipedia.org/wiki/Dyadics
[DyadicProducts] http://en.wikipedia.org/wiki/Dyadic_product
[DelOperator] http://en.wikipedia.org/wiki/Del

1956 Bibliography
 PYTHON MODULE INDEX

s sympy.combinatorics.testutil, 294
sympy, 801 sympy.combinatorics.util, 288
sympy.assumptions, 1105 sympy.core.add, 163
sympy.assumptions.ask, 1105 sympy.core.assumptions, 98
sympy.assumptions.assume, 1121 sympy.core.basic, 100
sympy.assumptions.handlers, 1125 sympy.core.cache, 100
sympy.assumptions.handlers.calculus, sympy.core.compatibility, 204
1125 sympy.core.containers, 203
sympy.assumptions.handlers.ntheory, sympy.core.core, 114
1127 sympy.core.evalf, 202
sympy.assumptions.handlers.order, 1127 sympy.core.expr, 115
sympy.assumptions.handlers.sets, 1128 sympy.core.exprtools, 206
sympy.assumptions.refine, 1123 sympy.core.function, 181
sympy.calculus, 1501 sympy.core.mod, 166
sympy.calculus.euler, 1501 sympy.core.mul, 160
sympy.calculus.finite_diff, 1505 sympy.core.multidimensional, 181
sympy.calculus.singularities, 1502 sympy.core.numbers, 142
sympy.categories, 1815 sympy.core.power, 157
sympy.categories.diagram_drawing, 1823 sympy.core.relational, 166
sympy.codegen.algorithms, 441 sympy.core.singleton, 114
sympy.codegen.approximations, 411 sympy.core.symbol, 137
sympy.codegen.ast, 412 sympy.core.sympify, 95
sympy.codegen.cfunctions, 429 sympy.crypto.crypto, 343
sympy.codegen.cnodes, 433 sympy.diffgeom, 1832
sympy.codegen.cutils, 443 sympy.discrete, 382
sympy.codegen.cxxnodes, 434 sympy.discrete.convolutions, 388
sympy.codegen.fnodes, 434 sympy.discrete.transforms, 382
sympy.codegen.futils, 443 sympy.functions, 446
sympy.codegen.pyutils, 443 sympy.functions.special.bessel, 534
sympy.codegen.rewriting, 409 sympy.functions.special.beta_functions,
sympy.combinatorics.generators, 237 512
sympy.combinatorics.graycode, 281 sympy.functions.special.elliptic_integrals,
sympy.combinatorics.group_constructs, 557
294 sympy.functions.special.error_functions,
sympy.combinatorics.named_groups, 285 514
sympy.combinatorics.partitions, 208 sympy.functions.special.gamma_functions,
sympy.combinatorics.perm_groups, 238 505
sympy.combinatorics.permutations, 213 sympy.functions.special.mathieu_functions,
sympy.combinatorics.polyhedron, 267 560
sympy.combinatorics.prufer, 270 sympy.functions.special.polynomials,
sympy.combinatorics.subsets, 274 563
sympy.combinatorics.tensor_can, 295 sympy.functions.special.singularity_functions,

1957
SymPy Documentation, Release 1.3

503 sympy.physics.qho_1d, 1516

sympy.functions.special.zeta_functions, sympy.physics.quantum.anticommutator,
547 1708
sympy.geometry.curve, 631 sympy.physics.quantum.cartesian, 1717
sympy.geometry.ellipse, 635 sympy.physics.quantum.cg, 1709
sympy.geometry.entity, 584 sympy.physics.quantum.circuitplot, 1750
sympy.geometry.line, 602 sympy.physics.quantum.commutator, 1711
sympy.geometry.plane, 673 sympy.physics.quantum.constants, 1712
sympy.geometry.point, 590 sympy.physics.quantum.dagger, 1713
sympy.geometry.polygon, 650 sympy.physics.quantum.gate, 1751
sympy.geometry.util, 587 sympy.physics.quantum.grover, 1755
sympy.holonomic, 680 sympy.physics.quantum.hilbert, 1718
sympy.holonomic.holonomic, 688 sympy.physics.quantum.innerproduct,
sympy.integrals, 689 1714
sympy.integrals.intpoly, 725 sympy.physics.quantum.operator, 1719
sympy.integrals.meijerint_doc, 708 sympy.physics.quantum.operatorset, 1724
sympy.integrals.transforms, 690 sympy.physics.quantum.piab, 1764
sympy.liealgebras, 727 sympy.physics.quantum.qapply, 1726
sympy.logic, 742 sympy.physics.quantum.qft, 1758
sympy.logic.inference, 752 sympy.physics.quantum.qubit, 1758
sympy.matrices, 754 sympy.physics.quantum.represent, 1727
sympy.matrices.expressions, 803 sympy.physics.quantum.shor, 1763
sympy.matrices.expressions.blockmatrix, sympy.physics.quantum.spin, 1731
809 sympy.physics.quantum.state, 1742
sympy.matrices.immutable, 802 sympy.physics.quantum.tensorproduct,
sympy.matrices.matrices, 754 1715
sympy.matrices.sparse, 792 sympy.physics.secondquant, 1518
sympy.ntheory.continued_fraction, 338 sympy.physics.sho, 1516
sympy.ntheory.egyptian_fraction, 341 sympy.physics.units.dimensions, 1550
sympy.ntheory.factor_, 313 sympy.physics.units.prefixes, 1553
sympy.ntheory.generate, 305 sympy.physics.units.quantities, 1554
sympy.ntheory.modular, 329 sympy.physics.units.unitsystem, 1553
sympy.ntheory.multinomial, 331 sympy.physics.units.util, 1555
sympy.ntheory.partitions_, 332 sympy.physics.vector.functions, 1612
sympy.ntheory.primetest, 333 sympy.physics.vector.point, 1606
sympy.ntheory.residue_ntheory, 334 sympy.physics.wigner, 1538
sympy.physics, 1510 sympy.plotting.plot, 1087
sympy.physics.continuum_mechanics.beam, sympy.plotting.pygletplot, 1101
1785 sympy.printing.ccode, 1051
sympy.physics.hep.gamma_matrices, 1556 sympy.printing.codeprinter, 1082
sympy.physics.hydrogen, 1511 sympy.printing.conventions, 1082
sympy.physics.matrices, 1513 sympy.printing.cxxcode, 1054
sympy.physics.mechanics.body, 1705 sympy.printing.fcode, 1057
sympy.physics.mechanics.kane, 1692 sympy.printing.gtk, 1072
sympy.physics.mechanics.lagrange, 1695 sympy.printing.jscode, 1062
sympy.physics.mechanics.linearize, 1702 sympy.printing.julia, 1064
sympy.physics.mechanics.particle, 1681 sympy.printing.lambdarepr, 1072
sympy.physics.mechanics.rigidbody, 1684 sympy.printing.latex, 1072
sympy.physics.mechanics.system, 1698 sympy.printing.mathematica, 1061
sympy.physics.optics.gaussopt, 1764 sympy.printing.mathml, 1076
sympy.physics.optics.medium, 1775 sympy.printing.octave, 1067
sympy.physics.optics.utils, 1777 sympy.printing.precedence, 1083
sympy.physics.optics.waves, 1781 sympy.printing.pretty.pretty, 1050
sympy.physics.paulialgebra, 1515

1958 Python Module Index

 SymPy Documentation, Release 1.3

sympy.printing.pretty.pretty_symbology, sympy.utilities.pytest, 1486

1083 sympy.utilities.randtest, 1487
sympy.printing.pretty.stringpict, 1084 sympy.utilities.runtests, 1488
sympy.printing.preview, 1080 sympy.utilities.source, 1495
sympy.printing.printer, 1046 sympy.utilities.timeutils, 1495
sympy.printing.pycode, 1077
sympy.printing.python, 1078
sympy.printing.rcode, 1055
sympy.printing.repr, 1078
sympy.printing.rust, 1069
sympy.printing.str, 1079
sympy.printing.theanocode, 1071
sympy.printing.tree, 1079
sympy.sets.fancysets, 1177
sympy.sets.sets, 1162
sympy.simplify.combsimp, 1204
sympy.simplify.cse_main, 1205
sympy.simplify.epathtools, 1208
sympy.simplify.hyperexpand, 1207
sympy.simplify.hyperexpand_doc, 1219
sympy.simplify.powsimp, 1201
sympy.simplify.radsimp, 1192
sympy.simplify.ratsimp, 1199
sympy.simplify.simplify, 81
sympy.simplify.sqrtdenest, 1204
sympy.simplify.traversaltools, 1208
sympy.simplify.trigsimp, 1200
sympy.solvers, 1328
sympy.solvers.inequalities, 1372
sympy.solvers.ode, 1316
sympy.solvers.pde, 1327
sympy.solvers.recurr, 1343
sympy.solvers.solveset, 1375
sympy.stats, 1220
sympy.stats.crv, 1261
sympy.stats.crv_types, 1261
sympy.stats.frv, 1260
sympy.stats.frv_types, 1261
sympy.stats.rv, 1260
sympy.tensor, 1399
sympy.tensor.array, 1399
sympy.tensor.index_methods, 1412
sympy.tensor.indexed, 1405
sympy.tensor.tensor, 1415
sympy.utilities, 1430
sympy.utilities.autowrap, 1431
sympy.utilities.codegen, 1438
sympy.utilities.decorator, 1449
sympy.utilities.enumerative, 1451
sympy.utilities.iterables, 1458
sympy.utilities.lambdify, 1478
sympy.utilities.memoization, 1482
sympy.utilities.misc, 1482
sympy.utilities.pkgdata, 1485

Python Module Index 1959

SymPy Documentation, Release 1.3

1960 Python Module Index

 INDEX

Symbols sympy.solvers.ode), 1301

_TensorManager (class in _linear_2eq_order2_type10() (in module
sympy.tensor.tensor), 1415 sympy.solvers.ode), 1307
__init__() (sympy.vector.coordsysrect.CoordSys3D_linear_2eq_order2_type11() (in module
method), 1865 sympy.solvers.ode), 1308
__init__() (sympy.vector.orienters.AxisOrienter _linear_2eq_order2_type2() (in module
method), 1878 sympy.solvers.ode), 1302
__init__() (sympy.vector.orienters.BodyOrienter _linear_2eq_order2_type3() (in module
method), 1879 sympy.solvers.ode), 1303
_linear_2eq_order2_type4()
__init__() (sympy.vector.orienters.QuaternionOrienter (in module
method), 1881 sympy.solvers.ode), 1303
__init__() (sympy.vector.orienters.SpaceOrienter_linear_2eq_order2_type5() (in module
method), 1880 sympy.solvers.ode), 1304
_base_ordering() (in module _linear_2eq_order2_type6() (in module
sympy.combinatorics.util), 288 sympy.solvers.ode), 1305
_check_cycles_alt_sym() (in module _linear_2eq_order2_type7() (in module
sympy.combinatorics.util), 288 sympy.solvers.ode), 1305
_cmp_perm_lists() (in module _linear_2eq_order2_type8() (in module
sympy.combinatorics.testutil), 294 sympy.solvers.ode), 1306
_distribute_gens_by_base() (in module _linear_2eq_order2_type9() (in module
sympy.combinatorics.util), 289 sympy.solvers.ode), 1307
_handle_precomputed_bsgs() (in module _linear_3eq_order1_type1() (in module
sympy.combinatorics.util), 290 sympy.solvers.ode), 1308
_is_exponential() (in module _linear_3eq_order1_type2() (in module
sympy.solvers.solveset), 1395 sympy.solvers.ode), 1309
_is_logarithmic() (in module _linear_3eq_order1_type3() (in module
sympy.solvers.solveset), 1398 sympy.solvers.ode), 1309
_linear_2eq_order1_type1() (in module _linear_3eq_order1_type4() (in module
sympy.solvers.ode), 1298 sympy.solvers.ode), 1310
_linear_2eq_order1_type2() (in module _linear_neq_order1_type1() (in module
sympy.solvers.ode), 1299 sympy.solvers.ode), 1310
_linear_2eq_order1_type3() (in module _naive_list_centralizer() (in module
sympy.solvers.ode), 1299 sympy.combinatorics.testutil), 294
_linear_2eq_order1_type4() (in module _nonlinear_2eq_order1_type1() (in module
sympy.solvers.ode), 1300 sympy.solvers.ode), 1311
_linear_2eq_order1_type5() (in module _nonlinear_2eq_order1_type2() (in module
sympy.solvers.ode), 1300 sympy.solvers.ode), 1312
_linear_2eq_order1_type6() (in module _nonlinear_2eq_order1_type3() (in module
sympy.solvers.ode), 1300 sympy.solvers.ode), 1312
_linear_2eq_order1_type7() (in module _nonlinear_2eq_order1_type4() (in module
sympy.solvers.ode), 1301 sympy.solvers.ode), 1312
_linear_2eq_order2_type1() (in module _nonlinear_2eq_order1_type5() (in module

1961
SymPy Documentation, Release 1.3

sympy.solvers.ode), 1313 Abs (class in sympy.functions.elementary.complexes),

_nonlinear_3eq_order1_type1() (in module 449
sympy.solvers.ode), 1313 abs() (sympy.polys.domains.domain.Domain
_nonlinear_3eq_order1_type2() (in module method), 931
sympy.solvers.ode), 1314 abs() (sympy.polys.polyclasses.DMP method),
_nonlinear_3eq_order1_type3() (in module 945
sympy.solvers.ode), 1314 abs() (sympy.polys.polytools.Poly method),
_nonlinear_3eq_order1_type4() (in module 849
sympy.solvers.ode), 1315 acc() (sympy.physics.vector.point.Point
_nonlinear_3eq_order1_type5() (in module method), 1608
sympy.solvers.ode), 1315 accepted_latex_functions (in module
_orbits_transversals_from_bsgs() (in module sympy.printing.latex), 1072
sympy.combinatorics.util), 290 acos (class in sympy.functions.elementary.trigonometric),
_print() (sympy.printing.printer.Printer 458
method), 1049 acosh (class in sympy.functions.elementary.hyperbolic),
_remove_gens() (in module 465
sympy.combinatorics.util), 291 acot (class in sympy.functions.elementary.trigonometric),
_solve_exponential() (in module 460
sympy.solvers.solveset), 1396 acoth (class in sympy.functions.elementary.hyperbolic),
_solve_logarithm() (in module 466
sympy.solvers.solveset), 1397 acsc (class in sympy.functions.elementary.trigonometric),
_strip() (in module sympy.combinatorics.util), 461
292 acsch (class in sympy.functions.elementary.hyperbolic),
_strong_gens_from_distr() (in module 467
sympy.combinatorics.util), 293 Add (class in sympy.core.add), 163
_transolve() (in module add() (sympy.assumptions.assume.AssumptionsContext
sympy.solvers.solveset), 1393 method), 1122
_verify_bsgs() (in module Add() (sympy.assumptions.handlers.calculus.AskFiniteHand
sympy.combinatorics.testutil), 294 static method), 1125
_verify_centralizer() (in module Add() (sympy.assumptions.handlers.order.AskNegativeHand
sympy.combinatorics.testutil), 295 static method), 1127
_verify_normal_closure() (in module Add() (sympy.assumptions.handlers.sets.AskAntiHermitianH
sympy.combinatorics.testutil), 295 static method), 1128
Add() (sympy.assumptions.handlers.sets.AskHermitianHand
A static method), 1128
Add() (sympy.assumptions.handlers.sets.AskImaginaryHand
A (sympy.physics.optics.gaussopt.RayTransferMatrix
attribute), 1765 static method), 1128
a (sympy.physics.quantum.shor.CMod at- Add() (sympy.assumptions.handlers.sets.AskIntegerHandler
tribute), 1763 static method), 1129
a1pt_theory() (sympy.physics.vector.point.Point Add() (sympy.assumptions.handlers.sets.AskRationalHandle
method), 1606 static method), 1129
a2idx() (in module sympy.matrices.matrices), Add() (sympy.assumptions.handlers.sets.AskRealHandler
787 static method), 1129
a2pt_theory() (sympy.physics.vector.point.Point add() (sympy.matrices.matrices.MatrixBase
method), 1607 method), 767
a_interval (sympy.sets.fancysets.ComplexRegion add() (sympy.polys.domains.domain.Domain
attribute), 1183 method), 931
abbrev (sympy.physics.units.quantities.Quantity add() (sympy.polys.polyclasses.DMF method),
attribute), 1554 950
AbelianGroup() (in module add() (sympy.polys.polyclasses.DMP method),
sympy.combinatorics.named_groups), 945
287 add() (sympy.polys.polytools.Poly method),
above() (sympy.printing.pretty.stringpict.stringPict 849
method), 1084 add() (sympy.polys.rings.PolyRing method),

1962 Index
 SymPy Documentation, Release 1.3

1000 method), 728

add_as_roots() (sympy.liealgebras.root_system.RootSystem
all_roots() (sympy.polys.polytools.Poly
method), 728 method), 850
add_gens() (sympy.polys.rings.PolyRing all_terms() (sympy.polys.polyclasses.DMP
method), 1000 method), 945
add_ground() (sympy.polys.polyclasses.DMP all_terms() (sympy.polys.polytools.Poly
method), 945 method), 851
add_ground() (sympy.polys.polytools.Poly allhints (in module sympy.solvers.ode), 1270
method), 849 allocated() (in module
add_simple_roots() (sympy.liealgebras.root_system.RootSystem
sympy.codegen.fnodes), 437
method), 728 almosteq() (sympy.polys.domains.domain.Domain
affine_rank() (sympy.geometry.point.Point method), 931
static method), 591 almosteq() (sympy.polys.domains.RealField
airyai (class in sympy.functions.special.bessel), method), 942
540 almosteq() (sympy.polys.rings.PolyElement
airyaiprime (class in method), 1001
sympy.functions.special.bessel), alternating() (sympy.combinatorics.generators
543 method), 238
AiryBase (class in AlternatingGroup() (in module
sympy.functions.special.bessel), sympy.combinatorics.named_groups),
540 287
airybi (class in sympy.functions.special.bessel), altitudes (sympy.geometry.polygon.Triangle
541 attribute), 665
airybiprime (class in ambient_dimension (sympy.geometry.entity.GeometryEntity
sympy.functions.special.bessel), attribute), 584
544 ambient_dimension (sympy.geometry.line.LinearEntity
alg_con (sympy.physics.mechanics.system.SymbolicSystem attribute), 603
attribute), 1701 ambient_dimension (sympy.geometry.point.Point
algebraic, 99 attribute), 591
algebraic (sympy.assumptions.ask.AssumptionKeys amplitude (sympy.physics.optics.waves.TWave
attribute), 1105 attribute), 1782
algebraic_field() (sympy.polys.domains.AlgebraicField
an (sympy.functions.special.hyper.meijerg at-
method), 940 tribute), 556
algebraic_field() (sympy.polys.domains.domain.Domain
And (class in sympy.logic.boolalg), 745
method), 931 ang_acc_in() (sympy.physics.vector.frame.ReferenceFrame
algebraic_field() (sympy.polys.domains.IntegerRing method), 1594
method), 938 ang_vel_in() (sympy.physics.vector.frame.ReferenceFrame
algebraic_field() (sympy.polys.domains.RationalField method), 1594
method), 940 angle (sympy.physics.optics.gaussopt.GeometricRay
AlgebraicField (class in attribute), 1770
sympy.polys.domains), 940 angle_between() (sympy.geometry.line.LinearEntity
AlgebraicNumber (class in method), 603
sympy.polys.numberfields), 893 angle_between() (sympy.geometry.plane.Plane
alignof() (in module sympy.codegen.cnodes), method), 673
433 angles (sympy.geometry.polygon.Polygon at-
all_coeffs() (sympy.polys.polyclasses.DMP tribute), 651
method), 945 angles (sympy.geometry.polygon.RegularPolygon
all_coeffs() (sympy.polys.polytools.Poly attribute), 658
method), 850 angular_momentum() (in module
all_monoms() (sympy.polys.polyclasses.DMP sympy.physics.mechanics.functions),
method), 945 1689
all_monoms() (sympy.polys.polytools.Poly angular_momentum()
method), 850 (sympy.physics.mechanics.particle.Particle
all_roots() (sympy.liealgebras.root_system.RootSystem method), 1682

Index 1963
SymPy Documentation, Release 1.3

angular_momentum() sympy.physics.quantum.grover),
(sympy.physics.mechanics.rigidbody.RigidBody 1757
method), 1684 apply_load() (sympy.physics.continuum_mechanics.beam.Be
angular_velocity (sympy.physics.optics.waves.TWave method), 1786
attribute), 1783 apply_load() (sympy.physics.continuum_mechanics.beam.Be
AnnihilateBoson (class in method), 1798
sympy.physics.secondquant), 1522 apply_moment_load()
AnnihilateFermion (class in (sympy.physics.continuum_mechanics.beam.Beam3D
sympy.physics.secondquant), 1523 method), 1799
annotated() (in module apply_operator() (sympy.physics.secondquant.AnnihilateBos
sympy.printing.pretty.pretty_symbology), method), 1522
1084 apply_operator() (sympy.physics.secondquant.AnnihilateFer
ANP (class in sympy.polys.polyclasses), 951 method), 1523
AntiCommutator (class in apply_operator() (sympy.physics.secondquant.CreateBoson
sympy.physics.quantum.anticommutator), method), 1523
1708 apply_operator() (sympy.physics.secondquant.CreateFermio
antidivisor_count() (in module method), 1525
sympy.ntheory.factor_), 324 apply_operators() (in module
antidivisors() (in module sympy.physics.secondquant), 1527
sympy.ntheory.factor_), 323 apply_support() (sympy.physics.continuum_mechanics.beam
antihermitian, 100 method), 1787
antihermitian (sympy.assumptions.ask.AssumptionKeys
apply_torque() (sympy.physics.mechanics.body.Body
attribute), 1105 method), 1707
AntiSymmetricTensor (class in applyfunc() (sympy.matrices.sparse.SparseMatrix
sympy.physics.secondquant), 1535 method), 793
aother (sympy.functions.special.hyper.meijerg applyfunc() (sympy.physics.vector.dyadic.Dyadic
attribute), 557 method), 1604
ap (sympy.functions.special.hyper.hyper at- applyfunc() (sympy.physics.vector.vector.Vector
tribute), 554 method), 1599
ap (sympy.functions.special.hyper.meijerg at- approximation() (sympy.core.numbers.NumberSymbol
tribute), 557 method), 148
apart() (in module sympy.polys.partfrac), 902 arbitrary_point() (sympy.geometry.curve.Curve
apart() (sympy.core.expr.Expr method), 115 method), 632
apart_list() (in module sympy.polys.partfrac), arbitrary_point() (sympy.geometry.ellipse.Ellipse
902 method), 636
apoapsis (sympy.geometry.ellipse.Ellipse at- arbitrary_point() (sympy.geometry.line.LinearEntity
tribute), 636 method), 604
apothem (sympy.geometry.polygon.RegularPolygon arbitrary_point() (sympy.geometry.plane.Plane
attribute), 658 method), 674
append() (sympy.plotting.plot.Plot method), arbitrary_point() (sympy.geometry.polygon.Polygon
1089 method), 651
applied_loads (sympy.physics.continuum_mechanics.beam.Beam
Arcsin() (in module sympy.stats), 1225
attribute), 1786 are_collinear() (sympy.geometry.point.Point3D
AppliedPredicate (class in static method), 599
sympy.assumptions.assume), 1121 are_concurrent() (sympy.geometry.line.LinearEntity
apply() (sympy.printing.pretty.stringpict.prettyForm static method), 604
static method), 1086 are_concurrent() (sympy.geometry.plane.Plane
apply() (sympy.simplify.epathtools.EPath static method), 674
method), 1209 are_coplanar() (sympy.geometry.point.Point
apply_finite_diff() (in module class method), 591
sympy.calculus.finite_diff), 1505 are_similar() (in module
apply_force() (sympy.physics.mechanics.body.Body sympy.geometry.util), 588
method), 1707 area (sympy.geometry.ellipse.Ellipse at-
apply_grover() (in module tribute), 637

1964 Index
 SymPy Documentation, Release 1.3

area (sympy.geometry.polygon.Polygon at- as_coeff_Mul() (sympy.core.expr.Expr

tribute), 652 method), 116
area (sympy.geometry.polygon.RegularPolygon as_coeff_mul() (sympy.core.expr.Expr
attribute), 659 method), 116
area (sympy.physics.continuum_mechanics.beam.Beam3D
as_coeff_Mul() (sympy.core.mul.Mul method),
attribute), 1799 160
arg (class in sympy.functions.elementary.complexes),
as_coeff_Mul() (sympy.core.numbers.Number
450 method), 142
arg (sympy.assumptions.assume.AppliedPredicate as_coeff_Mul() (sympy.core.numbers.Rational
attribute), 1122 method), 147
args (sympy.core.basic.Basic attribute), 101 as_coeff_Mul() (sympy.core.numbers.Zero
args (sympy.geometry.polygon.RegularPolygon method), 149
attribute), 659 as_coeff_Mul() (sympy.matrices.expressions.MatrixExpr
args (sympy.polys.polytools.Poly attribute), method), 804
851 as_coefficient() (sympy.core.expr.Expr
args_cnc() (sympy.core.expr.Expr method), method), 117
115 as_coefficients_dict() (sympy.core.add.Add
Argument (class in sympy.utilities.codegen), method), 163
1439 as_coefficients_dict() (sympy.core.expr.Expr
argument (sympy.functions.special.bessel.BesselBase method), 118
attribute), 534 as_coefficients_dict() (sympy.core.mul.Mul
argument (sympy.functions.special.hyper.hyper method), 160
attribute), 554 as_content_primitive() (sympy.core.add.Add
argument (sympy.functions.special.hyper.meijerg method), 164
attribute), 557 as_content_primitive()
array() (in module sympy.codegen.fnodes), (sympy.core.basic.Basic method),
437 101
array_form (sympy.combinatorics.permutations.Permutation
as_content_primitive() (sympy.core.expr.Expr
attribute), 218 method), 118
array_form (sympy.combinatorics.polyhedron.Polyhedron
as_content_primitive() (sympy.core.mul.Mul
attribute), 267 method), 160
ArrayConstructor (class in as_content_primitive()
sympy.codegen.fnodes), 434 (sympy.core.numbers.Rational
ArrowStringDescription (class in method), 147
sympy.categories.diagram_drawing), as_content_primitive()
1826 (sympy.core.power.Pow method),
as_base_exp() (sympy.core.function.Function 159
method), 190 as_Declaration() (sympy.codegen.ast.Variable
as_base_exp() (sympy.core.power.Pow method), 427
method), 158 as_dict() (sympy.combinatorics.partitions.IntegerPartition
as_coeff_Add() (sympy.core.add.Add method), method), 210
163 as_dict() (sympy.polys.polytools.Poly
as_coeff_add() (sympy.core.add.Add method), method), 851
163 as_dummy() (sympy.core.symbol.Symbol
as_coeff_Add() (sympy.core.expr.Expr method), 138
method), 116 as_explicit() (sympy.matrices.expressions.MatrixExpr
as_coeff_add() (sympy.core.expr.Expr method), 804
method), 116 as_expr() (sympy.core.expr.Expr method),
as_coeff_Add() (sympy.core.numbers.Number 119
method), 142 as_expr() (sympy.polys.numberfields.AlgebraicNumber
as_coeff_Add() (sympy.core.numbers.Rational method), 893
method), 147 as_expr() (sympy.polys.polytools.Poly
as_coeff_exponent() (sympy.core.expr.Expr method), 851
method), 116 as_ferrers() (sympy.combinatorics.partitions.IntegerPartition

Index 1965
SymPy Documentation, Release 1.3

method), 210 as_two_terms() (sympy.core.add.Add

as_finite_diff() (in module method), 164
sympy.calculus.finite_diff), 1506 as_two_terms() (sympy.core.mul.Mul
as_finite_difference() method), 161
(sympy.core.function.Derivative ascents() (sympy.combinatorics.permutations.Permutation
method), 185 method), 219
as_immutable() (sympy.matrices.sparse.SparseMatrix
asec (class in sympy.functions.elementary.trigonometric),
method), 793 460
as_independent() (sympy.core.expr.Expr asech (class in sympy.functions.elementary.hyperbolic),
method), 120 466
as_int() (in module sympy.core.compatibility), asin (class in sympy.functions.elementary.trigonometric),
205 458
as_leading_term() (sympy.core.expr.Expr asinh (class in sympy.functions.elementary.hyperbolic),
method), 122 465
as_list() (sympy.polys.polytools.Poly method), ask() (in module sympy.assumptions.ask),
852 1120
as_mutable() (sympy.matrices.expressions.MatrixExpr
ask_full_inference() (in module
method), 804 sympy.assumptions.ask), 1121
as_mutable() (sympy.matrices.sparse.SparseMatrixAskAlgebraicHandler (class in
method), 793 sympy.assumptions.handlers.sets),
as_numer_denom() (sympy.core.expr.Expr 1128
method), 122 AskAntiHermitianHandler (class in
as_ordered_factors() (sympy.core.expr.Expr sympy.assumptions.handlers.sets),
method), 122 1128
as_ordered_factors() (sympy.core.mul.Mul AskComplexHandler (class in
method), 161 sympy.assumptions.handlers.sets),
as_ordered_terms() (sympy.core.expr.Expr 1128
method), 122 AskExtendedRealHandler (class in
as_poly() (sympy.core.basic.Basic method), sympy.assumptions.handlers.sets),
101 1128
as_poly() (sympy.polys.numberfields.AlgebraicNumber
AskFiniteHandler (class in
method), 893 sympy.assumptions.handlers.calculus),
as_powers_dict() (sympy.core.expr.Expr 1125
method), 123 AskHermitianHandler (class in
as_real_imag() (sympy.core.add.Add method), sympy.assumptions.handlers.sets),
164 1128
as_real_imag() (sympy.core.expr.Expr AskImaginaryHandler (class in
method), 123 sympy.assumptions.handlers.sets),
as_real_imag() (sympy.functions.elementary.complexes.im 1128
method), 448 AskIntegerHandler (class in
as_real_imag() (sympy.functions.elementary.complexes.re sympy.assumptions.handlers.sets),
method), 448 1129
as_relational() (sympy.sets.sets.FiniteSet AskNegativeHandler (class in
method), 1172 sympy.assumptions.handlers.order),
as_relational() (sympy.sets.sets.Intersection 1127
method), 1173 AskNonZeroHandler (class in
as_relational() (sympy.sets.sets.Interval sympy.assumptions.handlers.order),
method), 1170 1128
as_relational() (sympy.sets.sets.Union AskOddHandler (class in
method), 1173 sympy.assumptions.handlers.ntheory),
as_sum() (sympy.integrals.Integral method), 1127
714 AskPositiveHandler (class in
as_terms() (sympy.core.expr.Expr method), sympy.assumptions.handlers.order),
123 1128

1966 Index
 SymPy Documentation, Release 1.3

AskPrimeHandler (class in auto_number() (in module

sympy.assumptions.handlers.ntheory), sympy.parsing.sympy_parser), 1499
1127 auto_symbol() (in module
AskRationalHandler (class in sympy.parsing.sympy_parser), 1499
sympy.assumptions.handlers.sets), autowrap() (in module
1129 sympy.utilities.autowrap), 1433
AskRealHandler (class in auxiliary_eqs (sympy.physics.mechanics.kane.KanesMethod
sympy.assumptions.handlers.sets), attribute), 1693
1129 axial_force() (sympy.physics.continuum_mechanics.beam.Be
assemble_partfrac_list() (in module method), 1799
sympy.polys.partfrac), 904 AxisOrienter (class in
Assignment (class in sympy.codegen.ast), 414 sympy.vector.orienters), 1878
Assignment (class in AZ() (in module sympy.crypto.crypto), 343
sympy.printing.codeprinter), 1082
AssignmentBase (class in B
sympy.codegen.ast), 415 B (in module sympy.physics.secondquant),
AssignmentError, 1083 1527
assoc_laguerre (class in B (sympy.physics.optics.gaussopt.RayTransferMatrix
sympy.functions.special.polynomials), attribute), 1765
572 b_interval (sympy.sets.fancysets.ComplexRegion
assoc_legendre (class in attribute), 1183
sympy.functions.special.polynomials), base (sympy.combinatorics.perm_groups.PermutationGroup
569 attribute), 240
assoc_recurrence_memo() (in module base (sympy.tensor.indexed.Indexed at-
sympy.utilities.memoization), 1482 tribute), 1409
assuming() (in module base_oneform() (sympy.diffgeom.CoordSystem
sympy.assumptions.assume), 1123 method), 1834
AssumptionKeys (class in base_oneforms() (sympy.diffgeom.CoordSystem
sympy.assumptions.ask), 1105 method), 1834
assumptions0 (sympy.core.basic.Basic at- base_solution_linear() (in module
tribute), 102 sympy.solvers.diophantine), 1355
AssumptionsContext (class in base_vector() (sympy.diffgeom.CoordSystem
sympy.assumptions.assume), 1122 method), 1834
atan (class in sympy.functions.elementary.trigonometric),
base_vectors() (sympy.diffgeom.CoordSystem
459 method), 1834
atan2 (class in sympy.functions.elementary.trigonometric),
BaseCovarDerivativeOp (class in
462 sympy.diffgeom), 1841
atanh (class in sympy.functions.elementary.hyperbolic),
BasePolynomialError (class in
466 sympy.polys.polyerrors), 1026
Atom (class in sympy.core.basic), 114 BaseScalarField (class in sympy.diffgeom),
AtomicExpr (class in sympy.core.expr), 137 1836
atoms() (sympy.combinatorics.permutations.Permutation
BaseSeries (class in sympy.plotting.plot),
method), 219 1099
atoms() (sympy.core.basic.Basic method), 102 baseswap() (sympy.combinatorics.perm_groups.Permutation
atoms_table (in module method), 240
sympy.printing.pretty.pretty_symbology), BaseVectorField (class in sympy.diffgeom),
1084 1837
attr_params() (sympy.codegen.ast.Node Basic (class in sympy.core.basic), 100
method), 422 basic_orbits (sympy.combinatorics.perm_groups.Permutation
Attribute (class in sympy.codegen.ast), 415 attribute), 241
aug_assign() (in module sympy.codegen.ast), basic_root() (sympy.liealgebras.type_a.TypeA
428 method), 729
AugmentedAssignment (class in basic_root() (sympy.liealgebras.type_b.TypeB
sympy.codegen.ast), 415 method), 731

Index 1967
SymPy Documentation, Release 1.3

basic_root() (sympy.liealgebras.type_c.TypeC sympy.functions.special.bessel),

method), 732 534
basic_root() (sympy.liealgebras.type_d.TypeD besseli (class in sympy.functions.special.bessel),
method), 734 536
basic_root() (sympy.liealgebras.type_e.TypeE besselj (class in sympy.functions.special.bessel),
method), 735 534
basic_root() (sympy.liealgebras.type_f.TypeF besselk (class in sympy.functions.special.bessel),
method), 736 536
basic_stabilizers (sympy.combinatorics.perm_groups.PermutationGroup
besselsimp() (in module
attribute), 242 sympy.simplify.simplify), 1189
basic_transversals (sympy.combinatorics.perm_groups.PermutationGroup
bessely (class in sympy.functions.special.bessel),
attribute), 242 535
basis() (sympy.liealgebras.type_a.TypeA beta (class in sympy.functions.special.beta_functions),
method), 730 512
basis() (sympy.liealgebras.type_b.TypeB Beta() (in module sympy.stats), 1226
method), 731 BetaPrime() (in module sympy.stats), 1227
basis() (sympy.liealgebras.type_c.TypeC bifid5_square() (in module
method), 732 sympy.crypto.crypto), 353, 355
basis() (sympy.liealgebras.type_d.TypeD bifid6_square() (in module
method), 734 sympy.crypto.crypto), 356
basis() (sympy.liealgebras.type_e.TypeE bin_to_gray() (sympy.combinatorics.graycode
method), 735 method), 284
basis() (sympy.liealgebras.type_f.TypeF binary_function() (in module
method), 736 sympy.utilities.autowrap), 1434
basis() (sympy.liealgebras.type_g.TypeG binary_partitions() (in module
method), 738 sympy.utilities.iterables), 1458
basis() (sympy.polys.agca.modules.FreeModule bind_C() (in module sympy.codegen.fnodes),
method), 913 438
BBra (in module sympy.physics.secondquant), binomial (class in
1527 sympy.functions.combinatorial.factorials),
Bd (in module sympy.physics.secondquant), 481
1527 Binomial() (in module sympy.stats), 1222
Beam (class in sympy.physics.continuum_mechanics.beam),
binomial_coefficients() (in module
1785 sympy.ntheory.multinomial), 331
Beam3D (class in binomial_coefficients_list() (in module
sympy.physics.continuum_mechanics.beam), sympy.ntheory.multinomial), 331
1797 bisectors() (sympy.geometry.polygon.Triangle
BeamParameter (class in method), 666
sympy.physics.optics.gaussopt), bitlist_from_subset()
1770 (sympy.combinatorics.subsets.Subset
bell (class in sympy.functions.combinatorial.numbers), class method), 274
479 BKet (in module sympy.physics.secondquant),
below() (sympy.printing.pretty.stringpict.stringPict 1527
method), 1085 block_collapse() (in module
bending_moment() (sympy.physics.continuum_mechanics.beam.Beam
sympy.matrices.expressions.blockmatrix),
method), 1788 810
bending_moment() (sympy.physics.continuum_mechanics.beam.Beam3D
BlockDiagMatrix (class in
method), 1799 sympy.matrices.expressions.blockmatrix),
Benini() (in module sympy.stats), 1225 809
bernoulli (class in BlockMatrix (class in
sympy.functions.combinatorial.numbers), sympy.matrices.expressions.blockmatrix),
480 809
Bernoulli() (in module sympy.stats), 1222 bm (sympy.functions.special.hyper.meijerg
BesselBase (class in attribute), 557

1968 Index
 SymPy Documentation, Release 1.3

bodies (sympy.physics.mechanics.system.SymbolicSystem sympy.combinatorics.tensor_can),

attribute), 1701 300
Body (class in sympy.physics.mechanics.body), bspline_basis() (in module
1705 sympy.functions.special.bsplines),
BodyOrienter (class in 545
sympy.vector.orienters), 1879 bspline_basis_set() (in module
bool_map() (in module sympy.logic.boolalg), sympy.functions.special.bsplines),
752 546
BooleanFalse (class in sympy.logic.boolalg), build_expression_tree() (in module
745 sympy.series.gruntz), 1138
BooleanTrue (class in sympy.logic.boolalg),
743 C
BosonicBasis (class in C (sympy.physics.optics.gaussopt.RayTransferMatrix
sympy.physics.secondquant), 1527 attribute), 1766
bother (sympy.functions.special.hyper.meijerg C89CodePrinter (class in
attribute), 557 sympy.printing.ccode), 1051
boundary (sympy.sets.sets.Set attribute), C99CodePrinter (class in
1162 sympy.printing.ccode), 1051
boundary_conditions cacheit() (in module sympy.core.cache), 100
(sympy.physics.continuum_mechanics.beam.Beam
calculate_series() (in module
attribute), 1788 sympy.series.gruntz), 1138
boundary_conditions can_transf_matrix (sympy.physics.units.dimensions.Dimensi
(sympy.physics.continuum_mechanics.beam.Beam3Dattribute), 1552
attribute), 1799 canberra_distance()
bounded (sympy.assumptions.ask.AssumptionKeys (sympy.geometry.point.Point
attribute), 1105 method), 591
bounds (sympy.geometry.ellipse.Ellipse at- cancel() (in module sympy.polys.polytools),
tribute), 637 845
bounds (sympy.geometry.entity.GeometryEntity cancel() (sympy.core.expr.Expr method), 123
attribute), 584 cancel() (sympy.polys.polyclasses.DMF
bounds (sympy.geometry.line.LinearEntity2D method), 950
attribute), 621 cancel() (sympy.polys.polyclasses.DMP
bounds (sympy.geometry.point.Point2D at- method), 945
tribute), 597 cancel() (sympy.polys.polytools.Poly method),
bounds (sympy.geometry.polygon.Polygon at- 852
tribute), 653 cancel() (sympy.polys.rings.PolyElement
bq (sympy.functions.special.hyper.hyper at- method), 1001
tribute), 554 canon_bp() (in module sympy.tensor.tensor),
bq (sympy.functions.special.hyper.meijerg at- 1430
tribute), 557 canon_bp() (sympy.tensor.tensor.TensAdd
Bra (class in sympy.physics.quantum.state), method), 1426
1744 canon_bp() (sympy.tensor.tensor.TensMul
bra (sympy.physics.quantum.operator.OuterProduct method), 1428
attribute), 1722 canonical_variables (sympy.core.basic.Basic
bra (sympy.physics.secondquant.InnerProduct attribute), 103
attribute), 1527 canonicalize() (in module
BraBase (class in sympy.combinatorics.tensor_can),
sympy.physics.quantum.state), 1742 295
bracelets() (in module capture() (in module
sympy.utilities.iterables), 1458 sympy.utilities.iterables), 1458
BreakToken (class in sympy.codegen.ast), 416 cardinality (sympy.combinatorics.permutations.Permutation
brewster_angle() (in module attribute), 219
sympy.physics.optics.utils), 1779 cardinality (sympy.combinatorics.subsets.Subset
bsgs_direct_product() (in module attribute), 275

Index 1969
SymPy Documentation, Release 1.3

cartan_matrix() (sympy.liealgebras.root_system.RootSystem method), 243

method), 728 centroid (sympy.geometry.polygon.Polygon
cartan_matrix() (sympy.liealgebras.type_a.TypeA attribute), 653
method), 730 centroid (sympy.geometry.polygon.RegularPolygon
cartan_matrix() (sympy.liealgebras.type_b.TypeB attribute), 659
method), 731 centroid() (in module sympy.geometry.util),
cartan_matrix() (sympy.liealgebras.type_c.TypeC 589
method), 732 CG (class in sympy.physics.quantum.cg),
cartan_matrix() (sympy.liealgebras.type_d.TypeD 1709
method), 734 cg_simp() (in module
cartan_matrix() (sympy.liealgebras.type_e.TypeE sympy.physics.quantum.cg), 1711
method), 735 CGate (class in sympy.physics.quantum.gate),
cartan_matrix() (sympy.liealgebras.type_f.TypeF 1751
method), 736 CGateS (class in sympy.physics.quantum.gate),
cartan_matrix() (sympy.liealgebras.type_g.TypeG 1755
method), 738 characteristic() (sympy.polys.domains.domain.Domain
CartanMatrix() (in module method), 931
sympy.liealgebras.cartan_matrix), characteristic() (sympy.polys.domains.FiniteField
741 method), 937
CartanType_generator (class in chebyshevt (class in
sympy.liealgebras.cartan_type), sympy.functions.special.polynomials),
740 566
casoratian() (in module chebyshevt_poly() (in module
sympy.matrices.dense), 782 sympy.polys.orthopolys), 899
cast_check() (sympy.codegen.ast.Type chebyshevt_root (class in
method), 425 sympy.functions.special.polynomials),
cast_nocheck (sympy.codegen.ast.FloatBaseType 568
attribute), 418 chebyshevu (class in
cast_nocheck() (sympy.codegen.ast.FloatType sympy.functions.special.polynomials),
method), 419 567
Catalan (class in sympy.core.numbers), 155 chebyshevu_poly() (in module
catalan (class in sympy.functions.combinatorial.numbers), sympy.polys.orthopolys), 899
483 chebyshevu_root (class in
Category (class in sympy.categories), 1819 sympy.functions.special.polynomials),
Cauchy() (in module sympy.stats), 1228 568
Cbrt (class in sympy.codegen.cfunctions), 429 check_and_join() (in module
cbrt() (in module sympy.crypto.crypto), 344
sympy.functions.elementary.miscellaneous),
check_assumptions() (in module
477 sympy.solvers.solvers), 1341
ccode() (in module sympy.printing.ccode), check_output() (sympy.utilities.runtests.SymPyOutputCheck
1051 method), 1489
CCodeGen (class in sympy.utilities.codegen), checkinfsol() (in module sympy.solvers.ode),
1441 1269
ceiling (class in sympy.functions.elementary.integers),
checkodesol() (in module sympy.solvers.ode),
467 1267
center (sympy.geometry.ellipse.Ellipse at- checkpdesol() (in module sympy.solvers.pde),
tribute), 637 1323
center (sympy.geometry.polygon.RegularPolygon checksol() (in module sympy.solvers.solvers),
attribute), 659 1341
center() (sympy.combinatorics.perm_groups.PermutationGroup
Chi (class in sympy.functions.special.error_functions),
method), 243 533
central_inertia (sympy.physics.mechanics.rigidbody.RigidBody
Chi() (in module sympy.stats), 1228
attribute), 1685 ChiNoncentral() (in module sympy.stats),
centralizer() (sympy.combinatorics.perm_groups.PermutationGroup
1229

1970 Index
 SymPy Documentation, Release 1.3

ChiSquared() (in module sympy.stats), 1229 CNotGate (class in

cholesky() (sympy.matrices.matrices.MatrixBase sympy.physics.quantum.gate), 1753
method), 767 CodeBlock (class in sympy.codegen.ast), 416
cholesky() (sympy.matrices.sparse.SparseMatrixCodeGen (class in sympy.utilities.codegen),
method), 794 1440
cholesky_solve() (sympy.matrices.matrices.MatrixBase
codegen() (in module
method), 768 sympy.utilities.codegen), 1445
Ci (class in sympy.functions.special.error_functions),
CodePrinter (class in
530 sympy.printing.codeprinter), 1083
Circle (class in sympy.geometry.ellipse), 647 CodeWrapper (class in
circumcenter (sympy.geometry.polygon.RegularPolygonsympy.utilities.autowrap), 1432
attribute), 660 codomain (sympy.categories.CompositeMorphism
circumcenter (sympy.geometry.polygon.Triangle attribute), 1817
attribute), 666 codomain (sympy.categories.Morphism at-
circumcircle (sympy.geometry.polygon.RegularPolygon tribute), 1815
attribute), 660 coeff() (sympy.core.expr.Expr method), 123
circumcircle (sympy.geometry.polygon.Triangle coeff() (sympy.polys.rings.PolyElement
attribute), 667 method), 1001
circumference (sympy.geometry.ellipse.Circle coeff() (sympy.series.sequences.SeqBase
attribute), 648 method), 1145
circumference (sympy.geometry.ellipse.Ellipse coeff_monomial() (sympy.polys.polytools.Poly
attribute), 637 method), 852
circumradius (sympy.geometry.polygon.RegularPolygon
coeff_mul() (sympy.series.sequences.EmptySequence
attribute), 660 method), 1148
circumradius (sympy.geometry.polygon.Trianglecoeff_mul() (sympy.series.sequences.SeqBase
attribute), 667 method), 1145
CL (sympy.matrices.sparse.SparseMatrix at- coeff_mul() (sympy.series.sequences.SeqFormula
tribute), 792 method), 1147
class_key() (sympy.core.add.Add class coeff_mul() (sympy.series.sequences.SeqPer
method), 165 method), 1148
class_key() (sympy.core.basic.Basic class coefficients (sympy.geometry.line.Line2D at-
method), 103 tribute), 623
classify_diop() (in module coeffs() (sympy.polys.numberfields.AlgebraicNumber
sympy.solvers.diophantine), 1353 method), 893
classify_ode() (in module sympy.solvers.ode), coeffs() (sympy.polys.polyclasses.DMP
1265 method), 945
classify_pde() (in module sympy.solvers.pde), coeffs() (sympy.polys.polytools.Poly method),
1322 853
clear() (sympy.tensor.tensor._TensorManager coeffs() (sympy.polys.rings.PolyElement
method), 1415 method), 1001
clear_denoms() (sympy.polys.polyclasses.DMP CoercionFailed (class in
method), 945 sympy.polys.polyerrors), 1026
clear_denoms() (sympy.polys.polytools.Poly cofactors() (in module sympy.polys.polytools),
method), 852 837
clebsch_gordan() (in module cofactors() (sympy.core.numbers.Number
sympy.physics.wigner), 1538 method), 142
closing_angle() (sympy.geometry.line.Ray2D cofactors() (sympy.polys.domains.domain.Domain
method), 624 method), 931
closure (sympy.sets.sets.Set attribute), 1163 cofactors() (sympy.polys.polyclasses.DMP
CMod (class in sympy.physics.quantum.shor), method), 945
1763 cofactors() (sympy.polys.polytools.Poly
cmplx (class in sympy.codegen.fnodes), 438 method), 853
CNOT (in module coherent_state() (in module
sympy.physics.quantum.gate), 1754 sympy.physics.qho_1d), 1516

Index 1971
SymPy Documentation, Release 1.3

Coin() (in module sympy.stats), 1222 1711

col_del() (sympy.matrices.dense.MutableDenseMatrix
Commutator (class in
method), 787 sympy.physics.secondquant), 1529
col_del() (sympy.matrices.sparse.MutableSparseMatrix
commutator() (sympy.combinatorics.perm_groups.Permutati
method), 797 method), 244
col_join() (sympy.matrices.sparse.MutableSparseMatrix
commutator() (sympy.combinatorics.permutations.Permutat
method), 797 method), 219
col_list() (sympy.matrices.sparse.SparseMatrix commutes_with() (sympy.combinatorics.permutations.Permu
method), 794 method), 220
col_op() (sympy.matrices.dense.MutableDenseMatrix
commutes_with() (sympy.tensor.tensor.TensorHead
method), 787 method), 1424
col_op() (sympy.matrices.sparse.MutableSparseMatrix
compare() (in module sympy.series.gruntz),
method), 798 1138
col_swap() (sympy.matrices.dense.MutableDenseMatrix
compare() (sympy.core.basic.Basic method),
method), 788 104
col_swap() (sympy.matrices.sparse.MutableSparseMatrix
Complement (class in sympy.sets.sets), 1175
method), 798 complement() (sympy.sets.sets.Set method),
collect() (in module sympy.simplify.radsimp), 1163
1194 complex, 99
collect() (sympy.core.expr.Expr method), 125 complex (sympy.assumptions.ask.AssumptionKeys
collect_const() (in module attribute), 1105
sympy.simplify.radsimp), 1197 complex_elements (sympy.assumptions.ask.AssumptionKeys
collect_sqrt() (in module attribute), 1106
sympy.simplify.radsimp), 1197 ComplexInfinity (class in
sympy.core.numbers), 153
comb_explicit_rhs (sympy.physics.mechanics.system.SymbolicSystem
attribute), 1701 ComplexRegion (class in
comb_implicit_mat (sympy.physics.mechanics.system.SymbolicSystem
sympy.sets.fancysets), 1181
attribute), 1701 ComplexRootOf (class in
comb_implicit_rhs (sympy.physics.mechanics.system.SymbolicSystem
sympy.polys.rootoftools), 895
attribute), 1702 ComplexSpace (class in
combsimp() (in module sympy.physics.quantum.hilbert),
sympy.simplify.combsimp), 1204 1718
combsimp() (sympy.core.expr.Expr method), ComplexType (class in sympy.codegen.ast),
125 417
comm_i2symbol() (sympy.tensor.tensor._TensorManager
components (sympy.categories.CompositeMorphism
method), 1415 attribute), 1817
comm_symbols2i() (sympy.tensor.tensor._TensorManager
components (sympy.vector.dyadic.Dyadic at-
method), 1415 tribute), 1875
CommaOperator (class in components (sympy.vector.vector.Vector at-
sympy.codegen.cnodes), 433 tribute), 1872
Comment (class in sympy.codegen.ast), 417 compose() (in module sympy.polys.polytools),
common_prefix() (in module 839
sympy.utilities.iterables), 1458 compose() (sympy.categories.Morphism
common_suffix() (in module method), 1815
sympy.utilities.iterables), 1459 compose() (sympy.polys.polyclasses.DMP
commutative, 99 method), 945
commutative (sympy.assumptions.ask.AssumptionKeys
compose() (sympy.polys.polytools.Poly
attribute), 1105 method), 853
commutative_diagrams compose() (sympy.polys.rings.PolyRing
(sympy.categories.Category at- method), 1000
tribute), 1819 composite, 99
Commutator (class in sympy.diffgeom), 1838 composite (sympy.assumptions.ask.AssumptionKeys
Commutator (class in attribute), 1106
sympy.physics.quantum.commutator), composite() (in module

1972 Index
 SymPy Documentation, Release 1.3

sympy.ntheory.generate), 312 method), 613

CompositeDomain (class in contains() (sympy.geometry.line.LinearEntity
sympy.polys.domains.compositedomain), method), 605
937 contains() (sympy.geometry.line.Ray method),
CompositeMorphism (class in 615
sympy.categories), 1817 contains() (sympy.geometry.line.Segment
compositepi() (in module method), 618
sympy.ntheory.generate), 313 contains() (sympy.polys.agca.ideals.Ideal
composition() (sympy.holonomic.holonomic.HolonomicFunction
method), 920
method), 683 contains() (sympy.polys.agca.modules.Module
ComputationFailed (class in method), 913
sympy.polys.polyerrors), 1026 contains() (sympy.polys.polytools.GroebnerBasis
compute_explicit_form() method), 887
(sympy.physics.mechanics.system.SymbolicSystem
contains() (sympy.series.order.Order
method), 1702 method), 1142
compute_fps() (in module contains() (sympy.sets.sets.Set method), 1163
sympy.series.formal), 1155 content() (in module sympy.polys.polytools),
compute_known_facts() (in module 839
sympy.assumptions.ask), 1121 content() (sympy.polys.polyclasses.DMP
compute_leading_term() method), 945
(sympy.core.expr.Expr method), content() (sympy.polys.polytools.Poly
125 method), 854
conclusions (sympy.categories.Diagram at- content() (sympy.polys.rings.PolyElement
tribute), 1821 method), 1002
condition_number() continued_fraction_convergents() (in module
(sympy.matrices.matrices.MatrixBase sympy.ntheory.continued_fraction),
method), 768 338
ConditionalDomain (class in sympy.stats.rv), continued_fraction_iterator() (in module
1260 sympy.ntheory.continued_fraction),
conjugate (class in 338
sympy.functions.elementary.complexes),continued_fraction_periodic() (in module
451 sympy.ntheory.continued_fraction),
conjugate (sympy.combinatorics.partitions.IntegerPartition
339
attribute), 210 continued_fraction_reduce() (in module
conjugate_gauss_beams() (in module sympy.ntheory.continued_fraction),
sympy.physics.optics.gaussopt), 340
1775 ContinueToken (class in sympy.codegen.ast),
connect_to() (sympy.diffgeom.CoordSystem 417
method), 1834 ContinuousDomain (class in sympy.stats.crv),
conserve_mpmath_dps() (in module 1261
sympy.utilities.decorator), 1449 ContinuousPSpace (class in sympy.stats.crv),
const() (sympy.polys.rings.PolyElement 1261
method), 1002 ContinuousRV() (in module sympy.stats),
constant_renumber() (in module 1252
sympy.solvers.ode), 1271 contract_metric() (sympy.tensor.tensor.TensAdd
constant_symbols() (sympy.physics.mechanics.system.SymbolicSystem
method), 1426
method), 1702 contract_metric() (sympy.tensor.tensor.TensMul
constantsimp() (in module method), 1428
sympy.solvers.ode), 1272 contraction() (in module
construct_domain() (in module sympy.physics.secondquant), 1530
sympy.polys.constructor), 891 controls (sympy.physics.quantum.gate.CGate
contains() (sympy.combinatorics.perm_groups.PermutationGroup
attribute), 1751
method), 244 controls (sympy.physics.quantum.gate.CNotGate
contains() (sympy.geometry.line.Line attribute), 1754

Index 1973
SymPy Documentation, Release 1.3

convergence_statement method), 768

(sympy.functions.special.hyper.hyper copy() (sympy.polys.rings.PolyElement
attribute), 554 method), 1002
convert() (sympy.polys.agca.modules.FreeModule copy() (sympy.series.gruntz.SubsSet
method), 913 method), 1140
convert() (sympy.polys.agca.modules.Module copyin_list() (sympy.matrices.dense.MutableDenseMatrix
method), 913 method), 788
convert() (sympy.polys.agca.modules.QuotientModule
copyin_matrix() (sympy.matrices.dense.MutableDenseMatrix
method), 922 method), 789
convert() (sympy.polys.agca.modules.SubModule core() (in module sympy.ntheory.factor_), 327
method), 915 cornacchia() (in module
convert() (sympy.polys.domains.domain.Domain sympy.solvers.diophantine), 1357
method), 931 corners (sympy.combinatorics.polyhedron.Polyhedron
convert() (sympy.polys.polyclasses.DMP attribute), 268
method), 945 cos (class in sympy.functions.elementary.trigonometric),
convert_from() (sympy.polys.domains.domain.Domain 453
method), 931 coset_factor() (sympy.combinatorics.perm_groups.Permutati
convert_to() (in module method), 245
sympy.physics.units.util), 1555 coset_rank() (sympy.combinatorics.perm_groups.Permutatio
convert_to() (sympy.physics.units.quantities.Quantity method), 246
method), 1554 coset_table() (sympy.combinatorics.perm_groups.Permutatio
convert_to_native_paths() (in module method), 247
sympy.utilities.runtests), 1489 coset_transversal() (sympy.combinatorics.perm_groups.Perm
convert_xor() (in module method), 247
sympy.parsing.sympy_parser), 1499 coset_unrank() (sympy.combinatorics.perm_groups.Permuta
convex_hull() (in module method), 247
sympy.geometry.util), 587 cosh (class in sympy.functions.elementary.hyperbolic),
convolution() (in module 464
sympy.discrete.convolutions), 388 cosine_transform() (in module
convolution_fft() (in module sympy.integrals.transforms), 694
sympy.discrete.convolutions), 389 cot (class in sympy.functions.elementary.trigonometric),
convolution_fwht() (in module 455
sympy.discrete.convolutions), 390 coth (class in sympy.functions.elementary.hyperbolic),
convolution_ntt() (in module 464
sympy.discrete.convolutions), 390 could_extract_minus_sign()
convolution_subset() (in module (sympy.core.expr.Expr method),
sympy.discrete.convolutions), 391 125
coord_function() (sympy.diffgeom.CoordSystem count() (sympy.core.basic.Basic method), 104
method), 1835 count_complex_roots()
coord_functions() (sympy.diffgeom.CoordSystem (sympy.polys.polyclasses.DMP
method), 1835 method), 945
coord_tuple_transform_to() count_ops() (in module sympy.core.function),
(sympy.diffgeom.CoordSystem 197
method), 1835 count_ops() (sympy.core.basic.Basic method),
coordinates (sympy.physics.mechanics.system.SymbolicSystem
104
attribute), 1702 count_ops() (sympy.core.expr.Expr method),
CoordinateSym (class in 126
sympy.physics.vector.frame), 1593 count_partitions() (sympy.utilities.enumerative.MultisetPart
coords() (sympy.diffgeom.Point method), method), 1453
1836 count_real_roots() (sympy.polys.polyclasses.DMP
CoordSys3D (class in method), 945
sympy.vector.coordsysrect), 1865 count_roots() (in module
CoordSystem (class in sympy.diffgeom), 1833 sympy.polys.polytools), 843
copy() (sympy.matrices.matrices.MatrixBase count_roots() (sympy.polys.polytools.Poly

1974 Index
 SymPy Documentation, Release 1.3

method), 854 attribute), 281

couple() (in module Curve (class in sympy.geometry.curve), 631
sympy.physics.quantum.spin), 1740 CurvedMirror (class in
CovarDerivativeOp (class in sympy.diffgeom), sympy.physics.optics.gaussopt),
1841 1768
Covariance (class in sympy.stats), 1258 CurvedRefraction (class in
covariance() (in module sympy.stats), 1258 sympy.physics.optics.gaussopt),
covering_product() (in module 1767
sympy.discrete.convolutions), 392 CXX11CodePrinter (class in
coxeter_diagram() (sympy.liealgebras.weyl_group.WeylGroupsympy.printing.cxxcode), 1054
method), 739 CXX98CodePrinter (class in
create_expand_pow_optimization() (in mod- sympy.printing.cxxcode), 1054
ule sympy.codegen.rewriting), 410 cxxcode() (in module
create_new() (sympy.vector.coordsysrect.CoordSys3D sympy.printing.cxxcode), 1054
method), 1866 Cycle (class in sympy.combinatorics.permutations),
CreateBoson (class in 236
sympy.physics.secondquant), 1523 cycle_length() (in module
CreateCGate() (in module sympy.ntheory.generate), 311
sympy.physics.quantum.circuitplot), cycle_list() (in module sympy.crypto.crypto),
1750 344
CreateFermion (class in cycle_structure (sympy.combinatorics.permutations.Permuta
sympy.physics.secondquant), 1524 attribute), 220
cross() (in module cycles (sympy.combinatorics.permutations.Permutation
sympy.physics.vector.functions), attribute), 221
1619 cyclic() (sympy.combinatorics.generators
cross() (sympy.matrices.matrices.MatrixBase method), 237
method), 769 cyclic_form (sympy.combinatorics.permutations.Permutation
cross() (sympy.physics.vector.dyadic.Dyadic attribute), 221
method), 1604 cyclic_form (sympy.combinatorics.polyhedron.Polyhedron
cross() (sympy.physics.vector.vector.Vector attribute), 268
method), 1599 CyclicGroup() (in module
cross() (sympy.vector.deloperator.Del sympy.combinatorics.named_groups),
method), 1877 286
cross() (sympy.vector.dyadic.Dyadic method), cyclotomic_poly() (in module
1875 sympy.polys.specialpolys), 898
cross() (sympy.vector.vector.Vector method), CythonCodeWrapper (class in
1873 sympy.utilities.autowrap), 1432
crt() (in module sympy.ntheory.modular), 329
crt1() (in module sympy.ntheory.modular), D
330 D (sympy.matrices.matrices.MatrixBase at-
crt2() (in module sympy.ntheory.modular), tribute), 762
330 D (sympy.physics.optics.gaussopt.RayTransferMatrix
csc (class in sympy.functions.elementary.trigonometric),attribute), 1766
456 D() (sympy.physics.quantum.spin.Rotation
csch (class in sympy.functions.elementary.hyperbolic), class method), 1732
465 d() (sympy.physics.quantum.spin.Rotation
cse() (in module sympy.simplify.cse_main), class method), 1733
1205 Dagger (class in sympy.physics.quantum.dagger),
cse() (sympy.codegen.ast.CodeBlock 1713
method), 416 Dagger (class in sympy.physics.secondquant),
curl() (in module sympy.physics.vector.fieldfunctions), 1518
1622 Dagum() (in module sympy.stats), 1230
curl() (in module sympy.vector), 1883 DataType (class in sympy.utilities.codegen),
current (sympy.combinatorics.graycode.GrayCode 1439

Index 1975
SymPy Documentation, Release 1.3

dcm() (sympy.physics.vector.frame.ReferenceFrame method), 1789

method), 1595 deflection() (sympy.physics.continuum_mechanics.beam.Bea
debug() (in module sympy.utilities.misc), method), 1799
1482 degree (sympy.combinatorics.perm_groups.PermutationGrou
debug_decorator() (in module attribute), 247
sympy.utilities.misc), 1482 degree() (in module sympy.polys.polytools),
decimal_dig (sympy.codegen.ast.FloatType 828
attribute), 419 degree() (sympy.polys.polyclasses.DMP
decipher_affine() (in module method), 945
sympy.crypto.crypto), 346 degree() (sympy.polys.polytools.Poly
decipher_bifid() (in module method), 855
sympy.crypto.crypto), 352 degree() (sympy.polys.rings.PolyElement
decipher_bifid5() (in module method), 1002
sympy.crypto.crypto), 355 degree_list() (in module
decipher_bifid6() (in module sympy.polys.polytools), 829
sympy.crypto.crypto), 356 degree_list() (sympy.polys.polyclasses.DMP
decipher_elgamal() (in module method), 946
sympy.crypto.crypto), 363, 366 degree_list() (sympy.polys.polytools.Poly
decipher_gm() (in module method), 855
sympy.crypto.crypto), 368 degrees() (sympy.polys.rings.PolyElement
decipher_hill() (in module method), 1002
sympy.crypto.crypto), 351 Del (class in sympy.vector.deloperator), 1877
decipher_kid_rsa() (in module delete_doubles() (sympy.liealgebras.weyl_group.WeylGroup
sympy.crypto.crypto), 359 method), 739
decipher_rsa() (in module delta (sympy.functions.special.hyper.meijerg
sympy.crypto.crypto), 358 attribute), 557
decipher_shift() (in module denom() (sympy.polys.domains.AlgebraicField
sympy.crypto.crypto), 345 method), 940
decipher_vigenere() (in module denom() (sympy.polys.domains.domain.Domain
sympy.crypto.crypto), 350 method), 931
Declaration (class in sympy.codegen.ast), 418 denom() (sympy.polys.domains.ExpressionDomain
decode_morse() (in module method), 943
sympy.crypto.crypto), 359 denom() (sympy.polys.domains.FractionField
decompose() (in module method), 941
sympy.polys.polytools), 840 denom() (sympy.polys.domains.ring.Ring
decompose() (sympy.physics.quantum.gate.CGate method), 935
method), 1751 denom() (sympy.polys.polyclasses.DMF
decompose() (sympy.physics.quantum.gate.SwapGate method), 950
method), 1753 density() (in module sympy.stats), 1255
decompose() (sympy.physics.quantum.qft.IQFT depth() (sympy.polys.agca.ideals.Ideal
method), 1758 method), 920
decompose() (sympy.physics.quantum.qft.QFT Derivative (class in sympy.core.function), 183
method), 1758 derive_by_array() (in module
decompose() (sympy.polys.polyclasses.DMP sympy.tensor.array), 1403
method), 945 derived_series() (sympy.combinatorics.perm_groups.Permut
decompose() (sympy.polys.polytools.Poly method), 247
method), 854 derived_subgroup() (sympy.combinatorics.perm_groups.Perm
deduced() (sympy.codegen.ast.Variable class method), 248
method), 427 descent() (in module
deflate() (sympy.polys.polyclasses.DMP sympy.solvers.diophantine), 1361
method), 945 descents() (sympy.combinatorics.permutations.Permutation
deflate() (sympy.polys.polytools.Poly method), 221
method), 854 deviation() (in module
deflection() (sympy.physics.continuum_mechanics.beam.Beam
sympy.physics.optics.utils), 1778

1976 Index
 SymPy Documentation, Release 1.3

dh_private_key() (in module 286

sympy.crypto.crypto), 364 dim (sympy.physics.units.dimensions.DimensionSystem
dh_public_key() (in module attribute), 1552
sympy.crypto.crypto), 364 dim (sympy.physics.units.unitsystem.UnitSystem
dh_shared_key() (in module attribute), 1553
sympy.crypto.crypto), 365 dim_can_vector() (sympy.physics.units.dimensions.Dimensio
diag() (in module sympy.matrices.dense), 780 method), 1552
diagonal (sympy.assumptions.ask.AssumptionKeys dim_vector() (sympy.physics.units.dimensions.DimensionSys
attribute), 1106 method), 1552
diagonal_solve() (sympy.matrices.matrices.MatrixBase
Dimension (class in
method), 769 sympy.physics.units.dimensions),
Diagram (class in sympy.categories), 1820 1551
DiagramGrid (class in dimension (sympy.physics.quantum.hilbert.HilbertSpace
sympy.categories.diagram_drawing), attribute), 1718
1823 dimension() (in module
Dict (class in sympy.core.containers), 203 sympy.codegen.fnodes), 438
dict_merge() (in module dimension() (sympy.liealgebras.type_a.TypeA
sympy.utilities.iterables), 1459 method), 730
Die() (in module sympy.stats), 1221 dimension() (sympy.liealgebras.type_b.TypeB
DiePSpace (class in sympy.stats.frv_types), method), 731
1261 dimension() (sympy.liealgebras.type_c.TypeC
diff() (in module sympy.core.function), 187 method), 733
diff() (sympy.holonomic.holonomic.HolonomicFunction
dimension() (sympy.liealgebras.type_d.TypeD
method), 683 method), 734
diff() (sympy.physics.vector.vector.Vector dimension() (sympy.liealgebras.type_e.TypeE
method), 1600 method), 736
diff() (sympy.polys.polyclasses.DMP method), dimension() (sympy.liealgebras.type_f.TypeF
946 method), 737
diff() (sympy.polys.polytools.Poly method), dimension() (sympy.liealgebras.type_g.TypeG
855 method), 738
diff() (sympy.polys.rings.PolyElement DimensionSystem (class in
method), 1002 sympy.physics.units.dimensions),
difference_delta() (in module 1551
sympy.series.limitseq), 1160 diop_bf_DN() (in module
Differential (class in sympy.diffgeom), 1838 sympy.solvers.diophantine), 1358
DifferentialOperator (class in diop_DN() (in module
sympy.physics.quantum.operator), sympy.solvers.diophantine), 1356
1723 diop_general_pythagorean() (in module
differentiate_finite() (in module sympy.solvers.diophantine), 1362
sympy.calculus.finite_diff), 1507 diop_general_sum_of_even_powers() (in mod-
dig (sympy.codegen.ast.FloatType attribute), ule sympy.solvers.diophantine), 1363
419 diop_general_sum_of_squares() (in module
digamma() (in module sympy.solvers.diophantine), 1362
diop_linear()
sympy.functions.special.gamma_functions), (in module
509 sympy.solvers.diophantine), 1354
digit_2txt (in module diop_quadratic() (in module
sympy.printing.pretty.pretty_symbology), sympy.solvers.diophantine), 1356
1083 diop_solve() (in module
digits() (in module sympy.ntheory.factor_), sympy.solvers.diophantine), 1354
327 diop_ternary_quadratic() (in module
dihedral() (sympy.combinatorics.generators sympy.solvers.diophantine), 1360
method), 238 diop_ternary_quadratic_normal() (in module
DihedralGroup() (in module sympy.solvers.diophantine), 1369
sympy.combinatorics.named_groups), diophantine() (in module

Index 1977
SymPy Documentation, Release 1.3

sympy.solvers.diophantine), 1352 div() (sympy.polys.domains.field.Field

DiracDelta (class in method), 934
div()
sympy.functions.special.delta_functions), (sympy.polys.domains.ring.Ring
498 method), 935
direction (sympy.geometry.line.LinearEntity div() (sympy.polys.polyclasses.DMP method),
attribute), 605 946
direction_cosine (sympy.geometry.line.LinearEntity3D
div() (sympy.polys.polytools.Poly method),
attribute), 626 858
direction_cosine() (sympy.geometry.point.Point3Ddiv() (sympy.polys.rings.PolyElement
method), 600 method), 1003
direction_ratio (sympy.geometry.line.LinearEntity3D
divergence (sympy.physics.optics.gaussopt.BeamParameter
attribute), 627 attribute), 1771
direction_ratio() (sympy.geometry.point.Point3Ddivergence() (in module
method), 600 sympy.physics.vector.fieldfunctions),
DirectProduct() (in module 1622
sympy.combinatorics.group_constructs),divergence() (in module sympy.vector), 1883
294 divisible() (in module
dirichlet_eta (class in sympy.solvers.diophantine), 1367
sympy.functions.special.zeta_functions),divisor_count() (in module
549 sympy.ntheory.factor_), 322
discrete_log() (in module divisor_sigma (class in
sympy.ntheory.residue_ntheory), sympy.ntheory.factor_), 325
337 divisors() (in module sympy.ntheory.factor_),
DiscreteUniform() (in module sympy.stats), 322
1221 DMF (class in sympy.polys.polyclasses), 950
discriminant() (in module DMP (class in sympy.polys.polyclasses), 945
sympy.polys.polytools), 833 dmp_abs() (in module
discriminant() (sympy.polys.polyclasses.DMP sympy.polys.densearith), 966
method), 946 dmp_add() (in module
discriminant() (sympy.polys.polytools.Poly sympy.polys.densearith), 967
method), 855 dmp_add_ground() (in module
dispersion() (in module sympy.polys.densearith), 965
sympy.polys.dispersion), 833, 906 dmp_add_mul() (in module
dispersion() (sympy.polys.polytools.Poly sympy.polys.densearith), 967
method), 856 dmp_add_term() (in module
dispersionset() (in module sympy.polys.densearith), 964
sympy.polys.dispersion), 835, 905 dmp_apply_pairs() (in module
dispersionset() (sympy.polys.polytools.Poly sympy.polys.densebasic), 963
method), 857 dmp_cancel() (in module
distance() (sympy.geometry.line.Line sympy.polys.euclidtools), 1019
method), 614 dmp_clear_denoms() (in module
distance() (sympy.geometry.line.Ray method), sympy.polys.densetools), 980
616 dmp_compose() (in module
distance() (sympy.geometry.line.Segment sympy.polys.densetools), 979
method), 618 dmp_content() (in module
distance() (sympy.geometry.plane.Plane sympy.polys.euclidtools), 1019
method), 674 dmp_convert() (in module
distance() (sympy.geometry.point.Point sympy.polys.densebasic), 956
method), 592 dmp_copy() (in module
distance() (sympy.geometry.polygon.Polygon sympy.polys.densebasic), 955
method), 653 dmp_deflate() (in module
div() (in module sympy.polys.polytools), 831 sympy.polys.densebasic), 961
div() (sympy.polys.domains.domain.Domain dmp_degree() (in module
method), 931 sympy.polys.densebasic), 953

1978 Index
 SymPy Documentation, Release 1.3

dmp_degree_in() (in module dmp_ground_extract() (in module

sympy.polys.densebasic), 953 sympy.polys.densetools), 977
dmp_degree_list() (in module dmp_ground_LC() (in module
sympy.polys.densebasic), 954 sympy.polys.densebasic), 952
dmp_diff() (in module dmp_ground_monic() (in module
sympy.polys.densetools), 973 sympy.polys.densetools), 975
dmp_diff_eval_in() (in module dmp_ground_nth() (in module
sympy.polys.densetools), 974 sympy.polys.densebasic), 956
dmp_diff_in() (in module dmp_ground_p() (in module
sympy.polys.densetools), 973 sympy.polys.densebasic), 958
dmp_discriminant() (in module dmp_ground_primitive() (in module
sympy.polys.euclidtools), 1016 sympy.polys.densetools), 977
dmp_div() (in module dmp_ground_TC() (in module
sympy.polys.densearith), 970 sympy.polys.densebasic), 953
dmp_eject() (in module dmp_ground_trunc() (in module
sympy.polys.densebasic), 963 sympy.polys.densetools), 975
dmp_euclidean_prs() (in module dmp_grounds() (in module
sympy.polys.euclidtools), 1011 sympy.polys.densebasic), 958
dmp_eval() (in module dmp_half_gcdex() (in module
sympy.polys.densetools), 973 sympy.polys.euclidtools), 1011
dmp_eval_in() (in module dmp_include() (in module
sympy.polys.densetools), 974 sympy.polys.densebasic), 962
dmp_eval_tail() (in module dmp_inflate() (in module
sympy.polys.densetools), 974 sympy.polys.densebasic), 961
dmp_exclude() (in module dmp_inject() (in module
sympy.polys.densebasic), 962 sympy.polys.densebasic), 962
dmp_expand() (in module dmp_inner_gcd() (in module
sympy.polys.densearith), 972 sympy.polys.euclidtools), 1018
dmp_exquo() (in module dmp_inner_subresultants() (in module
sympy.polys.densearith), 971 sympy.polys.euclidtools), 1014
dmp_exquo_ground() (in module dmp_integrate() (in module
sympy.polys.densearith), 966 sympy.polys.densetools), 972
dmp_ext_factor() (in module dmp_integrate_in() (in module
sympy.polys.factortools), 1023 sympy.polys.densetools), 972
dmp_factor_list() (in module dmp_invert() (in module
sympy.polys.factortools), 1023 sympy.polys.euclidtools), 1011
dmp_factor_list_include() (in module dmp_irreducible_p() (in module
sympy.polys.factortools), 1023 sympy.polys.factortools), 1023
dmp_ff_div() (in module dmp_l1_norm() (in module
sympy.polys.densearith), 970 sympy.polys.densearith), 972
dmp_ff_prs_gcd() (in module dmp_LC() (in module
sympy.polys.euclidtools), 1017 sympy.polys.densebasic), 952
dmp_from_dict() (in module dmp_lcm() (in module
sympy.polys.densebasic), 959 sympy.polys.euclidtools), 1019
dmp_from_sympy() (in module dmp_lift() (in module
sympy.polys.densebasic), 956 sympy.polys.densetools), 980
dmp_gcd() (in module dmp_list_terms() (in module
sympy.polys.euclidtools), 1018 sympy.polys.densebasic), 963
dmp_gcdex() (in module dmp_max_norm() (in module
sympy.polys.euclidtools), 1011 sympy.polys.densearith), 971
dmp_ground() (in module dmp_mul() (in module
sympy.polys.densebasic), 958 sympy.polys.densearith), 968
dmp_ground_content() (in module dmp_mul_ground() (in module
sympy.polys.densetools), 976 sympy.polys.densearith), 965

Index 1979
SymPy Documentation, Release 1.3

dmp_mul_term() (in module dmp_rr_div() (in module

sympy.polys.densearith), 964 sympy.polys.densearith), 970
dmp_multi_deflate() (in module dmp_rr_prs_gcd() (in module
sympy.polys.densebasic), 961 sympy.polys.euclidtools), 1016
dmp_neg() (in module dmp_slice() (in module
sympy.polys.densearith), 967 sympy.polys.densebasic), 964
dmp_negative_p() (in module dmp_sqr() (in module
sympy.polys.densebasic), 959 sympy.polys.densearith), 968
dmp_nest() (in module dmp_strip() (in module
sympy.polys.densebasic), 960 sympy.polys.densebasic), 954
dmp_normal() (in module dmp_sub() (in module
sympy.polys.densebasic), 955 sympy.polys.densearith), 967
dmp_nth() (in module dmp_sub_ground() (in module
sympy.polys.densebasic), 956 sympy.polys.densearith), 965
dmp_one() (in module dmp_sub_mul() (in module
sympy.polys.densebasic), 957 sympy.polys.densearith), 968
dmp_one_p() (in module dmp_sub_term() (in module
sympy.polys.densebasic), 957 sympy.polys.densearith), 964
dmp_pdiv() (in module dmp_subresultants() (in module
sympy.polys.densearith), 968 sympy.polys.euclidtools), 1014
dmp_permute() (in module dmp_swap() (in module
sympy.polys.densebasic), 960 sympy.polys.densebasic), 960
dmp_pexquo() (in module dmp_TC() (in module
sympy.polys.densearith), 969 sympy.polys.densebasic), 952
dmp_positive_p() (in module dmp_terms_gcd() (in module
sympy.polys.densebasic), 959 sympy.polys.densebasic), 963
dmp_pow() (in module dmp_to_dict() (in module
sympy.polys.densearith), 968 sympy.polys.densebasic), 959
dmp_pquo() (in module dmp_to_tuple() (in module
sympy.polys.densearith), 969 sympy.polys.densebasic), 955
dmp_prem() (in module dmp_trial_division() (in module
sympy.polys.densearith), 969 sympy.polys.factortools), 1020
dmp_primitive() (in module dmp_true_LT() (in module
sympy.polys.euclidtools), 1019 sympy.polys.densebasic), 953
dmp_primitive_prs() (in module dmp_trunc() (in module
sympy.polys.euclidtools), 1012 sympy.polys.densetools), 974
dmp_prs_resultant() (in module dmp_validate() (in module
sympy.polys.euclidtools), 1014 sympy.polys.densebasic), 954
dmp_qq_collins_resultant() (in module dmp_zero() (in module
sympy.polys.euclidtools), 1015 sympy.polys.densebasic), 957
dmp_qq_heu_gcd() (in module dmp_zero_p() (in module
sympy.polys.euclidtools), 1018 sympy.polys.densebasic), 957
dmp_quo() (in module dmp_zeros() (in module
sympy.polys.densearith), 971 sympy.polys.densebasic), 958
dmp_quo_ground() (in module dmp_zz_collins_resultant() (in module
sympy.polys.densearith), 965 sympy.polys.euclidtools), 1015
dmp_raise() (in module dmp_zz_diophantine() (in module
sympy.polys.densebasic), 961 sympy.polys.factortools), 1022
dmp_rem() (in module dmp_zz_factor() (in module
sympy.polys.densearith), 970 sympy.polys.factortools), 1023
dmp_resultant() (in module dmp_zz_heu_gcd() (in module
sympy.polys.euclidtools), 1016 sympy.polys.euclidtools), 1017
dmp_revert() (in module dmp_zz_mignotte_bound() (in module
sympy.polys.densetools), 980 sympy.polys.factortools), 1020

1980 Index
 SymPy Documentation, Release 1.3

dmp_zz_modular_resultant() (in module method), 1061

sympy.polys.euclidtools), 1015 doprint() (sympy.printing.printer.Printer
dmp_zz_wang() (in module method), 1050
sympy.polys.factortools), 1022 doprint() (sympy.printing.theanocode.TheanoPrinter
dmp_zz_wang_hensel_lifting() (in module method), 1071
sympy.polys.factortools), 1022 dot() (in module sympy.physics.vector.functions),
dmp_zz_wang_lead_coeffs() (in module 1618
sympy.polys.factortools), 1022 dot() (sympy.geometry.point.Point method),
dmp_zz_wang_non_divisors() (in module 592
sympy.polys.factortools), 1022 dot() (sympy.matrices.matrices.MatrixBase
dmp_zz_wang_test_points() (in module method), 769
sympy.polys.factortools), 1022 dot() (sympy.physics.vector.dyadic.Dyadic
Do (class in sympy.codegen.fnodes), 434 method), 1604
do_subs() (sympy.series.gruntz.SubsSet dot() (sympy.physics.vector.vector.Vector
method), 1140 method), 1601
doctest() (in module sympy.utilities.runtests), dot() (sympy.vector.deloperator.Del method),
1489 1877
doctest_depends_on() (in module dot() (sympy.vector.dyadic.Dyadic method),
sympy.utilities.decorator), 1449 1876
doit() (sympy.core.basic.Basic method), 104 dot() (sympy.vector.vector.Vector method),
doit() (sympy.integrals.Integral method), 716 1873
doit() (sympy.physics.quantum.anticommutator.AntiCommutator
dot_rot_grad_Ynm() (in module
method), 1709 sympy.physics.wigner), 1539
doit() (sympy.physics.quantum.commutator.Commutator
dotprint() (in module sympy.printing.dot),
method), 1712 1086
doit() (sympy.physics.secondquant.AntiSymmetricTensor
double_coset_can_rep() (in module
method), 1535 sympy.combinatorics.tensor_can),
doit() (sympy.physics.secondquant.Commutator 297
method), 1529 draw() (sympy.categories.diagram_drawing.XypicDiagramDr
doit() (sympy.physics.secondquant.NO method), 1830
method), 1532 drop() (sympy.polys.rings.PolyRing method),
doit() (sympy.physics.vector.dyadic.Dyadic 1000
method), 1604 drop_to_ground() (sympy.polys.rings.PolyRing
doit() (sympy.physics.vector.vector.Vector method), 1000
method), 1601 dsign (class in sympy.codegen.fnodes), 438
doit() (sympy.series.limits.Limit method), dsolve() (in module sympy.solvers.ode), 1262
1136 dt() (sympy.physics.vector.dyadic.Dyadic
doit_numerically() (sympy.core.function.Derivative method), 1604
method), 187 dt() (sympy.physics.vector.vector.Vector
Domain (class in sympy.polys.domains.domain), method), 1601
931 dtype (sympy.polys.agca.modules.FreeModule
domain (sympy.categories.CompositeMorphism attribute), 914
attribute), 1818 dtype (sympy.polys.agca.modules.QuotientModule
domain (sympy.categories.Morphism at- attribute), 922
tribute), 1816 dtype (sympy.polys.domains.AlgebraicField
domain (sympy.polys.polytools.Poly at- attribute), 940
tribute), 859 dtype (sympy.polys.domains.ExpressionDomain
domain_check() (in module attribute), 943
sympy.solvers.solveset), 1386 dual (sympy.physics.quantum.state.StateBase
DomainError (class in attribute), 1742
sympy.polys.polyerrors), 1026 dual() (sympy.matrices.matrices.MatrixBase
dominant() (in module sympy.series.limitseq), method), 770
1161 dual_class() (sympy.physics.quantum.state.StateBase
doprint() (sympy.printing.mathematica.MCodePrinter class method), 1742

Index 1981
SymPy Documentation, Release 1.3

Dummy (class in sympy.core.symbol), 139 sympy.polys.densetools), 978

dummy_eq() (sympy.core.basic.Basic dup_sign_variations() (in module
method), 104 sympy.polys.densetools), 980
DummyWrapper (class in dup_transform() (in module
sympy.utilities.autowrap), 1433 sympy.polys.densetools), 979
dump_c() (sympy.utilities.autowrap.UfuncifyCodeWrapper
dup_zz_cyclotomic_factor() (in module
method), 1433 sympy.polys.factortools), 1021
dump_c() (sympy.utilities.codegen.CCodeGen dup_zz_cyclotomic_poly() (in module
method), 1441 sympy.polys.factortools), 1021
dump_code() (sympy.utilities.codegen.CodeGen dup_zz_factor() (in module
method), 1440 sympy.polys.factortools), 1021
dump_f95() (sympy.utilities.codegen.FCodeGen dup_zz_factor_sqf() (in module
method), 1442 sympy.polys.factortools), 1021
dump_h() (sympy.utilities.codegen.CCodeGen dup_zz_hensel_lift() (in module
method), 1442 sympy.polys.factortools), 1020
dump_h() (sympy.utilities.codegen.FCodeGen dup_zz_hensel_step() (in module
method), 1443 sympy.polys.factortools), 1020
dump_jl() (sympy.utilities.codegen.JuliaCodeGendup_zz_irreducible_p() (in module
method), 1443 sympy.polys.factortools), 1021
dump_m() (sympy.utilities.codegen.OctaveCodeGendup_zz_zassenhaus() (in module
method), 1444 sympy.polys.factortools), 1021
dump_pyx() (sympy.utilities.autowrap.CythonCodeWrapper
Dyadic (class in sympy.physics.vector.dyadic),
method), 1432 1603
dump_rs() (sympy.utilities.codegen.RustCodeGen Dyadic (class in sympy.vector.dyadic), 1875
method), 1445 dyn_implicit_mat (sympy.physics.mechanics.system.Symboli
dup_content() (in module attribute), 1702
sympy.polys.densetools), 976 dyn_implicit_rhs (sympy.physics.mechanics.system.Symbolic
dup_cyclotomic_p() (in module attribute), 1702
sympy.polys.factortools), 1021 dynamic_symbols() (sympy.physics.mechanics.system.Symbo
dup_decompose() (in module method), 1702
sympy.polys.densetools), 979 dynamicsymbols() (in module
dup_extract() (in module sympy.physics.vector), 1618
sympy.polys.densetools), 977 dynkin_diagram() (sympy.liealgebras.root_system.RootSyste
dup_gf_factor() (in module method), 729
sympy.polys.factortools), 1023 DynkinDiagram() (in module
dup_lshift() (in module sympy.liealgebras.dynkin_diagram),
sympy.polys.densearith), 966 741
dup_mirror() (in module
sympy.polys.densetools), 978 E
dup_monic() (in module E() (in module sympy.stats), 1253
sympy.polys.densetools), 975 E1() (in module sympy.functions.special.error_functions),
dup_primitive() (in module 526
sympy.polys.densetools), 976 E_n() (in module sympy.physics.qho_1d),
dup_random() (in module 1516
sympy.polys.densebasic), 964 E_nl() (in module sympy.physics.hydrogen),
dup_real_imag() (in module 1511
sympy.polys.densetools), 978 E_nl() (in module sympy.physics.sho), 1516
dup_reverse() (in module E_nl_dirac() (in module
sympy.polys.densebasic), 955 sympy.physics.hydrogen), 1511
dup_rshift() (in module EC() (sympy.polys.polytools.Poly method),
sympy.polys.densearith), 966 847
dup_scale() (in module eccentricity (sympy.geometry.ellipse.Ellipse
sympy.polys.densetools), 978 attribute), 638
dup_shift() (in module

1982 Index
 SymPy Documentation, Release 1.3

edges (sympy.combinatorics.polyhedron.Polyhedron encipher_elgamal() (in module

attribute), 268 sympy.crypto.crypto), 363, 366
edges() (sympy.combinatorics.prufer.Prufer encipher_gm() (in module
static method), 270 sympy.crypto.crypto), 367
egyptian_fraction() (in module encipher_hill() (in module
sympy.ntheory.egyptian_fraction), sympy.crypto.crypto), 350
341 encipher_kid_rsa() (in module
Ei (class in sympy.functions.special.error_functions), sympy.crypto.crypto), 358
523 encipher_rsa() (in module
Eijk() (in module sympy.functions.special.tensor_functions),
sympy.crypto.crypto), 357
576 encipher_shift() (in module
eject() (sympy.polys.polyclasses.DMP sympy.crypto.crypto), 344
method), 946 encipher_substitution() (in module
eject() (sympy.polys.polytools.Poly method), sympy.crypto.crypto), 347
859 encipher_vigenere() (in module
elastic_modulus (sympy.physics.continuum_mechanics.beam.Beam
sympy.crypto.crypto), 347
attribute), 1789 encloses() (sympy.geometry.entity.GeometryEntity
Element (class in sympy.codegen.ast), 418 method), 584
element_order() (sympy.liealgebras.weyl_group.WeylGroup
encloses_point() (sympy.geometry.ellipse.Ellipse
method), 739 method), 638
elements (sympy.combinatorics.perm_groups.PermutationGroup
encloses_point() (sympy.geometry.polygon.Polygon
attribute), 248 method), 653
elgamal_private_key() (in module encloses_point() (sympy.geometry.polygon.RegularPolygon
sympy.crypto.crypto), 362 method), 660
elgamal_public_key() (in module encode_morse() (in module
sympy.crypto.crypto), 362 sympy.crypto.crypto), 359
Ellipse (class in sympy.geometry.ellipse), 635 end (sympy.sets.sets.Interval attribute), 1170
elliptic_e (class in enum_all() (sympy.utilities.enumerative.MultisetPartitionTra
sympy.functions.special.elliptic_integrals), method), 1454
558 enum_large() (sympy.utilities.enumerative.MultisetPartitionT
elliptic_f (class in method), 1455
sympy.functions.special.elliptic_integrals),
enum_range() (sympy.utilities.enumerative.MultisetPartition
558 method), 1455
elliptic_k (class in enum_small() (sympy.utilities.enumerative.MultisetPartition
sympy.functions.special.elliptic_integrals), method), 1456
557 enumerate_states() (in module
elliptic_pi (class in sympy.physics.quantum.represent),
sympy.functions.special.elliptic_integrals), 1731
559 EPath (class in sympy.simplify.epathtools),
EM() (sympy.polys.polytools.Poly method), 1208
847 epath() (in module
emptyPrinter() (sympy.printing.repr.ReprPrinter sympy.simplify.epathtools), 1210
method), 1078 eps (sympy.codegen.ast.FloatType attribute),
EmptySequence (class in 419
sympy.series.sequences), 1148 Eq (in module sympy.core.relational), 166
EmptySet (class in sympy.sets.sets), 1175 Equality (class in sympy.core.relational), 167
encipher_affine() (in module equals() (sympy.core.expr.Expr method), 126
sympy.crypto.crypto), 346 equals() (sympy.geometry.line.Line method),
encipher_bifid() (in module 614
sympy.crypto.crypto), 352 equals() (sympy.geometry.line.Ray method),
encipher_bifid5() (in module 616
sympy.crypto.crypto), 354 equals() (sympy.geometry.line.Segment
encipher_bifid6() (in module method), 619
sympy.crypto.crypto), 356 equals() (sympy.geometry.plane.Plane

Index 1983
SymPy Documentation, Release 1.3

method), 675 class method), 504

equals() (sympy.geometry.point.Point eval() (sympy.functions.special.tensor_functions.KroneckerD
method), 592 class method), 577
equals() (sympy.matrices.expressions.MatrixExpr eval() (sympy.physics.secondquant.Commutator
method), 804 class method), 1530
equation() (sympy.geometry.ellipse.Circle eval() (sympy.physics.secondquant.Dagger
method), 648 class method), 1518
equation() (sympy.geometry.ellipse.Ellipse eval() (sympy.physics.secondquant.KroneckerDelta
method), 638 class method), 1519
equation() (sympy.geometry.line.Line2D eval() (sympy.polys.polyclasses.DMP
method), 623 method), 946
equation() (sympy.geometry.line.Line3D eval() (sympy.polys.polytools.Poly method),
method), 628 859
equation() (sympy.geometry.plane.Plane eval_controls() (sympy.physics.quantum.gate.CGate
method), 675 method), 1751
Equivalent (class in sympy.logic.boolalg), 749 eval_expr() (in module
equivalent() (in module sympy.parsing.sympy_parser), 1497
sympy.solvers.diophantine), 1368 eval_levicivita() (in module
erf (class in sympy.functions.special.error_functions), sympy.functions.special.tensor_functions),
514 576
erf2 (class in sympy.functions.special.error_functions),
eval_zeta_function()
517 (sympy.concrete.summations.Sum
erf2inv (class in sympy.functions.special.error_functions),
method), 372
520 evalf() (sympy.geometry.point.Point method),
erfc (class in sympy.functions.special.error_functions), 592
515 evalf() (sympy.holonomic.holonomic.HolonomicFunction
erfcinv (class in sympy.functions.special.error_functions),
method), 685
519 evalf() (sympy.polys.domains.domain.Domain
erfi (class in sympy.functions.special.error_functions), method), 931
516 evaluate_deltas() (in module
erfinv (class in sympy.functions.special.error_functions),sympy.physics.secondquant), 1534
518 evaluate_pauli_product() (in module
Erlang() (in module sympy.stats), 1231 sympy.physics.paulialgebra), 1515
ET() (sympy.polys.polytools.Poly method), EvaluationFailed (class in
848 sympy.polys.polyerrors), 1026
eta (sympy.functions.special.hyper.hyper at- even, 99
tribute), 554 even (sympy.assumptions.ask.AssumptionKeys
euler (class in sympy.functions.combinatorial.numbers),attribute), 1107
484 evolute() (sympy.geometry.ellipse.Ellipse
euler_equations() (in module method), 639
sympy.calculus.euler), 1501 ExactQuotientFailed (class in
euler_maclaurin() (sympy.concrete.summations.Sum sympy.polys.polyerrors), 1026
method), 371 exclude() (sympy.polys.polyclasses.DMP
EulerGamma (class in sympy.core.numbers), method), 946
155 exclude() (sympy.polys.polytools.Poly
eulerline (sympy.geometry.polygon.Triangle method), 859
attribute), 667 exp (class in sympy.functions.elementary.exponential),
eval() (sympy.assumptions.assume.Predicate 470
method), 1123 exp() (sympy.matrices.matrices.MatrixBase
eval() (sympy.functions.special.delta_functions.DiracDeltamethod), 770
class method), 499 Exp1 (class in sympy.core.numbers), 153
eval() (sympy.functions.special.delta_functions.Heaviside
exp2 (class in sympy.codegen.cfunctions),
class method), 501 430
eval() (sympy.functions.special.singularity_functions.SingularityFunction
exp_re() (in module sympy.series.formal),

1984 Index
 SymPy Documentation, Release 1.3

1158 exquo() (in module sympy.polys.polytools),

expand() (in module sympy.core.function), 831
192 exquo() (sympy.polys.domains.domain.Domain
expand() (sympy.core.expr.Expr method), 126 method), 931
expand_complex() (in module exquo() (sympy.polys.domains.field.Field
sympy.core.function), 200 method), 934
expand_func() (in module exquo() (sympy.polys.domains.ring.Ring
sympy.core.function), 199 method), 935
expand_log() (in module exquo() (sympy.polys.polyclasses.DMF
sympy.core.function), 199 method), 950
expand_mul() (in module exquo() (sympy.polys.polyclasses.DMP
sympy.core.function), 198 method), 946
expand_multinomial() (in module exquo() (sympy.polys.polytools.Poly method),
sympy.core.function), 200 860
expand_power_base() (in module exquo_ground() (sympy.polys.polyclasses.DMP
sympy.core.function), 201 method), 946
expand_power_exp() (in module exquo_ground() (sympy.polys.polytools.Poly
sympy.core.function), 200 method), 860
expand_trig() (in module exradii (sympy.geometry.polygon.Triangle at-
sympy.core.function), 199 tribute), 668
Expectation (class in sympy.stats), 1254 extend() (sympy.ntheory.generate.Sieve
expint (class in sympy.functions.special.error_functions),method), 305
525 extend() (sympy.physics.units.unitsystem.UnitSystem
expm1 (class in sympy.codegen.cfunctions), method), 1554
430 extend() (sympy.plotting.plot.Plot method),
Exponential() (in module sympy.stats), 1232 1089
Expr (class in sympy.core.expr), 115 extend_to_no() (sympy.ntheory.generate.Sieve
expr (sympy.core.function.Lambda attribute), method), 306
182 extended_real (sympy.assumptions.ask.AssumptionKeys
expr (sympy.core.function.Subs attribute), attribute), 1107
191 Extent (class in sympy.codegen.fnodes), 435
expr (sympy.physics.quantum.operator.DifferentialOperator
exterior_angle (sympy.geometry.polygon.RegularPolygon
attribute), 1723 attribute), 661
expr (sympy.physics.quantum.state.Wavefunction extract_additively() (sympy.core.expr.Expr
attribute), 1747 method), 126
expr_free_symbols (sympy.core.expr.Expr at- extract_branch_factor()
tribute), 126 (sympy.core.expr.Expr method),
expr_to_holonomic() (in module 127
sympy.holonomic.holonomic), 688 extract_leading_order() (sympy.core.add.Add
ExprCondPair (class in method), 165
sympy.functions.elementary.piecewise),extract_multiplicatively()
471 (sympy.core.expr.Expr method),
express() (in module 127
sympy.physics.vector.functions), extract_type_tens() (in module
1620 sympy.physics.hep.gamma_matrices),
express() (in module sympy.vector), 1882 1556
express() (sympy.physics.vector.dyadic.Dyadic ExtraneousFactors (class in
method), 1605 sympy.polys.polyerrors), 1026
express() (sympy.physics.vector.vector.Vector eye() (in module sympy.matrices.dense), 779
method), 1601
ExpressionDomain (class in F
sympy.polys.domains), 943 F (in module sympy.physics.secondquant),
ExpressionDomain.Expression (class in 1527
sympy.polys.domains), 943

Index 1985
SymPy Documentation, Release 1.3

F2PyCodeWrapper (class in fdiff() (sympy.codegen.cfunctions.exp2

sympy.utilities.autowrap), 1433 method), 430
faces (sympy.combinatorics.polyhedron.Polyhedronfdiff() (sympy.codegen.cfunctions.expm1
attribute), 268 method), 431
factor() (in module sympy.polys.polytools), fdiff() (sympy.codegen.cfunctions.fma
842 method), 431
factor() (sympy.core.expr.Expr method), 128 fdiff() (sympy.codegen.cfunctions.hypot
factor_list() (in module method), 431
sympy.polys.polytools), 842 fdiff() (sympy.codegen.cfunctions.log10
factor_list() (sympy.polys.polyclasses.DMP method), 432
method), 946 fdiff() (sympy.codegen.cfunctions.log1p
factor_list() (sympy.polys.polytools.Poly method), 432
method), 860 fdiff() (sympy.codegen.cfunctions.log2
factor_list_include() method), 433
(sympy.polys.polyclasses.DMP fdiff() (sympy.codegen.cfunctions.Sqrt
method), 946 method), 430
factor_list_include() fdiff() (sympy.core.function.Function
(sympy.polys.polytools.Poly method), method), 190
861 fdiff() (sympy.functions.elementary.complexes.Abs
factor_terms() (in module method), 450
sympy.core.exprtools), 207 fdiff() (sympy.functions.special.delta_functions.DiracDelta
factorial (class in method), 500
sympy.functions.combinatorial.factorials),
fdiff() (sympy.functions.special.delta_functions.Heaviside
485 method), 502
factorial() (sympy.polys.domains.FractionField fdiff() (sympy.functions.special.singularity_functions.Singula
method), 941 method), 504
factorial() (sympy.polys.domains.PolynomialRing FDistribution() (in module sympy.stats), 1233
method), 939 fft() (in module sympy.discrete.transforms),
factorial2 (class in 382
sympy.functions.combinatorial.factorials),
fglm() (sympy.polys.polytools.GroebnerBasis
487 method), 887
factorial_notation() (in module fibonacci (class in
sympy.parsing.sympy_parser), 1499 sympy.functions.combinatorial.numbers),
factoring_visitor() (in module 488
sympy.utilities.enumerative), 1452 Field (class in sympy.polys.domains.field),
factorint() (in module sympy.ntheory.factor_), 934
319 field_isomorphism() (in module
factors() (sympy.core.numbers.Rational sympy.polys.numberfields), 893
method), 147 fill() (sympy.matrices.dense.MutableDenseMatrix
FallingFactorial (class in method), 789
sympy.functions.combinatorial.factorials),
fill() (sympy.matrices.sparse.MutableSparseMatrix
488 method), 798
FBra (in module sympy.physics.secondquant), filldedent() (in module sympy.utilities.misc),
1527 1482
fcode() (in module sympy.printing.fcode), filter_symbols() (in module
1057 sympy.utilities.iterables), 1459
FCodeGen (class in sympy.utilities.codegen), find() (sympy.core.basic.Basic method), 105
1442 find_DN() (in module
FCodePrinter (class in sympy.printing.fcode), sympy.solvers.diophantine), 1360
1059 find_dynamicsymbols() (in module
Fd (in module sympy.physics.secondquant), sympy.physics.mechanics), 1704
1527 find_executable() (in module
fdiff() (sympy.codegen.cfunctions.Cbrt sympy.utilities.misc), 1483
method), 430 find_linear_recurrence()

1986 Index
 SymPy Documentation, Release 1.3

(sympy.series.sequences.SeqBase FockStateKet (class in

method), 1145 sympy.physics.secondquant), 1526
finite, 99 focus_distance (sympy.geometry.ellipse.Ellipse
finite (sympy.assumptions.ask.AssumptionKeys attribute), 640
attribute), 1107 For (class in sympy.codegen.ast), 420
finite_diff_weights() (in module forcing (sympy.physics.mechanics.kane.KanesMethod
sympy.calculus.finite_diff), 1508 attribute), 1693
FiniteDomain (class in sympy.stats.frv), 1260 forcing (sympy.physics.mechanics.lagrange.LagrangesMeth
FiniteField (class in sympy.polys.domains), attribute), 1696
937 forcing_full (sympy.physics.mechanics.kane.KanesMethod
FinitePSpace (class in sympy.stats.frv), 1260 attribute), 1693
FiniteRV() (in module sympy.stats), 1223 forcing_full (sympy.physics.mechanics.lagrange.LagrangesM
FiniteSet (class in sympy.sets.sets), 1171 attribute), 1696
FisherZ() (in module sympy.stats), 1234 form_lagranges_equations()
FixedBosonicBasis (class in (sympy.physics.mechanics.lagrange.LagrangesMeth
sympy.physics.secondquant), 1528 method), 1696
FKet (in module sympy.physics.secondquant), FormalPowerSeries (class in
1527 sympy.series.formal), 1153
FlagError (class in sympy.polys.polyerrors), FortranReturn (class in
1027 sympy.codegen.fnodes), 435
FlatMirror (class in fourier_series() (in module
sympy.physics.optics.gaussopt), sympy.series.fourier), 1152
1768 fourier_series() (sympy.core.expr.Expr
FlatRefraction (class in method), 128
sympy.physics.optics.gaussopt), fourier_transform() (in module
1767 sympy.integrals.transforms), 693
flatten() (in module sympy.utilities.iterables), FourierSeries (class in sympy.series.fourier),
1459 1150
flatten() (sympy.categories.CompositeMorphismfps() (in module sympy.series.formal), 1154
method), 1818 fps() (sympy.core.expr.Expr method), 128
flatten() (sympy.core.add.Add class method), frac (class in sympy.functions.elementary.integers),
165 469
flatten() (sympy.core.mul.Mul class method), frac (in module sympy.printing.pretty.pretty_symbology),
161 1084
Float (class in sympy.core.numbers), 143 frac_field() (sympy.polys.domains.domain.Domain
FloatBaseType (class in sympy.codegen.ast), method), 931
418 frac_unify() (sympy.polys.polyclasses.DMF
FloatType (class in sympy.codegen.ast), 418 method), 950
floor (class in sympy.functions.elementary.integers),
fraction() (in module sympy.simplify.radsimp),
468 1198
fma (class in sympy.codegen.cfunctions), 431 FractionField (class in sympy.polys.domains),
foci (sympy.geometry.ellipse.Ellipse at- 941
tribute), 639 Frechet() (in module sympy.stats), 1235
FockSpace (class in free_module() (sympy.polys.domains.ring.Ring
sympy.physics.quantum.hilbert), method), 936
1719 free_symbols (sympy.core.basic.Basic at-
FockState (class in tribute), 105
sympy.physics.secondquant), 1526 free_symbols (sympy.geometry.curve.Curve
FockStateBosonBra (class in attribute), 632
sympy.physics.secondquant), 1526 free_symbols (sympy.integrals.Integral at-
FockStateBosonKet (class in tribute), 716
sympy.physics.secondquant), 1526 free_symbols (sympy.physics.quantum.operator.DifferentialO
FockStateBra (class in attribute), 1724
sympy.physics.secondquant), 1526 free_symbols (sympy.physics.units.quantities.Quantity

Index 1987
SymPy Documentation, Release 1.3

attribute), 1554 method), 932

free_symbols (sympy.polys.polytools.Poly at- from_ExpressionDomain()
tribute), 861 (sympy.polys.domains.ExpressionDomain
free_symbols (sympy.polys.polytools.PurePoly method), 943
attribute), 887 from_FF_gmpy() (sympy.polys.domains.domain.Domain
free_symbols (sympy.series.sequences.SeqBase method), 932
attribute), 1146 from_FF_gmpy() (sympy.polys.domains.FiniteField
free_symbols() (sympy.physics.vector.vector.Vector method), 937
method), 1602 from_FF_python() (sympy.polys.domains.domain.Domain
free_symbols_in_domain method), 932
(sympy.polys.polytools.Poly at- from_FF_python() (sympy.polys.domains.FiniteField
tribute), 861 method), 937
FreeModule (class in from_FractionField()
sympy.polys.agca.modules), 913 (sympy.polys.domains.domain.Domain
FreeSpace (class in method), 932
sympy.physics.optics.gaussopt), from_FractionField()
1766 (sympy.polys.domains.ExpressionDomain
frequency (sympy.physics.optics.waves.TWave method), 943
attribute), 1783 from_FractionField()
fresnelc (class in sympy.functions.special.error_functions),
(sympy.polys.domains.FractionField
522 method), 941
FresnelIntegral (class in from_FractionField()
sympy.functions.special.error_functions), (sympy.polys.domains.PolynomialRing
521 method), 939
fresnels (class in sympy.functions.special.error_functions),
from_GlobalPolynomialRing()
521 (sympy.polys.domains.domain.Domain
from_AlgebraicField() method), 932
(sympy.polys.domains.domain.Domain from_hyper() (in module
method), 932 sympy.holonomic.holonomic), 687
from_AlgebraicField() from_index_summation()
(sympy.polys.domains.FractionField (sympy.matrices.expressions.MatrixExpr
method), 941 static method), 805
from_AlgebraicField() from_inversion_vector()
(sympy.polys.domains.IntegerRing (sympy.combinatorics.permutations.Permutation
method), 938 class method), 222
from_AlgebraicField() from_list() (sympy.polys.polyclasses.DMP
(sympy.polys.domains.PolynomialRing class method), 946
method), 939 from_list() (sympy.polys.polytools.Poly class
from_AlgebraicField() method), 862
(sympy.polys.domains.RationalField from_meijerg() (in module
method), 940 sympy.holonomic.holonomic), 687
from_ComplexField() from_poly() (sympy.polys.polytools.Poly class
(sympy.polys.domains.domain.Domain method), 862
method), 932 from_PolynomialRing()
from_dict() (sympy.polys.polyclasses.DMP (sympy.polys.domains.domain.Domain
class method), 946 method), 932
from_dict() (sympy.polys.polytools.Poly class from_PolynomialRing()
method), 862 (sympy.polys.domains.ExpressionDomain
from_expr() (sympy.codegen.ast.Type class method), 943
method), 426 from_PolynomialRing()
from_expr() (sympy.polys.polytools.Poly class (sympy.polys.domains.FractionField
method), 862 method), 941
from_ExpressionDomain() from_PolynomialRing()
(sympy.polys.domains.domain.Domain (sympy.polys.domains.PolynomialRing

1988 Index
 SymPy Documentation, Release 1.3

method), 939 method), 939

from_QQ_gmpy() (sympy.polys.domains.AlgebraicField
from_sympy() (sympy.polys.domains.RealField
method), 940 method), 942
from_QQ_gmpy() (sympy.polys.domains.domain.Domain
from_sympy_list() (sympy.polys.polyclasses.DMP
method), 932 class method), 946
from_QQ_gmpy() (sympy.polys.domains.ExpressionDomain
from_ZZ_gmpy() (sympy.polys.domains.AlgebraicField
method), 943 method), 940
from_QQ_gmpy() (sympy.polys.domains.FiniteFieldfrom_ZZ_gmpy() (sympy.polys.domains.domain.Domain
method), 938 method), 932
from_QQ_gmpy() (sympy.polys.domains.FractionField
from_ZZ_gmpy() (sympy.polys.domains.ExpressionDomain
method), 941 method), 943
from_QQ_gmpy() (sympy.polys.domains.PolynomialRing
from_ZZ_gmpy() (sympy.polys.domains.FiniteField
method), 939 method), 938
from_QQ_python() (sympy.polys.domains.AlgebraicField
from_ZZ_gmpy() (sympy.polys.domains.FractionField
method), 940 method), 942
from_QQ_python() (sympy.polys.domains.domain.Domain
from_ZZ_gmpy() (sympy.polys.domains.PolynomialRing
method), 932 method), 939
from_QQ_python() (sympy.polys.domains.ExpressionDomain
from_ZZ_python() (sympy.polys.domains.AlgebraicField
method), 943 method), 940
from_QQ_python() (sympy.polys.domains.FiniteField
from_ZZ_python() (sympy.polys.domains.domain.Domain
method), 938 method), 932
from_QQ_python() (sympy.polys.domains.FractionField
from_ZZ_python() (sympy.polys.domains.ExpressionDomain
method), 941 method), 943
from_QQ_python() (sympy.polys.domains.PolynomialRing
from_ZZ_python() (sympy.polys.domains.FiniteField
method), 939 method), 938
from_real() (sympy.sets.fancysets.ComplexRegionfrom_ZZ_python() (sympy.polys.domains.FractionField
class method), 1183 method), 942
from_RealField() (sympy.polys.domains.AlgebraicField
from_ZZ_python() (sympy.polys.domains.PolynomialRing
method), 940 method), 939
from_RealField() (sympy.polys.domains.domain.Domain
fromiter() (sympy.core.basic.Basic class
method), 932 method), 105
from_RealField() (sympy.polys.domains.ExpressionDomain
full_cyclic_form (sympy.combinatorics.permutations.Permut
method), 943 attribute), 222
from_RealField() (sympy.polys.domains.FiniteField
fullrank (sympy.assumptions.ask.AssumptionKeys
method), 938 attribute), 1108
from_RealField() (sympy.polys.domains.FractionField
fun_eval() (sympy.tensor.tensor.TensAdd
method), 941 method), 1426
from_RealField() (sympy.polys.domains.PolynomialRing
fun_eval() (sympy.tensor.tensor.TensExpr
method), 939 method), 1424
from_rgs() (sympy.combinatorics.partitions.Partition
func (sympy.core.basic.Basic attribute), 105
class method), 209 func_field_modgcd() (in module
from_sequence() (sympy.combinatorics.permutations.Permutation
sympy.polys.modulargcd), 1030
class method), 222 func_name() (in module sympy.utilities.misc),
from_sympy() (sympy.polys.domains.AlgebraicField 1483
method), 940 Function (class in sympy.core.function), 189
from_sympy() (sympy.polys.domains.domain.Domainfunction (sympy.physics.quantum.operator.DifferentialOpera
method), 932 attribute), 1724
from_sympy() (sympy.polys.domains.ExpressionDomain
function_exponentiation() (in module
method), 943 sympy.parsing.sympy_parser), 1498
from_sympy() (sympy.polys.domains.FiniteFieldFunctionCall (class in sympy.codegen.ast),
method), 938 420
from_sympy() (sympy.polys.domains.FractionFieldFunctionClass (class in sympy.core.function),
method), 942 188
from_sympy() (sympy.polys.domains.PolynomialRing
FunctionDefinition (class in

Index 1989
SymPy Documentation, Release 1.3

sympy.codegen.ast), 421 gaussian_conj() (in module

FunctionMatrix (class in sympy.physics.optics.gaussopt),
sympy.matrices.expressions), 808 1774
FunctionPrototype (class in gaussian_reduce() (in module
sympy.codegen.ast), 421 sympy.solvers.diophantine), 1370
functions (sympy.geometry.curve.Curve at- gcd() (in module sympy.polys.polytools), 837
tribute), 632 gcd() (sympy.core.numbers.Number method),
fwht() (in module sympy.discrete.transforms), 143
385 gcd() (sympy.polys.domains.domain.Domain
method), 932
G gcd() (sympy.polys.domains.field.Field
G() (in module sympy.printing.pretty.pretty_symbology),method), 934
1083 gcd() (sympy.polys.domains.PolynomialRing
g() (in module sympy.printing.pretty.pretty_symbology), method), 939
1083 gcd() (sympy.polys.domains.RealField
method), 942
gamma (class in sympy.functions.special.gamma_functions),
505 gcd() (sympy.polys.polyclasses.DMP method),
Gamma() (in module sympy.stats), 1235 946
gamma_trace() (in module gcd() (sympy.polys.polytools.Poly method),
sympy.physics.hep.gamma_matrices), 862
1556 gcd_list() (in module sympy.polys.polytools),
GammaInverse() (in module sympy.stats), 838
1236 gcd_terms() (in module
gammasimp() (sympy.core.expr.Expr sympy.core.exprtools), 206
method), 128 gcdex() (in module sympy.polys.polytools),
Gate (class in sympy.physics.quantum.gate), 832
1751 gcdex() (sympy.polys.domains.domain.Domain
gate (sympy.physics.quantum.gate.CGate at- method), 932
tribute), 1752 gcdex() (sympy.polys.domains.PolynomialRing
gate (sympy.physics.quantum.gate.CNotGate method), 939
attribute), 1754 gcdex() (sympy.polys.polyclasses.DMP
gate_simp() (in module method), 946
sympy.physics.quantum.gate), 1755 gcdex() (sympy.polys.polytools.Poly method),
gate_sort() (in module 862
sympy.physics.quantum.gate), 1755 Ge (in module sympy.core.relational), 167
gaunt() (in module sympy.physics.wigner), gegenbauer (class in
1539 sympy.functions.special.polynomials),
gauss_chebyshev_t() (in module 565
sympy.integrals.quadrature), 722 gegenbauer_poly() (in module
gauss_chebyshev_u() (in module sympy.polys.orthopolys), 899
sympy.integrals.quadrature), 723 gen (sympy.polys.polytools.Poly attribute),
gauss_gen_laguerre() (in module 862
sympy.integrals.quadrature), 721 gen (sympy.series.sequences.SeqBase at-
gauss_hermite() (in module tribute), 1146
sympy.integrals.quadrature), 720 generate() (sympy.combinatorics.perm_groups.PermutationG
gauss_jacobi() (in module method), 248
sympy.integrals.quadrature), 724 generate_bell() (in module
gauss_jordan_solve() sympy.utilities.iterables), 1460
(sympy.matrices.matrices.MatrixBase generate_derangements() (in module
method), 770 sympy.utilities.iterables), 1461
gauss_laguerre() (in module generate_dimino() (sympy.combinatorics.perm_groups.Perm
sympy.integrals.quadrature), 719 method), 249
gauss_legendre() (in module generate_gray() (sympy.combinatorics.graycode.GrayCode
sympy.integrals.quadrature), 719 method), 282

1990 Index
 SymPy Documentation, Release 1.3

generate_involutions() (in module sympy.utilities.codegen), 1439

sympy.utilities.iterables), 1461 get_domain() (sympy.polys.polytools.Poly
generate_oriented_forest() (in module method), 863
sympy.utilities.iterables), 1461 get_exact() (sympy.polys.domains.domain.Domain
generate_schreier_sims() method), 932
(sympy.combinatorics.perm_groups.PermutationGroup
get_exact() (sympy.polys.domains.RealField
method), 250 method), 942
generator_product() get_field() (sympy.polys.domains.domain.Domain
(sympy.combinatorics.perm_groups.PermutationGroup
method), 932
method), 250 get_field() (sympy.polys.domains.ExpressionDomain
generators (sympy.combinatorics.perm_groups.PermutationGroup
method), 943
attribute), 250 get_field() (sympy.polys.domains.field.Field
generators() (sympy.liealgebras.weyl_group.WeylGroupmethod), 935
method), 740 get_field() (sympy.polys.domains.FiniteField
GeneratorsError (class in method), 938
sympy.polys.polyerrors), 1026 get_field() (sympy.polys.domains.IntegerRing
GeneratorsNeeded (class in method), 938
sympy.polys.polyerrors), 1026 get_field() (sympy.polys.domains.PolynomialRing
genocchi (class in method), 939
sympy.functions.combinatorial.numbers), get_free_indices() (sympy.tensor.tensor.TensMul
493 method), 1429
Geometric() (in module sympy.stats), 1223 get_indices() (in module
geometric_conj_ab() (in module sympy.tensor.index_methods), 1414
sympy.physics.optics.gaussopt), get_indices() (sympy.tensor.tensor.TensMul
1773 method), 1429
geometric_conj_af() (in module get_interface() (sympy.utilities.codegen.FCodeGen
sympy.physics.optics.gaussopt), method), 1443
1773 get_matrix() (sympy.tensor.tensor.TensExpr
geometric_conj_bf() (in module method), 1424
sympy.physics.optics.gaussopt), get_mod_func() (in module
1774 sympy.utilities.source), 1495
GeometricRay (class in get_modulus() (sympy.polys.polytools.Poly
sympy.physics.optics.gaussopt), method), 863
1769 get_motion_params() (in module
GeometryEntity (class in sympy.physics.vector.functions),
sympy.geometry.entity), 584 1613
get() (sympy.core.containers.Dict method), get_period() (sympy.functions.special.hyper.meijerg
204 method), 557
get_adjacency_distance() get_permuted() (sympy.physics.secondquant.PermutationOp
(sympy.combinatorics.permutations.Permutation method), 1537
method), 222 get_positional_distance()
get_adjacency_matrix() (sympy.combinatorics.permutations.Permutation
(sympy.combinatorics.permutations.Permutation method), 223
method), 223 get_precedence_distance()
get_basis() (in module (sympy.combinatorics.permutations.Permutation
sympy.physics.quantum.represent), method), 224
1730 get_precedence_matrix()
get_class() (in module sympy.utilities.source), (sympy.combinatorics.permutations.Permutation
1495 method), 224
get_comm() (sympy.tensor.tensor._TensorManager get_prototype() (sympy.utilities.codegen.CCodeGen
method), 1416 method), 1442
get_contraction_structure() (in module get_prototype() (sympy.utilities.codegen.RustCodeGen
sympy.tensor.index_methods), 1412 method), 1445
get_default_datatype() (in module get_resource() (in module

Index 1991
SymPy Documentation, Release 1.3

sympy.utilities.pkgdata), 1485 982

get_ring() (sympy.polys.domains.AlgebraicFieldgf_csolve() (in module
method), 941 sympy.polys.galoistools), 997
get_ring() (sympy.polys.domains.domain.Domain gf_degree() (in module
method), 932 sympy.polys.galoistools), 982
get_ring() (sympy.polys.domains.ExpressionDomain
gf_diff() (in module sympy.polys.galoistools),
method), 943 991
get_ring() (sympy.polys.domains.field.Field gf_div() (in module sympy.polys.galoistools),
method), 935 987
get_ring() (sympy.polys.domains.FractionField gf_eval() (in module sympy.polys.galoistools),
method), 942 991
get_ring() (sympy.polys.domains.RealField gf_expand() (in module
method), 942 sympy.polys.galoistools), 987
get_ring() (sympy.polys.domains.ring.Ring gf_exquo() (in module
method), 936 sympy.polys.galoistools), 988
get_segments() (sympy.plotting.plot.LineOver1DRangeSeries
gf_factor() (in module
method), 1100 sympy.polys.galoistools), 996
get_segments() (sympy.plotting.plot.Parametric2DLineSeries
gf_factor_sqf() (in module
method), 1100 sympy.polys.galoistools), 996
get_subNO() (sympy.physics.secondquant.NO gf_from_dict() (in module
method), 1532 sympy.polys.galoistools), 984
get_subset_from_bitstring() gf_from_int_poly() (in module
(sympy.combinatorics.graycode sympy.polys.galoistools), 984
method), 285 gf_gcd() (in module sympy.polys.galoistools),
get_symmetric_group_sgs() (in module 990
sympy.combinatorics.tensor_can), gf_gcdex() (in module
300 sympy.polys.galoistools), 990
get_sympy_dir() (in module gf_int() (in module sympy.polys.galoistools),
sympy.utilities.runtests), 1490 982
get_target_matrix() (sympy.physics.quantum.gate.Gate
gf_irreducible() (in module
method), 1751 sympy.polys.galoistools), 993
get_target_matrix() (sympy.physics.quantum.gate.UGate
gf_irreducible_p() (in module
method), 1752 sympy.polys.galoistools), 993
getn() (sympy.core.expr.Expr method), 128 gf_LC() (in module sympy.polys.galoistools),
getO() (sympy.core.expr.Expr method), 128 982
gf_add() (in module sympy.polys.galoistools), gf_lcm() (in module sympy.polys.galoistools),
986 990
gf_add_ground() (in module gf_lshift() (in module
sympy.polys.galoistools), 985 sympy.polys.galoistools), 989
gf_add_mul() (in module gf_monic() (in module
sympy.polys.galoistools), 987 sympy.polys.galoistools), 991
gf_berlekamp() (in module gf_mul() (in module sympy.polys.galoistools),
sympy.polys.galoistools), 995 986
gf_cofactors() (in module gf_mul_ground() (in module
sympy.polys.galoistools), 990 sympy.polys.galoistools), 985
gf_compose() (in module gf_multi_eval() (in module
sympy.polys.galoistools), 992 sympy.polys.galoistools), 992
gf_compose_mod() (in module gf_neg() (in module sympy.polys.galoistools),
sympy.polys.galoistools), 992 984
gf_crt() (in module sympy.polys.galoistools), gf_normal() (in module
981 sympy.polys.galoistools), 983
gf_crt1() (in module sympy.polys.galoistools), gf_pow() (in module sympy.polys.galoistools),
981 989
gf_crt2() (in module sympy.polys.galoistools), gf_pow_mod() (in module

1992 Index
 SymPy Documentation, Release 1.3

sympy.polys.galoistools), 989 given() (in module sympy.stats), 1255

gf_Qbasis() (in module gm_private_key() (in module
sympy.polys.galoistools), 995 sympy.crypto.crypto), 367
gf_Qmatrix() (in module gm_public_key() (in module
sympy.polys.galoistools), 995 sympy.crypto.crypto), 367
gf_quo() (in module sympy.polys.galoistools), GMPYFiniteField (class in
988 sympy.polys.domains), 944
gf_quo_ground() (in module GMPYIntegerRing (class in
sympy.polys.galoistools), 985 sympy.polys.domains), 944
gf_random() (in module GMPYRationalField (class in
sympy.polys.galoistools), 993 sympy.polys.domains), 944
gf_rem() (in module sympy.polys.galoistools), GoldenRatio (class in sympy.core.numbers),
988 156
gf_rshift() (in module gosper_normal() (in module
sympy.polys.galoistools), 989 sympy.concrete.gosper), 380
gf_shoup() (in module gosper_sum() (in module
sympy.polys.galoistools), 996 sympy.concrete.gosper), 381
gf_sqf_list() (in module gosper_term() (in module
sympy.polys.galoistools), 994 sympy.concrete.gosper), 381
gf_sqf_p() (in module goto (class in sympy.codegen.cnodes), 433
sympy.polys.galoistools), 994 GoTo (class in sympy.codegen.fnodes), 435
gf_sqf_part() (in module gouy (sympy.physics.optics.gaussopt.BeamParameter
sympy.polys.galoistools), 994 attribute), 1771
gf_sqr() (in module sympy.polys.galoistools), GradedLexOrder (class in
986 sympy.polys.orderings), 894
gf_strip() (in module sympy.polys.galoistools), gradient() (in module
983 sympy.physics.vector.fieldfunctions),
gf_sub() (in module sympy.polys.galoistools), 1623
986 gradient() (in module sympy.vector), 1884
gf_sub_ground() (in module gradient() (sympy.vector.deloperator.Del
sympy.polys.galoistools), 985 method), 1878
gf_sub_mul() (in module GramSchmidt() (in module
sympy.polys.galoistools), 987 sympy.matrices.dense), 782
gf_TC() (in module sympy.polys.galoistools), gray_to_bin() (sympy.combinatorics.graycode
983 method), 284
gf_to_dict() (in module GrayCode (class in
sympy.polys.galoistools), 984 sympy.combinatorics.graycode),
gf_to_int_poly() (in module 281
sympy.polys.galoistools), 984 graycode_subsets() (sympy.combinatorics.graycode
gf_trace_map() (in module method), 285
sympy.polys.galoistools), 992 GreaterThan (class in sympy.core.relational),
gf_trunc() (in module 168
sympy.polys.galoistools), 983 greek_letters (in module
gf_value() (in module sympy.printing.pretty.pretty_symbology),
sympy.polys.galoistools), 997 1083
gf_zassenhaus() (in module groebner() (in module
sympy.polys.galoistools), 996 sympy.polys.groebnertools), 1024
gff() (in module sympy.polys.polytools), 841 groebner() (in module sympy.polys.polytools),
gff_list() (in module sympy.polys.polytools), 845
840 GroebnerBasis (class in
gff_list() (sympy.polys.polyclasses.DMP sympy.polys.polytools), 887
method), 946 ground_roots() (in module
gff_list() (sympy.polys.polytools.Poly method), sympy.polys.polytools), 844
863 ground_roots() (sympy.polys.polytools.Poly

Index 1993
SymPy Documentation, Release 1.3

method), 863 Heaviside (class in

group() (in module sympy.utilities.iterables), sympy.functions.special.delta_functions),
1462 501
group_name() (sympy.liealgebras.weyl_group.WeylGroup
height (sympy.categories.diagram_drawing.DiagramGrid
method), 740 attribute), 1825
group_order() (sympy.liealgebras.weyl_group.WeylGroup
height (sympy.physics.optics.gaussopt.GeometricRay
method), 740 attribute), 1770
grover_iteration() (in module height() (sympy.polys.agca.ideals.Ideal
sympy.physics.quantum.grover), method), 920
1757 height() (sympy.printing.pretty.stringpict.stringPict
gruntz() (in module sympy.series.gruntz), method), 1085
1138 hermite (class in sympy.functions.special.polynomials),
Gt (in module sympy.core.relational), 167 570
hermite_poly() (in module
H sympy.polys.orthopolys), 900
H (in module sympy.physics.quantum.gate), hermitian, 100
1754 hermitian (sympy.assumptions.ask.AssumptionKeys
HadamardGate (class in attribute), 1108
sympy.physics.quantum.gate), 1752 HermitianOperator (class in
Half (class in sympy.core.numbers), 150 sympy.physics.quantum.operator),
half_gcdex() (in module 1721
sympy.polys.polytools), 832 hessian() (in module sympy.matrices.dense),
half_gcdex() (sympy.polys.domains.domain.Domain 781
method), 932 HeuristicGCDFailed (class in
half_gcdex() (sympy.polys.polyclasses.DMP sympy.polys.polyerrors), 1026
method), 946 highest_root() (sympy.liealgebras.type_a.TypeA
half_gcdex() (sympy.polys.polytools.Poly method), 730
method), 863 HilbertSpace (class in
half_per() (sympy.polys.polyclasses.DMF sympy.physics.quantum.hilbert),
method), 950 1718
hobj()
hankel1 (class in sympy.functions.special.bessel), (in module
537 sympy.printing.pretty.pretty_symbology),
hankel2 (class in sympy.functions.special.bessel), 1084
537 holzer() (in module
hankel_transform() (in module sympy.solvers.diophantine), 1370
sympy.integrals.transforms), 695 hom() (sympy.categories.Diagram method),
harmonic (class in 1821
sympy.functions.combinatorial.numbers), homogeneous_order() (in module
490 sympy.solvers.ode), 1267
has() (sympy.core.basic.Basic method), 106 homogeneous_order()
has_dups() (in module (sympy.polys.polyclasses.DMP
sympy.utilities.iterables), 1462 method), 947
has_integer_powers() homogeneous_order()
(sympy.physics.units.dimensions.Dimension (sympy.polys.polytools.Poly method),
method), 1551 864
has_only_gens() (sympy.polys.polytools.Poly homogenize() (sympy.polys.polyclasses.DMP
method), 864 method), 947
has_q_annihilators (sympy.physics.secondquant.NOhomogenize() (sympy.polys.polytools.Poly
attribute), 1532 method), 864
has_q_creators (sympy.physics.secondquant.NOhomomorphism() (in module
attribute), 1533 sympy.polys.agca.homomorphisms),
has_variety() (in module 925
sympy.utilities.iterables), 1462 HomomorphismFailed (class in
sympy.polys.polyerrors), 1026

1994 Index
 SymPy Documentation, Release 1.3

horner() (in module sympy.polys.polyfuncs), Idx (class in sympy.tensor.indexed), 1407

889 ifft() (in module sympy.discrete.transforms),
hradius (sympy.geometry.ellipse.Ellipse at- 383
tribute), 640 ifwht() (in module
hyper (class in sympy.functions.special.hyper), sympy.discrete.transforms), 385
552 igcd() (in module sympy.core.numbers), 148
hyper_algorithm() (in module ilcm() (in module sympy.core.numbers), 149
sympy.series.formal), 1160 im (class in sympy.functions.elementary.complexes),
hyper_re() (in module sympy.series.formal), 448
1158 image() (sympy.polys.agca.homomorphisms.ModuleHomomo
HyperbolicFunction (class in method), 926
sympy.functions.elementary.hyperbolic),ImageSet (class in sympy.sets.fancysets),
463 1179
hyperexpand() (in module imageset() (in module sympy.sets.sets), 1168
sympy.simplify.hyperexpand), 1207 imaginary, 99
hyperfocal_distance() (in module imaginary (sympy.assumptions.ask.AssumptionKeys
sympy.physics.optics.utils), 1781 attribute), 1108
Hypergeometric() (in module sympy.stats), ImaginaryUnit (class in
1223 sympy.core.numbers), 154
hypersimilar() (in module ImmutableDenseMatrix (class in
sympy.simplify.simplify), 1190 sympy.matrices.immutable), 802
hypersimp() (in module ImmutableDenseNDimArray (class in
sympy.simplify.simplify), 1189 sympy.tensor.array), 1403
hypot (class in sympy.codegen.cfunctions), ImmutableSparseMatrix (class in
431 sympy.matrices.immutable), 801
ImmutableSparseNDimArray (class in
I sympy.tensor.array), 1403
ibin() (in module sympy.utilities.iterables), implemented_function() (in module
1463 sympy.utilities.lambdify), 1478
Ideal (class in sympy.polys.agca.ideals), 919 implicit_application() (in module
ideal() (sympy.polys.domains.ring.Ring sympy.parsing.sympy_parser), 1498
method), 936 implicit_multiplication() (in module
Identity (class in sympy.matrices.expressions), sympy.parsing.sympy_parser), 1498
808 implicit_multiplication_application() (in mod-
ule
identity (sympy.combinatorics.perm_groups.PermutationGroup sympy.parsing.sympy_parser),
attribute), 250 1499
ImplicitSeries
identity_hom() (sympy.polys.agca.modules.FreeModule (class in
method), 914 sympy.plotting.plot_implicit), 1101
identity_hom() (sympy.polys.agca.modules.Module ImpliedDoLoop (class in
method), 913 sympy.codegen.fnodes), 436
Implies (class in sympy.logic.boolalg), 748
identity_hom() (sympy.polys.agca.modules.QuotientModule
method), 922 imul_num() (sympy.polys.rings.PolyElement
identity_hom() (sympy.polys.agca.modules.SubModule method), 1003
method), 915 in_terms_of_generators()
IdentityFunction (class in (sympy.polys.agca.modules.SubModule
sympy.functions.elementary.miscellaneous), method), 915
472 incenter (sympy.geometry.polygon.Triangle
IdentityGate (class in attribute), 668
sympy.physics.quantum.gate), 1752 incircle (sympy.geometry.polygon.RegularPolygon
IdentityMorphism (class in attribute), 661
sympy.categories), 1818 incircle (sympy.geometry.polygon.Triangle
IdentityOperator (class in attribute), 668
sympy.physics.quantum.operator), inclusion_hom() (sympy.polys.agca.modules.SubModule
1721 method), 916

Index 1995
SymPy Documentation, Release 1.3

indent_code() (sympy.printing.ccode.C89CodePrinter
init_printing() (in module
method), 1051 sympy.physics.vector.printing), 1614
indent_code() (sympy.printing.fcode.FCodePrinterinject() (sympy.polys.domains.compositedomain.CompositeD
method), 1059 method), 937
indent_code() (sympy.printing.jscode.JavascriptCodePrinter
inject() (sympy.polys.domains.domain.Domain
method), 1062 method), 932
indent_code() (sympy.printing.julia.JuliaCodePrinter
inject() (sympy.polys.domains.simpledomain.SimpleDomain
method), 1064 method), 937
indent_code() (sympy.printing.octave.OctaveCodePrinter
inject() (sympy.polys.polyclasses.DMP
method), 1067 method), 947
indent_code() (sympy.printing.rcode.RCodePrinterinject() (sympy.polys.polytools.Poly method),
method), 1055 865
indent_code() (sympy.printing.rust.RustCodePrinter
InnerProduct (class in
method), 1069 sympy.physics.quantum.innerproduct),
index() (sympy.combinatorics.permutations.Permutation1714
method), 224 InnerProduct (class in
index() (sympy.core.containers.Tuple sympy.physics.secondquant), 1527
method), 203 inradius (sympy.geometry.polygon.RegularPolygon
index() (sympy.physics.secondquant.FixedBosonicBasis attribute), 662
method), 1528 inradius (sympy.geometry.polygon.Triangle
index() (sympy.physics.secondquant.VarBosonicBasis attribute), 669
method), 1528 IntBaseType (class in sympy.codegen.ast),
index() (sympy.polys.rings.PolyRing method), 422
1000 intcurve_diffequ() (in module
Indexed (class in sympy.tensor.indexed), 1409 sympy.diffgeom), 1843
IndexedBase (class in sympy.tensor.indexed), intcurve_series() (in module sympy.diffgeom),
1410 1842
indices (sympy.tensor.indexed.Indexed at- integer, 99
tribute), 1409 Integer (class in sympy.core.numbers), 147
indices_contain_equal_information integer (sympy.assumptions.ask.AssumptionKeys
(sympy.functions.special.tensor_functions.KroneckerDelta
attribute), 1109
attribute), 577 integer_elements (sympy.assumptions.ask.AssumptionKeys
indices_contain_equal_information attribute), 1109
(sympy.physics.secondquant.KroneckerDelta
integer_nthroot() (in module
attribute), 1519 sympy.core.power), 160
inertia() (in module IntegerPartition (class in
sympy.physics.mechanics.functions), sympy.combinatorics.partitions),
1687 210
inertia_of_point_mass() (in module IntegerRing (class in sympy.polys.domains),
sympy.physics.mechanics.functions), 938
1687 Integers (class in sympy.sets.fancysets), 1178
inf (sympy.sets.sets.Set attribute), 1164 Integral (class in sympy.integrals), 714
infinite, 99 Integral.is_commutative (in module
infinite (sympy.assumptions.ask.AssumptionKeys sympy.integrals), 714
attribute), 1109 integrand() (sympy.functions.special.hyper.meijerg
infinite (sympy.series.formal.FormalPowerSeries method), 557
attribute), 1154 integrate() (in module sympy.integrals), 711
infinitesimal (sympy.assumptions.ask.AssumptionKeys
integrate() (sympy.core.expr.Expr method),
attribute), 1109 128
infinitesimals() (in module integrate() (sympy.holonomic.holonomic.HolonomicFunction
sympy.solvers.ode), 1268 method), 682
Infinity (class in sympy.core.numbers), 152 integrate() (sympy.polys.polyclasses.DMP
infinity (sympy.assumptions.ask.AssumptionKeys method), 947
attribute), 1109 integrate() (sympy.polys.polytools.Poly

1996 Index
 SymPy Documentation, Release 1.3

method), 865 sympy.physics.quantum.qubit), 1759

integrate() (sympy.series.formal.FormalPowerSeries
IntQubitBra (class in
method), 1154 sympy.physics.quantum.qubit), 1760
integrate_result() (in module intrinsic_impedance
sympy.physics.quantum.represent), (sympy.physics.optics.medium.Medium
1729 attribute), 1776
interactive_traversal() (in module intt() (in module sympy.discrete.transforms),
sympy.utilities.iterables), 1463 384
interior (sympy.sets.sets.Set attribute), 1164 inv() (sympy.matrices.matrices.MatrixBase
interior_angle (sympy.geometry.polygon.RegularPolygon method), 771
attribute), 662 inv_can_transf_matrix
interpolate() (in module (sympy.physics.units.dimensions.DimensionSystem
sympy.polys.polyfuncs), 890 attribute), 1552
interpolating_poly() (in module inv_mod() (sympy.matrices.matrices.MatrixBase
sympy.polys.specialpolys), 898 method), 771
intersect() (sympy.polys.agca.ideals.Ideal Inverse (class in sympy.matrices.expressions),
method), 920 806
intersect() (sympy.polys.agca.modules.SubModule inverse_ADJ() (sympy.matrices.matrices.MatrixBase
method), 916 method), 772
intersect() (sympy.sets.sets.Set method), inverse_cosine_transform() (in module
1164 sympy.integrals.transforms), 695
intersecting_product() (in module inverse_fourier_transform() (in module
sympy.discrete.convolutions), 392 sympy.integrals.transforms), 693
Intersection (class in sympy.sets.sets), 1173 inverse_GE() (sympy.matrices.matrices.MatrixBase
intersection() (in module method), 772
sympy.geometry.util), 587 inverse_hankel_transform() (in module
intersection() (sympy.geometry.ellipse.Circle sympy.integrals.transforms), 696
method), 648 inverse_laplace_transform() (in module
intersection() (sympy.geometry.ellipse.Ellipse sympy.integrals.transforms), 692
method), 640 inverse_LU() (sympy.matrices.matrices.MatrixBase
intersection() (sympy.geometry.entity.GeometryEntity method), 772
method), 584 inverse_mellin_transform() (in module
intersection() (sympy.geometry.line.LinearEntity sympy.integrals.transforms), 691
method), 605 inverse_mobius_transform() (in module
intersection() (sympy.geometry.plane.Plane sympy.discrete.transforms), 387
method), 675 inverse_sine_transform() (in module
intersection() (sympy.geometry.point.Point sympy.integrals.transforms), 694
method), 593 inversion_vector() (sympy.combinatorics.permutations.Perm
intersection() (sympy.geometry.point.Point3D method), 225
method), 600 inversions() (sympy.combinatorics.permutations.Permutation
intersection() (sympy.geometry.polygon.Polygon method), 225
method), 654 invert() (in module sympy.polys.polytools),
intersection() (sympy.sets.sets.Set method), 832
1164 invert() (sympy.core.expr.Expr method), 128
Interval (class in sympy.sets.sets), 1169 invert() (sympy.polys.domains.domain.Domain
interval (sympy.series.sequences.SeqBase at- method), 933
tribute), 1146 invert() (sympy.polys.domains.ring.Ring
intervals() (in module sympy.polys.polytools), method), 936
843 invert() (sympy.polys.polyclasses.DMF
intervals() (sympy.polys.polyclasses.DMP method), 950
method), 947 invert() (sympy.polys.polyclasses.DMP
intervals() (sympy.polys.polytools.Poly method), 947
method), 865 invert() (sympy.polys.polytools.Poly method),
IntQubit (class in 866

Index 1997
SymPy Documentation, Release 1.3

invert_complex() (in module is_convergent() (sympy.concrete.products.Product

sympy.solvers.solveset), 1385 method), 377
invert_real() (in module is_convergent() (sympy.concrete.summations.Sum
sympy.solvers.solveset), 1385 method), 372
invertible (sympy.assumptions.ask.AssumptionKeysis_convex() (sympy.geometry.polygon.Polygon
attribute), 1110 method), 654
IQFT (class in sympy.physics.quantum.qft), is_coplanar() (sympy.geometry.plane.Plane
1758 method), 676
irrational, 99 is_cyclotomic (sympy.polys.polyclasses.DMP
irrational (sympy.assumptions.ask.AssumptionKeys attribute), 947
attribute), 1110 is_cyclotomic (sympy.polys.polytools.Poly at-
is_abelian (sympy.combinatorics.perm_groups.PermutationGroup
tribute), 866
attribute), 250 is_decreasing() (in module
is_above_fermi (sympy.functions.special.tensor_functions.KroneckerDelta
sympy.calculus.singularities), 1502
attribute), 578 is_dimensionless (sympy.physics.units.dimensions.Dimensio
is_above_fermi (sympy.physics.secondquant.KroneckerDelta attribute), 1551
attribute), 1520 is_dimensionless() (sympy.physics.units.dimensions.Dimensi
is_absolutely_convergent() method), 1552
(sympy.concrete.summations.Sum is_disjoint() (sympy.sets.sets.Set method),
method), 372 1165
is_algebraic_expr() (sympy.core.expr.Expr is_dnf() (in module sympy.logic.boolalg), 751
method), 129 is_Empty (sympy.combinatorics.permutations.Permutation
is_aliased (sympy.polys.numberfields.AlgebraicNumber attribute), 226
attribute), 893 is_equilateral() (sympy.geometry.polygon.Triangle
method), 669
is_alt_sym() (sympy.combinatorics.perm_groups.PermutationGroup
method), 251 is_even (sympy.combinatorics.permutations.Permutation
is_below_fermi (sympy.functions.special.tensor_functions.KroneckerDelta
attribute), 227
attribute), 578 is_full_module() (sympy.polys.agca.modules.SubModule
is_below_fermi (sympy.physics.secondquant.KroneckerDelta method), 916
attribute), 1520 is_full_module() (sympy.polys.agca.modules.SubQuotientMo
is_closed (sympy.sets.sets.Set attribute), method), 923
1164 is_groebner() (in module
is_cnf() (in module sympy.logic.boolalg), 751 sympy.polys.groebnertools), 1024
is_collinear() (sympy.geometry.point.Point is_ground (sympy.polys.polyclasses.ANP at-
method), 593 tribute), 951
is_commutative (sympy.core.function.Function is_ground (sympy.polys.polyclasses.DMP at-
attribute), 190 tribute), 947
is_commutative (sympy.physics.quantum.state.Wavefunction
is_ground (sympy.polys.polytools.Poly at-
attribute), 1747 tribute), 866
is_comparable (sympy.core.basic.Basic at- is_homogeneous (sympy.polys.polyclasses.DMP
tribute), 106 attribute), 947
is_concyclic() (sympy.geometry.point.Point is_homogeneous (sympy.polys.polytools.Poly
method), 593 attribute), 867
is_conservative() (in module is_Identity (sympy.combinatorics.permutations.Permutation
sympy.physics.vector.fieldfunctions), attribute), 226
1625 is_identity (sympy.core.function.Lambda at-
is_conservative() (in module sympy.vector), tribute), 182
1884 is_increasing() (in module
is_consistent (sympy.physics.units.dimensions.DimensionSystem
sympy.calculus.singularities), 1502
attribute), 1552 is_injective() (sympy.polys.agca.homomorphisms.ModuleHom
is_consistent (sympy.physics.units.unitsystem.UnitSystem method), 927
attribute), 1554 is_irreducible (sympy.polys.polyclasses.DMP
is_constant() (sympy.core.expr.Expr method), attribute), 947
129 is_irreducible (sympy.polys.polytools.Poly at-

1998 Index
 SymPy Documentation, Release 1.3

tribute), 867 method), 941

is_isomorphism() (sympy.polys.agca.homomorphisms.ModuleHomomorphism
is_nonpositive() (sympy.polys.domains.domain.Domain
method), 927 method), 933
is_isosceles() (sympy.geometry.polygon.Triangleis_nonpositive() (sympy.polys.domains.ExpressionDomain
method), 670 method), 943
is_iterable (sympy.sets.sets.ProductSet at- is_nonpositive() (sympy.polys.domains.FractionField
tribute), 1174 method), 942
is_left_unbounded (sympy.sets.sets.Interval is_nonpositive() (sympy.polys.domains.PolynomialRing
attribute), 1170 method), 939
is_linear (sympy.polys.polyclasses.DMP at- is_nonzero (sympy.geometry.point.Point at-
tribute), 947 tribute), 594
is_linear (sympy.polys.polytools.Poly at- is_normal() (sympy.combinatorics.perm_groups.Permutation
tribute), 867 method), 252
is_maximal() (sympy.polys.agca.ideals.Ideal is_normalized (sympy.physics.quantum.state.Wavefunction
method), 920 attribute), 1748
is_minimal() (in module is_nthpow_residue() (in module
sympy.polys.groebnertools), 1024 sympy.ntheory.residue_ntheory),
is_monic (sympy.polys.polyclasses.DMP at- 336
tribute), 947 is_number (sympy.core.expr.Expr attribute),
is_monic (sympy.polys.polytools.Poly at- 130
tribute), 867 is_number (sympy.functions.special.hyper.meijerg
is_monomial (sympy.polys.polyclasses.DMP attribute), 557
attribute), 947 is_odd (sympy.combinatorics.permutations.Permutation
is_monomial (sympy.polys.polytools.Poly at- attribute), 227
tribute), 868 is_one (sympy.polys.polyclasses.ANP at-
is_monotonic() (in module tribute), 951
sympy.calculus.singularities), 1503 is_one (sympy.polys.polyclasses.DMF at-
is_multivariate (sympy.polys.polytools.Poly tribute), 950
attribute), 868 is_one (sympy.polys.polyclasses.DMP at-
is_negative() (sympy.polys.domains.AlgebraicField tribute), 947
method), 941 is_one (sympy.polys.polytools.Poly attribute),
is_negative() (sympy.polys.domains.domain.Domain 868
method), 933 is_one() (sympy.polys.domains.domain.Domain
is_negative() (sympy.polys.domains.ExpressionDomain method), 933
method), 943 is_only_above_fermi
is_negative() (sympy.polys.domains.FractionField (sympy.functions.special.tensor_functions.Kronecke
method), 942 attribute), 579
is_negative() (sympy.polys.domains.PolynomialRing
is_only_above_fermi
method), 939 (sympy.physics.secondquant.KroneckerDelta
is_nilpotent (sympy.combinatorics.perm_groups.PermutationGroup
attribute), 1521
attribute), 251 is_only_below_fermi
is_nilpotent() (sympy.matrices.matrices.MatrixBase (sympy.functions.special.tensor_functions.Kronecke
method), 772 attribute), 579
is_nonnegative() (sympy.polys.domains.AlgebraicField
is_only_below_fermi
method), 941 (sympy.physics.secondquant.KroneckerDelta
is_nonnegative() (sympy.polys.domains.domain.Domain attribute), 1521
method), 933 is_only_q_annihilator
is_nonnegative() (sympy.polys.domains.ExpressionDomain (sympy.physics.secondquant.AnnihilateFermion
method), 943 attribute), 1523
is_nonnegative() (sympy.polys.domains.FractionField
is_only_q_annihilator
method), 942 (sympy.physics.secondquant.CreateFermion
is_nonnegative() (sympy.polys.domains.PolynomialRing attribute), 1525
method), 939 is_only_q_creator (sympy.physics.secondquant.AnnihilateFer
is_nonpositive() (sympy.polys.domains.AlgebraicField attribute), 1524

Index 1999
SymPy Documentation, Release 1.3

is_only_q_creator (sympy.physics.secondquant.CreateFermion
attribute), 947
attribute), 1525 is_quadratic (sympy.polys.polytools.Poly at-
is_open (sympy.sets.sets.Set attribute), 1165 tribute), 869
is_parallel() (sympy.geometry.line.LinearEntity is_radical() (sympy.polys.agca.ideals.Ideal
method), 606 method), 920
is_parallel() (sympy.geometry.plane.Plane is_rational_function() (sympy.core.expr.Expr
method), 676 method), 132
is_perpendicular() (sympy.geometry.line.LinearEntity
is_reduced() (in module
method), 607 sympy.polys.groebnertools), 1024
is_perpendicular() (sympy.geometry.plane.Planeis_right() (sympy.geometry.polygon.Triangle
method), 676 method), 670
is_polynomial() (sympy.core.expr.Expr is_right_unbounded (sympy.sets.sets.Interval
method), 131 attribute), 1170
is_positive() (sympy.polys.domains.AlgebraicField
is_scalar_multiple() (sympy.geometry.point.Point
method), 941 method), 594
is_positive() (sympy.polys.domains.domain.Domainis_scalene() (sympy.geometry.polygon.Triangle
method), 933 method), 670
is_positive() (sympy.polys.domains.ExpressionDomain
is_sequence() (in module
method), 944 sympy.core.compatibility), 205
is_positive() (sympy.polys.domains.FractionFieldis_similar() (sympy.geometry.entity.GeometryEntity
method), 942 method), 585
is_positive() (sympy.polys.domains.PolynomialRing
is_similar() (sympy.geometry.line.LinearEntity
method), 939 method), 607
is_primary() (sympy.polys.agca.ideals.Ideal is_similar() (sympy.geometry.polygon.Triangle
method), 920 method), 670
is_prime() (sympy.polys.agca.ideals.Ideal is_simple() (sympy.functions.special.delta_functions.DiracDe
method), 920 method), 500
is_primitive (sympy.polys.polyclasses.DMP is_Singleton (sympy.combinatorics.permutations.Permutatio
attribute), 947 attribute), 226
is_primitive (sympy.polys.polytools.Poly at- is_solenoidal() (in module
tribute), 869 sympy.physics.vector.fieldfunctions),
is_primitive() (sympy.combinatorics.perm_groups.PermutationGroup
1625
method), 252 is_solenoidal() (in module sympy.vector),
is_primitive_root() (in module 1885
sympy.ntheory.residue_ntheory), is_solvable (sympy.combinatorics.perm_groups.Permutation
334 attribute), 253
is_principal() (sympy.polys.agca.ideals.Ideal is_sqf (sympy.polys.polyclasses.DMP at-
method), 920 tribute), 947
is_proper_subset() (sympy.sets.sets.Set is_sqf (sympy.polys.polytools.Poly attribute),
method), 1165 869
is_proper_superset() (sympy.sets.sets.Set is_strictly_decreasing() (in module
method), 1165 sympy.calculus.singularities), 1503
is_q_annihilator (sympy.physics.secondquant.AnnihilateFermion
is_strictly_increasing() (in module
attribute), 1524 sympy.calculus.singularities), 1503
is_q_annihilator (sympy.physics.secondquant.CreateFermion
is_subdiagram() (sympy.categories.Diagram
attribute), 1525 method), 1822
is_q_creator (sympy.physics.secondquant.AnnihilateFermion
is_subgroup() (sympy.combinatorics.perm_groups.Permutati
attribute), 1524 method), 253
is_q_creator (sympy.physics.secondquant.CreateFermion
is_submodule() (sympy.polys.agca.modules.FreeModule
attribute), 1526 method), 914
is_quad_residue() (in module is_submodule() (sympy.polys.agca.modules.Module
sympy.ntheory.residue_ntheory), method), 913
336 is_submodule() (sympy.polys.agca.modules.QuotientModule
is_quadratic (sympy.polys.polyclasses.DMP method), 922

2000 Index
 SymPy Documentation, Release 1.3

is_submodule() (sympy.polys.agca.modules.SubModule
isolate() (in module
method), 916 sympy.polys.numberfields), 893
is_subset() (sympy.sets.sets.Set method), IsomorphismFailed (class in
1166 sympy.polys.polyerrors), 1026
is_superset() (sympy.sets.sets.Set method), isprime() (in module
1166 sympy.ntheory.primetest), 333
is_surjective() (sympy.polys.agca.homomorphisms.ModuleHomomorphism
issubset() (sympy.sets.sets.Set method), 1166
method), 927 issuperset() (sympy.sets.sets.Set method),
is_tangent() (sympy.geometry.ellipse.Ellipse 1166
method), 641 ITE (class in sympy.logic.boolalg), 750
is_transitive() (sympy.combinatorics.perm_groups.PermutationGroup
items() (sympy.core.containers.Dict method),
method), 254 204
is_trivial (sympy.combinatorics.perm_groups.PermutationGroup
iter_q_annihilators()
attribute), 254 (sympy.physics.secondquant.NO
is_true (sympy.assumptions.ask.AssumptionKeys method), 1533
attribute), 1110 iter_q_creators() (sympy.physics.secondquant.NO
is_univariate (sympy.polys.polytools.Poly at- method), 1533
tribute), 869 iterable() (in module
is_whole_ring() (sympy.polys.agca.ideals.Ideal sympy.core.compatibility), 204
method), 920 iterate_binary() (sympy.combinatorics.subsets.Subset
is_zero (sympy.geometry.point.Point at- method), 275
tribute), 594 iterate_graycode() (sympy.combinatorics.subsets.Subset
is_zero (sympy.matrices.immutable.ImmutableDenseMatrix method), 275
attribute), 802 itercoeffs() (sympy.polys.rings.PolyElement
is_zero (sympy.polys.polyclasses.ANP at- method), 1004
tribute), 951 itermonomials() (in module
is_zero (sympy.polys.polyclasses.DMF at- sympy.polys.monomials), 893
tribute), 950 itermonoms() (sympy.polys.rings.PolyElement
is_zero (sympy.polys.polyclasses.DMP at- method), 1004
tribute), 947 iterterms() (sympy.polys.rings.PolyElement
is_zero (sympy.polys.polytools.Poly attribute), method), 1004
870
J
is_zero() (sympy.polys.agca.homomorphisms.ModuleHomomorphism
method), 928 jacobi (class in sympy.functions.special.polynomials),
is_zero() (sympy.polys.agca.ideals.Ideal 563
method), 920 jacobi_normalized() (in module
is_zero() (sympy.polys.agca.modules.FreeModule sympy.functions.special.polynomials),
method), 914 564
is_zero() (sympy.polys.agca.modules.Module jacobi_poly() (in module
method), 913 sympy.polys.orthopolys), 900
is_zero() (sympy.polys.agca.modules.QuotientModule
jacobi_symbol() (in module
method), 922 sympy.ntheory.residue_ntheory),
is_zero() (sympy.polys.agca.modules.SubModule 336
method), 917 jacobian() (sympy.diffgeom.CoordSystem
is_zero() (sympy.polys.domains.domain.Domain method), 1835
method), 933 JavascriptCodePrinter (class in
is_zero_dimensional sympy.printing.jscode), 1062
(sympy.polys.polytools.GroebnerBasis jn (class in sympy.functions.special.bessel),
attribute), 888 538
is_zero_dimensional() (in module jn_zeros() (in module
sympy.polys.polytools), 846 sympy.functions.special.bessel),
isdisjoint() (sympy.sets.sets.Set method), 539
1166 join() (sympy.physics.continuum_mechanics.beam.Beam
isign (class in sympy.codegen.fnodes), 439 method), 1789

Index 2001
SymPy Documentation, Release 1.3

jordan_cell() (in module ket (sympy.physics.secondquant.InnerProduct

sympy.matrices.dense), 781 attribute), 1527
josephus() (sympy.combinatorics.permutations.Permutation
KetBase (class in
class method), 227 sympy.physics.quantum.state), 1742
jscode() (in module sympy.printing.jscode), key2bounds() (sympy.matrices.matrices.MatrixBase
1062 method), 772
julia_code() (in module sympy.printing.julia), key2ij() (sympy.matrices.matrices.MatrixBase
1064 method), 773
JuliaCodeGen (class in keys() (sympy.core.containers.Dict method),
sympy.utilities.codegen), 1443 204
JuliaCodePrinter (class in kid_rsa_private_key() (in module
sympy.printing.julia), 1064 sympy.crypto.crypto), 358
JxBra (class in sympy.physics.quantum.spin), kid_rsa_public_key() (in module
1735 sympy.crypto.crypto), 358
JxBraCoupled (class in killable_index (sympy.functions.special.tensor_functions.Kro
sympy.physics.quantum.spin), 1737 attribute), 579
JxKet (class in sympy.physics.quantum.spin), killable_index (sympy.physics.secondquant.KroneckerDelta
1735 attribute), 1521
JxKetCoupled (class in kin_explicit_rhs (sympy.physics.mechanics.system.SymbolicS
sympy.physics.quantum.spin), 1737 attribute), 1702
JyBra (class in sympy.physics.quantum.spin), kind (class in sympy.codegen.fnodes), 439
1735 kindiffdict() (sympy.physics.mechanics.kane.KanesMethod
JyBraCoupled (class in method), 1694
sympy.physics.quantum.spin), 1738 kinematic_equations() (in module
JyKet (class in sympy.physics.quantum.spin), sympy.physics.vector.functions),
1735 1612
JyKetCoupled (class in kinetic_energy() (in module
sympy.physics.quantum.spin), 1738 sympy.physics.mechanics.functions),
JzBra (class in sympy.physics.quantum.spin), 1689
1737 kinetic_energy() (sympy.physics.mechanics.particle.Particle
JzBraCoupled (class in method), 1682
sympy.physics.quantum.spin), 1740 kinetic_energy() (sympy.physics.mechanics.rigidbody.RigidB
JzKet (class in sympy.physics.quantum.spin), method), 1685
1735 known_fcns_src1 (in module
JzKetCoupled (class in sympy.printing.julia), 1064
sympy.physics.quantum.spin), 1738 known_fcns_src1 (in module
sympy.printing.octave), 1067
K known_fcns_src2 (in module
kahane_simplify() (in module sympy.printing.julia), 1064
sympy.physics.hep.gamma_matrices), known_fcns_src2 (in module
1556 sympy.printing.octave), 1067
known_functions
kanes_equations() (sympy.physics.mechanics.kane.KanesMethod (in module
method), 1693 sympy.printing.jscode), 1062
KanesMethod (class in known_functions (in module
sympy.physics.mechanics.kane), sympy.printing.mathematica), 1061
1692 known_functions (in module
kbins() (in module sympy.utilities.iterables), sympy.printing.rcode), 1055
1464 known_functions (in module
sympy.printing.rust),
kernel() (sympy.polys.agca.homomorphisms.ModuleHomomorphism 1069
method), 928 known_functions_C89 (in module
Ket (class in sympy.physics.quantum.state), sympy.printing.ccode), 1051
1743 known_functions_C99 (in module
ket (sympy.physics.quantum.operator.OuterProduct sympy.printing.ccode), 1051
attribute), 1723 KroneckerDelta (class in

2002 Index
 SymPy Documentation, Release 1.3

sympy.functions.special.tensor_functions),
laplace_transform() (in module
576 sympy.integrals.transforms), 692
KroneckerDelta (class in latex() (in module sympy.printing.latex), 1072
sympy.physics.secondquant), 1518 LaTeXParsingError (class in
ksubsets() (sympy.combinatorics.subsets sympy.parsing.latex), 1500
method), 280 LatexPrinter (class in sympy.printing.latex),
Kumaraswamy() (in module sympy.stats), 1072
1237 lbound() (in module sympy.codegen.fnodes),
kwargs() (sympy.codegen.ast.Token method), 439
424 LC() (in module sympy.polys.polytools), 829
LC() (sympy.polys.polyclasses.ANP method),
L 951
l1_norm() (sympy.polys.polyclasses.DMP LC() (sympy.polys.polyclasses.DMP method),
method), 947 945
l1_norm() (sympy.polys.polytools.Poly LC() (sympy.polys.polytools.Poly method),
method), 870 848
L2 (class in sympy.physics.quantum.hilbert), lcm() (in module sympy.polys.polytools), 838
1718 lcm() (sympy.core.numbers.Number method),
Label (class in sympy.codegen.cnodes), 433 143
label (sympy.physics.quantum.state.TimeDepState lcm() (sympy.polys.domains.domain.Domain
attribute), 1745 method), 933
label (sympy.tensor.indexed.Idx attribute), lcm() (sympy.polys.domains.field.Field
1408 method), 935
label (sympy.tensor.indexed.IndexedBase at- lcm() (sympy.polys.domains.PolynomialRing
tribute), 1411 method), 939
labeller() (in module lcm() (sympy.polys.domains.RealField
sympy.physics.quantum.circuitplot), method), 942
1750 lcm() (sympy.polys.polyclasses.DMP method),
LagrangesMethod (class in 947
sympy.physics.mechanics.lagrange), lcm() (sympy.polys.polytools.Poly method),
1695 870
Lagrangian() (in module lcm_list() (in module sympy.polys.polytools),
sympy.physics.mechanics.functions), 838
1691 ldescent() (in module
laguerre (class in sympy.solvers.diophantine), 1369
sympy.functions.special.polynomials), LDLdecomposition()
571 (sympy.matrices.matrices.MatrixBase
laguerre_poly() (in module method), 763
sympy.polys.orthopolys), 900 LDLdecomposition()
Lambda (class in sympy.core.function), 181 (sympy.matrices.sparse.SparseMatrix
lambda_notation() (in module method), 792
sympy.parsing.sympy_parser), 1499 LDLsolve() (sympy.matrices.matrices.MatrixBase
LambdaPrinter (class in method), 764
sympy.printing.lambdarepr), 1072 Le (in module sympy.core.relational), 167
lambdarepr() (in module leading_expv() (sympy.polys.rings.PolyElement
sympy.printing.lambdarepr), 1072 method), 1004
lambdastr() (in module leading_monom() (sympy.polys.rings.PolyElement
sympy.utilities.lambdify), 1478 method), 1004
lambdify() (in module leading_term() (sympy.polys.rings.PolyElement
sympy.utilities.lambdify), 1479 method), 1004
LambertW (class in leadterm() (sympy.core.expr.Expr method),
sympy.functions.elementary.exponential), 133
470 left (sympy.sets.sets.Interval attribute), 1170
Laplace() (in module sympy.stats), 1238 left() (sympy.printing.pretty.stringpict.stringPict

Index 2003
SymPy Documentation, Release 1.3

method), 1085 527

left_open (sympy.sets.sets.Interval attribute), lie_algebra() (sympy.liealgebras.type_a.TypeA
1170 method), 730
leftslash() (sympy.printing.pretty.stringpict.stringPict
lie_algebra() (sympy.liealgebras.type_b.TypeB
method), 1085 method), 732
legendre (class in lie_algebra() (sympy.liealgebras.type_c.TypeC
sympy.functions.special.polynomials), method), 733
569 lie_algebra() (sympy.liealgebras.type_d.TypeD
legendre_poly() (in module method), 734
sympy.polys.orthopolys), 900 lie_heuristic_abaco1_product() (in module
legendre_symbol() (in module sympy.solvers.ode), 1294
sympy.ntheory.residue_ntheory), lie_heuristic_abaco1_simple() (in module
336 sympy.solvers.ode), 1293
length (sympy.geometry.curve.Curve at- lie_heuristic_abaco2_similar() (in module
tribute), 633 sympy.solvers.ode), 1295
length (sympy.geometry.line.LinearEntity at- lie_heuristic_abaco2_unique_general() (in
tribute), 608 module sympy.solvers.ode), 1297
length (sympy.geometry.line.Segment at- lie_heuristic_abaco2_unique_unknown() (in
tribute), 619 module sympy.solvers.ode), 1296
length (sympy.geometry.point.Point at- lie_heuristic_bivariate() (in module
tribute), 594 sympy.solvers.ode), 1294
length (sympy.geometry.polygon.RegularPolygon lie_heuristic_chi() (in module
attribute), 662 sympy.solvers.ode), 1295
length (sympy.physics.continuum_mechanics.beam.Beam
lie_heuristic_function_sum() (in module
attribute), 1790 sympy.solvers.ode), 1296
length (sympy.series.sequences.SeqBase at- lie_heuristic_linear() (in module
tribute), 1146 sympy.solvers.ode), 1297
length() (sympy.combinatorics.permutations.Permutation
LieDerivative (class in sympy.diffgeom), 1841
method), 228 lift() (sympy.polys.polyclasses.DMP method),
length() (sympy.polys.polytools.Poly method), 947
870 lift() (sympy.polys.polytools.Poly method),
lens_formula() (in module 871
sympy.physics.optics.utils), 1780 Limit (class in sympy.series.limits), 1136
lens_makers_formula() (in module limit() (in module sympy.series.limits), 1135
sympy.physics.optics.utils), 1779 limit() (sympy.core.expr.Expr method), 133
lerchphi (class in limit_denominator()
sympy.functions.special.zeta_functions), (sympy.core.numbers.Rational
550 method), 147
LessThan (class in sympy.core.relational), limit_seq() (in module sympy.series.limitseq),
171 1161
LeviCivita (class in limitinf() (in module sympy.series.gruntz),
sympy.functions.special.tensor_functions), 1138
576 limits (sympy.geometry.curve.Curve at-
LexOrder (class in sympy.polys.orderings), tribute), 633
894 limits (sympy.physics.quantum.state.Wavefunction
lfsr_autocorrelation() (in module attribute), 1748
sympy.crypto.crypto), 361 Line (class in sympy.geometry.line), 612
lfsr_connection_polynomial() (in module Line2D (class in sympy.geometry.line), 622
sympy.crypto.crypto), 361 Line2DBaseSeries (class in
lfsr_sequence() (in module sympy.plotting.plot), 1100
sympy.crypto.crypto), 360 Line3D (class in sympy.geometry.line), 627
Li (class in sympy.functions.special.error_functions),
Line3DBaseSeries (class in
528 sympy.plotting.plot), 1100
li (class in sympy.functions.special.error_functions),
line_integrate() (in module sympy.integrals),

2004 Index
 SymPy Documentation, Release 1.3

714 LM() (sympy.polys.polytools.Poly method),

linear_eq_to_matrix() (in module 848
sympy.solvers.solveset), 1386 load (sympy.physics.continuum_mechanics.beam.Beam
linear_momentum() (in module attribute), 1790
sympy.physics.mechanics.functions), load_vector (sympy.physics.continuum_mechanics.beam.Bea
1688 attribute), 1800
linear_momentum() loads (sympy.physics.mechanics.system.SymbolicSystem
(sympy.physics.mechanics.particle.Particle attribute), 1702
method), 1683 locate_new() (sympy.vector.coordsysrect.CoordSys3D
linear_momentum() method), 1866
locatenew() (sympy.physics.vector.point.Point
(sympy.physics.mechanics.rigidbody.RigidBody
method), 1686 method), 1608
LinearEntity (class in sympy.geometry.line), log (class in sympy.functions.elementary.exponential),
602 470
LinearEntity2D (class in log() (sympy.polys.domains.domain.Domain
sympy.geometry.line), 620 method), 933
LinearEntity3D (class in log() (sympy.polys.domains.IntegerRing
sympy.geometry.line), 626 method), 938
linearize() (sympy.physics.mechanics.kane.KanesMethod
log10 (class in sympy.codegen.cfunctions),
method), 1694 431
linearize() (sympy.physics.mechanics.lagrange.LagrangesMethod
log1p (class in sympy.codegen.cfunctions),
method), 1696 432
linearize() (sympy.physics.mechanics.linearize.Linearizer
log2 (class in sympy.codegen.cfunctions), 432
method), 1703 logcombine() (in module
Linearizer (class in sympy.simplify.simplify), 1191
sympy.physics.mechanics.linearize), loggamma (class in
1702 sympy.functions.special.gamma_functions),
LineOver1DRangeSeries (class in 506
sympy.plotting.plot), 1100 Logistic() (in module sympy.stats), 1239
linsolve() (in module sympy.solvers.solveset), LogNormal() (in module sympy.stats), 1240
1388 Lopen() (sympy.sets.sets.Interval class
list() (sympy.combinatorics.permutations.Cycle method), 1170
method), 237 lower (sympy.physics.secondquant.AntiSymmetricTensor
list() (sympy.combinatorics.permutations.Permutation attribute), 1535
method), 228 lower (sympy.tensor.indexed.Idx attribute),
list2numpy() (in module 1408
sympy.matrices.dense), 784 lower_central_series()
list_can_dims (sympy.physics.units.dimensions.DimensionSystem
(sympy.combinatorics.perm_groups.PermutationGro
attribute), 1553 method), 254
list_visitor() (in module lower_triangular (sympy.assumptions.ask.AssumptionKeys
sympy.utilities.enumerative), 1452 attribute), 1111
listcoeffs() (sympy.polys.rings.PolyElement lower_triangular_solve()
method), 1004 (sympy.matrices.matrices.MatrixBase
listmonoms() (sympy.polys.rings.PolyElement method), 773
method), 1005 lowergamma (class in
listterms() (sympy.polys.rings.PolyElement sympy.functions.special.gamma_functions),
method), 1005 511
literal_dp (class in sympy.codegen.fnodes), lseries() (sympy.core.expr.Expr method), 133
439 Lt (in module sympy.core.relational), 166
literal_sp (class in sympy.codegen.fnodes), LT() (in module sympy.polys.polytools), 829
439 LT() (sympy.polys.polytools.Poly method), 848
liupc() (sympy.matrices.sparse.SparseMatrix ltrim() (sympy.polys.polytools.Poly method),
method), 794 871
LM() (in module sympy.polys.polytools), 829 lucas (class in sympy.functions.combinatorial.numbers),

Index 2005
SymPy Documentation, Release 1.3

492 562
LUdecomposition() (sympy.matrices.matrices.MatrixBase
mathieus (class in
method), 764 sympy.functions.special.mathieu_functions),
LUdecomposition_Simple() 560
(sympy.matrices.matrices.MatrixBase mathieusprime (class in
method), 765 sympy.functions.special.mathieu_functions),
LUdecompositionFF() 561
(sympy.matrices.matrices.MatrixBase mathml() (in module sympy.printing.mathml),
method), 765 1076
LUsolve() (sympy.matrices.matrices.MatrixBasemathml_tag() (sympy.printing.mathml.MathMLContentPrint
method), 766 method), 1076
mathml_tag() (sympy.printing.mathml.MathMLPresentationP
M method), 1076
magnitude() (sympy.physics.vector.vector.VectorMathMLContentPrinter (class in
method), 1602 sympy.printing.mathml), 1076
magnitude() (sympy.vector.vector.Vector MathMLPresentationPrinter (class in
method), 1874 sympy.printing.mathml), 1076
major (sympy.geometry.ellipse.Ellipse at- MathMLPrinterBase (class in
tribute), 641 sympy.printing.mathml), 1076
MatMul (class in sympy.matrices.expressions),
make_perm() (sympy.combinatorics.perm_groups.PermutationGroup
method), 255 806
make_routine() (in module MatPow (class in
sympy.utilities.codegen), 1448 sympy.matrices.expressions), 806
Manifold (class in sympy.diffgeom), 1832 matrix2numpy() (in module
map() (sympy.polys.domains.domain.Domain sympy.matrices.dense), 784
method), 933 matrix_fglm() (in module
mass (sympy.physics.mechanics.particle.Particle sympy.polys.fglmtools), 1024
attribute), 1683 matrix_form() (sympy.liealgebras.weyl_group.WeylGroup
mass_matrix (sympy.physics.mechanics.kane.KanesMethod method), 740
attribute), 1694 matrix_multiply_elementwise() (in module
sympy.matrices.dense), 779
mass_matrix (sympy.physics.mechanics.lagrange.LagrangesMethod
attribute), 1697 matrix_rep() (in module
sympy.physics.secondquant), 1530
mass_matrix_full (sympy.physics.mechanics.kane.KanesMethod
attribute), 1694 matrix_to_density() (in module
sympy.physics.quantum.qubit), 1761
mass_matrix_full (sympy.physics.mechanics.lagrange.LagrangesMethod
attribute), 1697 matrix_to_qubit() (in module
MatAdd (class in sympy.matrices.expressions), sympy.physics.quantum.qubit), 1760
806 matrix_to_vector() (in module sympy.vector),
match() (sympy.core.basic.Basic method), 1881
107 MatrixBase (class in
matches() (sympy.core.basic.Basic method), sympy.matrices.matrices), 762
107 MatrixError (class in
mathematica() (in module sympy.matrices.matrices), 779
sympy.parsing.mathematica), 1497 MatrixExpr (class in
mathematica_code() (in module sympy.matrices.expressions), 803
sympy.printing.mathematica), 1062 MatrixSymbol (class in
MathieuBase (class in sympy.matrices.expressions), 805
Max (class in sympy.functions.elementary.miscellaneous),
sympy.functions.special.mathieu_functions),
560 473
mathieuc (class in max (sympy.codegen.ast.FloatType at-
sympy.functions.special.mathieu_functions), tribute), 419
561 max() (sympy.combinatorics.permutations.Permutation
mathieucprime (class in method), 229
max_bmoment()
sympy.functions.special.mathieu_functions), (sympy.physics.continuum_mechanics.beam

2006 Index
 SymPy Documentation, Release 1.3

method), 1791 midpoint (sympy.geometry.line.Segment at-

max_deflection() (sympy.physics.continuum_mechanics.beam.Beam
tribute), 619
method), 1791 midpoint() (sympy.geometry.point.Point
max_div (sympy.combinatorics.perm_groups.PermutationGroupmethod), 594
attribute), 255 Min (class in sympy.functions.elementary.miscellaneous),
max_exponent (sympy.codegen.ast.FloatType 473
attribute), 419 min() (sympy.combinatorics.permutations.Permutation
max_norm() (sympy.polys.polyclasses.DMP method), 229
method), 948 min_exponent (sympy.codegen.ast.FloatType
max_norm() (sympy.polys.polytools.Poly attribute), 420
method), 871 min_qubits (sympy.physics.quantum.gate.CGate
max_shear_force() (sympy.physics.continuum_mechanics.beam.Beam
attribute), 1752
method), 1791 min_qubits (sympy.physics.quantum.gate.CNotGate
Maxwell() (in module sympy.stats), 1240 attribute), 1754
MCodePrinter (class in min_qubits (sympy.physics.quantum.gate.Gate
sympy.printing.mathematica), 1061 attribute), 1751
mdft() (in module sympy.physics.matrices), minimal_block() (sympy.combinatorics.perm_groups.Permut
1513 method), 256
measure (sympy.sets.sets.Set attribute), 1166 minimal_blocks() (sympy.combinatorics.perm_groups.Permu
measure_all() (in module method), 256
sympy.physics.quantum.qubit), 1761 minimal_polynomial() (in module
measure_all_oneshot() (in module sympy.polys.numberfields), 891
sympy.physics.quantum.qubit), 1762 minlex() (in module sympy.utilities.iterables),
measure_partial() (in module 1465
sympy.physics.quantum.qubit), 1761 minor (sympy.geometry.ellipse.Ellipse at-
measure_partial_oneshot() (in module tribute), 642
sympy.physics.quantum.qubit), 1762 minpoly() (in module
medial (sympy.geometry.polygon.Triangle at- sympy.polys.numberfields), 892
tribute), 671 mirror_formula() (in module
medians (sympy.geometry.polygon.Triangle sympy.physics.optics.utils), 1780
attribute), 671 mobius (class in sympy.ntheory), 340
Medium (class in mobius_transform() (in module
sympy.physics.optics.medium), 1775 sympy.discrete.transforms), 386
meets() (sympy.series.gruntz.SubsSet mobiusrange() (sympy.ntheory.generate.Sieve
method), 1140 method), 306
meijerg (class in sympy.functions.special.hyper),Mod (class in sympy.core.mod), 166
555 modgcd_bivariate() (in module
mellin_transform() (in module sympy.polys.modulargcd), 1028
sympy.integrals.transforms), 690 modgcd_multivariate() (in module
memoize_property() (in module sympy.polys.modulargcd), 1029
sympy.utilities.decorator), 1450 modgcd_univariate() (in module
merge (class in sympy.codegen.fnodes), 439 sympy.polys.modulargcd), 1027
merge_solution() (in module Module (class in sympy.codegen.fnodes), 436
sympy.solvers.diophantine), 1367 Module (class in sympy.polys.agca.modules),
metric_to_Christoffel_1st() (in module 912
sympy.diffgeom), 1845 module_quotient() (sympy.polys.agca.modules.SubModule
metric_to_Christoffel_2nd() (in module method), 917
sympy.diffgeom), 1846 ModuleHomomorphism (class in
metric_to_Ricci_components() (in module sympy.polys.agca.homomorphisms),
sympy.diffgeom), 1846 926
metric_to_Riemann_components() (in module moment_load_vector
sympy.diffgeom), 1846 (sympy.physics.continuum_mechanics.beam.Beam3D
mgamma() (in module attribute), 1800
sympy.physics.matrices), 1514 momentum (sympy.physics.quantum.cartesian.PxBra

Index 2007
SymPy Documentation, Release 1.3

attribute), 1717 Mul() (sympy.assumptions.handlers.sets.AskRationalHandle

momentum (sympy.physics.quantum.cartesian.PxKet static method), 1129
attribute), 1717 Mul() (sympy.assumptions.handlers.sets.AskRealHandler
monic() (in module sympy.polys.polytools), static method), 1129
838 mul() (sympy.polys.domains.domain.Domain
monic() (sympy.polys.polyclasses.DMP method), 933
method), 948 mul() (sympy.polys.polyclasses.DMF
monic() (sympy.polys.polytools.Poly method), method), 950
871 mul() (sympy.polys.polyclasses.DMP method),
monic() (sympy.polys.rings.PolyElement 948
method), 1005 mul() (sympy.polys.polytools.Poly method),
Monomial (class in sympy.polys.monomials), 872
893 mul() (sympy.polys.rings.PolyRing method),
monomial_basis() (sympy.polys.rings.PolyRing 1000
method), 1000 mul_ground() (sympy.polys.polyclasses.DMP
monomial_count() (in module method), 948
sympy.polys.monomials), 894 mul_ground() (sympy.polys.polytools.Poly
monoms() (sympy.polys.polyclasses.DMP method), 872
method), 948 mul_inv() (sympy.combinatorics.permutations.Permutation
monoms() (sympy.polys.polytools.Poly method), 229
method), 872 mul_xin() (in module
monoms() (sympy.polys.rings.PolyElement sympy.polys.ring_series), 1046
method), 1005 MultiFactorial (class in
monotonicity_helper() (in module sympy.functions.combinatorial.factorials),
sympy.calculus.singularities), 1504 494
Morphism (class in sympy.categories), 1815 multinomial_coefficients() (in module
morphisms (sympy.categories.diagram_drawing.DiagramGrid sympy.ntheory.multinomial), 331
attribute), 1826 multinomial_coefficients_iterator() (in mod-
MpmathPrinter (class in ule sympy.ntheory.multinomial), 332
sympy.printing.pycode), 1077 multiplicity() (in module
mr() (in module sympy.ntheory.primetest), sympy.ntheory.factor_), 315
333 multiply() (sympy.matrices.matrices.MatrixBase
mrv() (in module sympy.series.gruntz), 1139 method), 773
mrv_leadterm() (in module multiply_ideal() (sympy.polys.agca.modules.FreeModule
sympy.series.gruntz), 1138 method), 914
mrv_max1() (in module sympy.series.gruntz), multiply_ideal() (sympy.polys.agca.modules.Module
1139 method), 913
mrv_max3() (in module sympy.series.gruntz), multiply_ideal() (sympy.polys.agca.modules.SubModule
1139 method), 917
msigma() (in module multiset() (in module
sympy.physics.matrices), 1514 sympy.utilities.iterables), 1465
msubs() (in module multiset_combinations() (in module
sympy.physics.mechanics), 1703 sympy.utilities.iterables), 1466
Mul (class in sympy.core.mul), 160 multiset_partitions() (in module
Mul() (sympy.assumptions.handlers.calculus.AskFiniteHandler
sympy.utilities.iterables), 1466
static method), 1126 multiset_partitions_taocp() (in module
Mul() (sympy.assumptions.handlers.sets.AskAntiHermitianHandler
sympy.utilities.enumerative), 1451
static method), 1128 multiset_permutations() (in module
Mul() (sympy.assumptions.handlers.sets.AskHermitianHandler
sympy.utilities.iterables), 1467
static method), 1128 MultisetPartitionTraverser (class in
Mul() (sympy.assumptions.handlers.sets.AskImaginaryHandler
sympy.utilities.enumerative), 1453
static method), 1129 MultivariatePolynomialError (class in
Mul() (sympy.assumptions.handlers.sets.AskIntegerHandlersympy.polys.polyerrors), 1026
static method), 1129 MutableDenseMatrix (class in

2008 Index
 SymPy Documentation, Release 1.3

sympy.matrices.dense), 787 NegativeInfinity (class in

MutableDenseNDimArray (class in sympy.core.numbers), 152
sympy.tensor.array), 1403 NegativeOne (class in sympy.core.numbers),
MutableSparseMatrix (class in 150
sympy.matrices.sparse), 796 new() (sympy.polys.polytools.Poly class
MutableSparseNDimArray (class in method), 873
sympy.tensor.array), 1403 newtons_method() (in module
Mx (class in sympy.physics.quantum.circuitplot), sympy.codegen.algorithms), 441
1750 newtons_method_function() (in module
Mz (class in sympy.physics.quantum.circuitplot), sympy.codegen.algorithms), 442
1750 next() (sympy.combinatorics.graycode.GrayCode
method), 282
N next() (sympy.combinatorics.prufer.Prufer
n (sympy.combinatorics.graycode.GrayCode method), 271
attribute), 282 next() (sympy.printing.pretty.stringpict.stringPict
N (sympy.physics.quantum.shor.CMod at- static method), 1085
tribute), 1763 next_binary() (sympy.combinatorics.subsets.Subset
N() (in module sympy.core.evalf), 202 method), 276
n() (sympy.geometry.point.Point method), 595 next_gray() (sympy.combinatorics.subsets.Subset
n() (sympy.polys.domains.domain.Domain method), 276
method), 933 next_lex() (sympy.combinatorics.partitions.IntegerPartition
n_order() (in module method), 211
sympy.ntheory.residue_ntheory), next_lex() (sympy.combinatorics.permutations.Permutation
334 method), 229
Nakagami() (in module sympy.stats), 1241 next_lexicographic()
name (sympy.categories.Category attribute), (sympy.combinatorics.subsets.Subset
1820 method), 276
name (sympy.categories.NamedMorphism at- next_nonlex() (sympy.combinatorics.permutations.Permutati
tribute), 1816 method), 230
NamedMorphism (class in sympy.categories), next_trotterjohnson()
1816 (sympy.combinatorics.permutations.Permutation
NaN (class in sympy.core.numbers), 151 method), 230
Nand (class in sympy.logic.boolalg), 748 nextprime() (in module
nargs (sympy.core.function.FunctionClass at- sympy.ntheory.generate), 309
tribute), 188 nfloat() (in module sympy.core.function), 202
nine_point_circle (sympy.geometry.polygon.Triangle
native_coeffs() (sympy.polys.numberfields.AlgebraicNumber
method), 893 attribute), 672
Naturals (class in sympy.sets.fancysets), 1177 nnz() (sympy.matrices.sparse.SparseMatrix
Naturals0 (class in sympy.sets.fancysets), method), 795
1177 NO (class in sympy.physics.secondquant),
Ne (in module sympy.core.relational), 166 1531
necklaces() (in module no_attrs_in_subclass (class in
sympy.utilities.iterables), 1468 sympy.utilities.decorator), 1450
neg() (sympy.polys.domains.domain.Domain Node (class in sympy.codegen.ast), 422
method), 933 nodes (sympy.combinatorics.prufer.Prufer at-
neg() (sympy.polys.polyclasses.DMF method), tribute), 271
951 NoneToken (class in sympy.codegen.ast), 422
neg() (sympy.polys.polyclasses.DMP method), nonlinsolve() (in module
948 sympy.solvers.solveset), 1390
neg() (sympy.polys.polytools.Poly method), nonnegative, 99
872 nonnegative (sympy.assumptions.ask.AssumptionKeys
negative, 99 attribute), 1112
negative (sympy.assumptions.ask.AssumptionKeys nonpositive, 100
attribute), 1111 nonpositive (sympy.assumptions.ask.AssumptionKeys

Index 2009
SymPy Documentation, Release 1.3

attribute), 1112 873

NonSquareMatrixError (class in nseries() (sympy.core.expr.Expr method), 133
sympy.matrices.matrices), 779 nsimplify() (in module
nonzero, 99 sympy.simplify.simplify), 1190
nonzero (sympy.assumptions.ask.AssumptionKeys nsimplify() (sympy.core.expr.Expr method),
attribute), 1113 134
Nor (class in sympy.logic.boolalg), 748 nsolve() (in module sympy.solvers.solvers),
norm (sympy.physics.quantum.state.Wavefunction 1339
attribute), 1748 nth() (sympy.polys.polyclasses.DMP method),
norm() (sympy.matrices.matrices.MatrixBase 948
method), 773 nth() (sympy.polys.polytools.Poly method),
norm() (sympy.polys.polyclasses.DMP 874
method), 948 nth_power_roots_poly() (in module
norm() (sympy.polys.polytools.Poly method), sympy.polys.polytools), 844
873 nth_power_roots_poly()
normal (sympy.assumptions.ask.AssumptionKeys (sympy.polys.polytools.Poly method),
attribute), 1113 874
Normal() (in module sympy.stats), 1242 nthroot() (in module sympy.simplify.simplify),
normal_closure() (sympy.combinatorics.perm_groups.PermutationGroup
1188
method), 257 nthroot_mod() (in module
normal_lines() (sympy.geometry.ellipse.Ellipse sympy.ntheory.residue_ntheory),
method), 642 335
normal_vector (sympy.geometry.plane.Plane ntt() (in module sympy.discrete.transforms),
attribute), 677 384
normalize() (sympy.physics.quantum.state.Wavefunction
nu (sympy.functions.special.hyper.meijerg at-
method), 1749 tribute), 557
normalize() (sympy.physics.vector.vector.VectorNumber (class in sympy.core.numbers), 142
method), 1602 numbered_symbols() (in module
normalize() (sympy.vector.vector.Vector sympy.utilities.iterables), 1468
method), 1874 NumberSymbol (class in
normalize_theta_set() (in module sympy.core.numbers), 148
sympy.sets.fancysets), 1184 numer() (sympy.polys.domains.AlgebraicField
normalized() (in module method), 941
sympy.physics.quantum.gate), 1754 numer() (sympy.polys.domains.domain.Domain
normalized() (sympy.matrices.matrices.MatrixBase method), 933
method), 774 numer() (sympy.polys.domains.ExpressionDomain
NormalPSpace (class in method), 944
sympy.stats.crv_types), 1261 numer() (sympy.polys.domains.FractionField
Not (class in sympy.logic.boolalg), 746 method), 942
NotAlgebraic (class in numer() (sympy.polys.domains.ring.Ring
sympy.polys.polyerrors), 1026 method), 936
NotInvertible (class in numer() (sympy.polys.polyclasses.DMF
sympy.polys.polyerrors), 1026 method), 951
NotReversible (class in NumPyPrinter (class in
sympy.polys.polyerrors), 1026 sympy.printing.pycode), 1077
npartitions() (in module
sympy.ntheory.partitions_), 332 O
nqubits (sympy.physics.quantum.gate.CGate Object (class in sympy.categories), 1815
attribute), 1752 objects (sympy.categories.Category at-
nqubits (sympy.physics.quantum.gate.Gate tribute), 1820
attribute), 1751 objects (sympy.categories.Diagram at-
nroots() (in module sympy.polys.polytools), tribute), 1822
844 octave_code() (in module
nroots() (sympy.polys.polytools.Poly method), sympy.printing.octave), 1067

2010 Index
 SymPy Documentation, Release 1.3

OctaveCodeGen (class in tribute), 1411

sympy.utilities.codegen), 1444 old_frac_field() (sympy.polys.domains.domain.Domain
OctaveCodePrinter (class in method), 933
sympy.printing.octave), 1067 old_poly_ring() (sympy.polys.domains.domain.Domain
odd, 99 method), 933
odd (sympy.assumptions.ask.AssumptionKeys One (class in sympy.core.numbers), 150
attribute), 1113 one (sympy.polys.polytools.Poly attribute),
ode_1st_exact() (in module 874
sympy.solvers.ode), 1274 OneQubitGate (class in
ode_1st_homogeneous_coeff_best() (in mod- sympy.physics.quantum.gate), 1752
ule sympy.solvers.ode), 1275 ones() (in module sympy.matrices.dense), 779
ode_1st_homogeneous_coeff_subs_dep_div_indep() open() (sympy.sets.sets.Interval class
(in module sympy.solvers.ode), 1276 method), 1171
ode_1st_homogeneous_coeff_subs_indep_div_dep() OperationNotSupported (class in
(in module sympy.solvers.ode), 1277 sympy.polys.polyerrors), 1026
ode_1st_linear() (in module Operator (class in
sympy.solvers.ode), 1278 sympy.physics.quantum.operator),
ode_1st_power_series() (in module 1719
sympy.solvers.ode), 1291 operators (sympy.physics.quantum.state.StateBase
ode_2nd_power_series_ordinary() (in module attribute), 1742
sympy.solvers.ode), 1291 operators_to_state() (in module
ode_2nd_power_series_regular() (in module sympy.physics.quantum.operatorset),
sympy.solvers.ode), 1292 1725
ode_almost_linear() (in module opt_cse() (in module
sympy.solvers.ode), 1287 sympy.simplify.cse_main), 1206
ode_Bernoulli() (in module Optimization (class in
sympy.solvers.ode), 1279 sympy.codegen.rewriting), 409
ode_lie_group() (in module optimize() (in module
sympy.solvers.ode), 1290 sympy.codegen.rewriting), 410
ode_linear_coefficients() (in module OptionError (class in
sympy.solvers.ode), 1288 sympy.polys.polyerrors), 1027
ode_Liouville() (in module Or (class in sympy.logic.boolalg), 746
sympy.solvers.ode), 1281 OracleGate (class in
ode_nth_linear_constant_coeff_homogeneous() sympy.physics.quantum.grover),
(in module sympy.solvers.ode), 1282 1756
ode_nth_linear_constant_coeff_undetermined_coefficients()
orbit() (sympy.combinatorics.perm_groups.PermutationGrou
(in module sympy.solvers.ode), 1284 method), 258
ode_nth_linear_constant_coeff_variation_of_parameters()
orbit_rep() (sympy.combinatorics.perm_groups.PermutationG
(in module sympy.solvers.ode), 1285 method), 258
ode_order() (in module orbit_transversal() (sympy.combinatorics.perm_groups.Perm
sympy.solvers.deutils), 1342 method), 258
ode_Riccati_special_minus2() (in module orbits() (sympy.combinatorics.perm_groups.PermutationGro
sympy.solvers.ode), 1282 method), 259
ode_separable() (in module Order (class in sympy.series.order), 1141
sympy.solvers.ode), 1286 order (sympy.functions.special.bessel.BesselBase
ode_separable_reduced() (in module attribute), 534
sympy.solvers.ode), 1289 order() (sympy.combinatorics.perm_groups.PermutationGro
ode_sol_simplicity() (in module method), 259
sympy.solvers.ode), 1273 order() (sympy.combinatorics.permutations.Permutation
odesimp() (in module sympy.solvers.ode), method), 230
1270 ordered_partitions() (in module
of_type() (sympy.polys.domains.domain.Domain sympy.utilities.iterables), 1469
method), 933 orient() (sympy.physics.vector.frame.ReferenceFrame
offset (sympy.tensor.indexed.IndexedBase at- method), 1595

Index 2011
SymPy Documentation, Release 1.3

orient_new() (sympy.vector.coordsysrect.CoordSys3D
parameter (sympy.geometry.curve.Curve at-
method), 1867 tribute), 633
orient_new_axis() (sympy.vector.coordsysrect.CoordSys3D
parameter_value() (sympy.geometry.entity.GeometryEntity
method), 1868 method), 585
orient_new_body() (sympy.vector.coordsysrect.CoordSys3D
parameter_value() (sympy.geometry.plane.Plane
method), 1868 method), 677
orient_new_quaternion() Parametric2DLineSeries (class in
(sympy.vector.coordsysrect.CoordSys3D sympy.plotting.plot), 1100
method), 1869 Parametric3DLineSeries (class in
orient_new_space() (sympy.vector.coordsysrect.CoordSys3Dsympy.plotting.plot), 1100
method), 1870 ParametricSurfaceSeries (class in
Orienter (class in sympy.vector.orienters), sympy.plotting.plot), 1101
1878 parametrize_ternary_quadratic() (in module
orientnew() (sympy.physics.vector.frame.ReferenceFrame sympy.solvers.diophantine), 1368
method), 1596 parens() (sympy.printing.pretty.stringpict.stringPict
origin (sympy.geometry.point.Point attribute), method), 1085
595 Pareto() (in module sympy.stats), 1243
orthocenter (sympy.geometry.polygon.Triangle parity() (sympy.combinatorics.permutations.Permutation
attribute), 672 method), 231
orthogonal (sympy.assumptions.ask.AssumptionKeysparse_expr() (in module
attribute), 1114 sympy.parsing.sympy_parser), 1496
orthogonal_direction parse_latex() (in module
(sympy.geometry.point.Point at- sympy.parsing.latex), 1500
tribute), 595 parse_maxima() (in module
outer() (in module sympy.parsing.maxima), 1497
sympy.physics.vector.functions), partial_velocity() (in module
1619 sympy.physics.vector.functions),
outer() (sympy.physics.vector.vector.Vector 1612
method), 1602 partial_velocity() (sympy.physics.vector.frame.ReferenceFra
outer() (sympy.vector.vector.Vector method), method), 1597
1874 partial_velocity() (sympy.physics.vector.point.Point
OuterProduct (class in method), 1608
sympy.physics.quantum.operator), Particle (class in sympy.physics.mechanics.particle),
1721 1681
OutputArgument (class in Partition (class in
sympy.utilities.codegen), 1439 sympy.combinatorics.partitions),
208
P partition (class in
P() (in module sympy.stats), 1252 sympy.functions.combinatorial.numbers),
p1 (sympy.geometry.line.LinearEntity at- 493
tribute), 608 partition (sympy.combinatorics.partitions.Partition
p1 (sympy.geometry.plane.Plane attribute), attribute), 209
677 partition() (in module
p2 (sympy.geometry.line.LinearEntity at- sympy.solvers.diophantine), 1363
tribute), 608 partitions() (in module
padded_key() (in module sympy.utilities.iterables), 1470
sympy.crypto.crypto), 343 pat_matrix() (in module
parallel_line() (sympy.geometry.line.LinearEntity sympy.physics.matrices), 1515
method), 608 Patch (class in sympy.diffgeom), 1832
parallel_plane() (sympy.geometry.plane.Plane pde_1st_linear_constant_coeff() (in module
method), 677 sympy.solvers.pde), 1325
parallel_poly_from_expr() (in module pde_1st_linear_constant_coeff_homogeneous()
sympy.polys.polytools), 828 (in module sympy.solvers.pde), 1324
pde_1st_linear_variable_coeff() (in module

2012 Index
 SymPy Documentation, Release 1.3

sympy.solvers.pde), 1326 perpendicular_line()

pde_separate() (in module (sympy.geometry.line.LinearEntity
sympy.solvers.pde), 1319 method), 609
pde_separate_add() (in module perpendicular_line()
sympy.solvers.pde), 1320 (sympy.geometry.line.LinearEntity2D
pde_separate_mul() (in module method), 621
sympy.solvers.pde), 1320 perpendicular_line()
pdiv() (in module sympy.polys.polytools), 829 (sympy.geometry.plane.Plane
pdiv() (sympy.polys.polyclasses.DMP method), 678
method), 948 perpendicular_plane()
pdiv() (sympy.polys.polytools.Poly method), (sympy.geometry.plane.Plane
874 method), 678
pdsolve() (in module sympy.solvers.pde), perpendicular_segment()
1321 (sympy.geometry.line.LinearEntity
per() (sympy.polys.polyclasses.DMF method), method), 609
951 pexquo() (in module sympy.polys.polytools),
per() (sympy.polys.polyclasses.DMP method), 830
948 pexquo() (sympy.polys.polyclasses.DMP
per() (sympy.polys.polytools.Poly method), method), 948
875 pexquo() (sympy.polys.polytools.Poly
perfect_power() (in module method), 875
sympy.ntheory.factor_), 315 pgroup (sympy.combinatorics.polyhedron.Polyhedron
periapsis (sympy.geometry.ellipse.Ellipse at- attribute), 268
tribute), 643 Phase (in module
perimeter (sympy.geometry.polygon.Polygon sympy.physics.quantum.gate), 1754
attribute), 655 phase (sympy.physics.optics.waves.TWave at-
period_find() (in module tribute), 1783
sympy.physics.quantum.shor), 1763 PhaseGate (class in
periodic_argument (class in sympy.physics.quantum.gate), 1753
sympy.functions.elementary.complexes),Pi (class in sympy.core.numbers), 154
452 PIABBra (class in
perm2tensor() (sympy.tensor.tensor.TensMul sympy.physics.quantum.piab), 1764
method), 1429 PIABHamiltonian (class in
permeability (sympy.physics.optics.medium.Medium sympy.physics.quantum.piab), 1764
attribute), 1776 PIABKet (class in
permittivity (sympy.physics.optics.medium.Medium sympy.physics.quantum.piab), 1764
attribute), 1776 Piecewise (class in
Permutation (class in sympy.functions.elementary.piecewise),
sympy.combinatorics.permutations), 471
213 piecewise_fold() (in module
PermutationGroup (class in sympy.functions.elementary.piecewise),
sympy.combinatorics.perm_groups), 472
238 pinv() (sympy.matrices.matrices.MatrixBase
PermutationOperator (class in method), 774
sympy.physics.secondquant), 1537 pinv_solve() (sympy.matrices.matrices.MatrixBase
permute() (sympy.polys.polyclasses.DMP method), 774
method), 948 Plane (class in sympy.geometry.plane), 673
permute_signs() (in module Plot (class in sympy.plotting.plot), 1088
sympy.utilities.iterables), 1471 plot() (in module sympy.plotting.plot), 1090
permutedims() (in module plot3d() (in module sympy.plotting.plot), 1094
sympy.tensor.array), 1403 plot3d_parametric_line() (in module
perpendicular_bisector() sympy.plotting.plot), 1095
(sympy.geometry.line.Segment plot3d_parametric_surface() (in module
method), 620 sympy.plotting.plot), 1097

Index 2013
SymPy Documentation, Release 1.3

plot_bending_moment() attribute), 1183

(sympy.physics.continuum_mechanics.beam.Beam
polar_lift (class in
method), 1791 sympy.functions.elementary.complexes),
plot_deflection() (sympy.physics.continuum_mechanics.beam.Beam
451
method), 1791 PoleError (class in sympy.core.function), 197
plot_gate() (sympy.physics.quantum.gate.CGatePolificationFailed (class in
method), 1752 sympy.polys.polyerrors), 1027
plot_implicit() (in module pollard_pm1() (in module
sympy.plotting.plot_implicit), 1098 sympy.ntheory.factor_), 317
plot_interval() (sympy.geometry.curve.Curve pollard_rho() (in module
method), 634 sympy.ntheory.factor_), 315
plot_interval() (sympy.geometry.ellipse.Ellipse Poly (class in sympy.polys.polytools), 847
method), 643 poly() (in module sympy.polys.polytools), 828
plot_interval() (sympy.geometry.line.Line poly_from_expr() (in module
method), 614 sympy.polys.polytools), 828
plot_interval() (sympy.geometry.line.Ray poly_ring() (sympy.polys.domains.domain.Domain
method), 616 method), 933
plot_interval() (sympy.geometry.line.Segment poly_unify() (sympy.polys.polyclasses.DMF
method), 620 method), 951
plot_interval() (sympy.geometry.polygon.Polygon PolyElement (class in sympy.polys.rings),
method), 655 1001
plot_loading_results() polygamma (class in
(sympy.physics.continuum_mechanics.beam.Beam sympy.functions.special.gamma_functions),
method), 1792 508
plot_parametric() (in module Polygon (class in sympy.geometry.polygon),
sympy.plotting.plot), 1092 650
plot_shear_force() (sympy.physics.continuum_mechanics.beam.Beam
Polyhedron (class in
method), 1793 sympy.combinatorics.polyhedron),
plot_slope() (sympy.physics.continuum_mechanics.beam.Beam267
method), 1793 polylog (class in sympy.functions.special.zeta_functions),
Point (class in sympy.diffgeom), 1835 549
Point (class in sympy.geometry.point), 590 polynomial() (sympy.series.formal.FormalPowerSeries
Point (class in sympy.physics.vector.point), method), 1154
1606 PolynomialError (class in
point (sympy.core.function.Subs attribute), sympy.polys.polyerrors), 1026
191 PolynomialRing (class in
point (sympy.physics.mechanics.particle.Particle sympy.polys.domains), 938
attribute), 1683 PolyRing (class in sympy.polys.rings), 1000
point() (sympy.diffgeom.CoordSystem polytope_integrate() (in module
method), 1835 sympy.integrals.intpoly), 727
Point2D (class in sympy.geometry.point), 596 pos() (sympy.polys.domains.domain.Domain
Point3D (class in sympy.geometry.point), 598 method), 933
point_cflexure() (sympy.physics.continuum_mechanics.beam.Beam
pos_from() (sympy.physics.vector.point.Point
method), 1794 method), 1609
point_to_coords() (sympy.diffgeom.CoordSystemPOSform() (in module sympy.logic.boolalg),
method), 1835 743
Pointer (class in sympy.codegen.ast), 422 posify() (in module sympy.simplify.simplify),
points (sympy.geometry.line.LinearEntity at- 1191
tribute), 610 position (sympy.physics.quantum.cartesian.XBra
pointwise_stabilizer() attribute), 1717
(sympy.combinatorics.perm_groups.PermutationGroup
position (sympy.physics.quantum.cartesian.XKet
method), 260 attribute), 1717
Poisson() (in module sympy.stats), 1224 position_wrt() (sympy.vector.coordsysrect.CoordSys3D
polar (sympy.sets.fancysets.ComplexRegion method), 1871

2014 Index
 SymPy Documentation, Release 1.3

position_x (sympy.physics.quantum.cartesian.PositionState3D
Pow() (sympy.assumptions.handlers.order.AskNegativeHand
attribute), 1717 static method), 1127
position_y (sympy.physics.quantum.cartesian.PositionState3D
Pow() (sympy.assumptions.handlers.sets.AskAntiHermitianH
attribute), 1717 static method), 1128
position_z (sympy.physics.quantum.cartesian.PositionState3D
Pow() (sympy.assumptions.handlers.sets.AskHermitianHand
attribute), 1717 static method), 1128
PositionBra3D (class in Pow() (sympy.assumptions.handlers.sets.AskImaginaryHand
sympy.physics.quantum.cartesian), static method), 1129
1717 Pow() (sympy.assumptions.handlers.sets.AskIntegerHandler
PositionKet3D (class in static method), 1129
sympy.physics.quantum.cartesian), Pow() (sympy.assumptions.handlers.sets.AskRationalHandle
1717 static method), 1129
PositionState3D (class in Pow() (sympy.assumptions.handlers.sets.AskRealHandler
sympy.physics.quantum.cartesian), static method), 1129
1717 pow() (sympy.polys.domains.domain.Domain
positive, 99 method), 933
positive (sympy.assumptions.ask.AssumptionKeys pow() (sympy.polys.polyclasses.ANP method),
attribute), 1114 951
positive_definite (sympy.assumptions.ask.AssumptionKeys
pow() (sympy.polys.polyclasses.DMF
attribute), 1115 method), 951
positive_roots() (sympy.liealgebras.type_a.TypeApow() (sympy.polys.polyclasses.DMP
method), 730 method), 948
positive_roots() (sympy.liealgebras.type_b.TypeBpow() (sympy.polys.polytools.Poly method),
method), 732 875
positive_roots() (sympy.liealgebras.type_c.TypeCpow_xin() (in module
method), 733 sympy.polys.ring_series), 1046
positive_roots() (sympy.liealgebras.type_d.TypeDpowdenest() (in module
method), 734 sympy.simplify.powsimp), 1202
positive_roots() (sympy.liealgebras.type_e.TypeEpowerset() (sympy.sets.sets.Set method),
method), 736 1166
positive_roots() (sympy.liealgebras.type_f.TypeFpowsimp() (in module
method), 737 sympy.simplify.powsimp), 1201
positive_roots() (sympy.liealgebras.type_g.TypeGpowsimp() (sympy.core.expr.Expr method),
method), 738 134
PostDecrement (class in pprint_nodes() (in module
sympy.codegen.cnodes), 433 sympy.printing.tree), 1079
postfixes() (in module PQa() (in module sympy.solvers.diophantine),
sympy.utilities.iterables), 1471 1367
PostIncrement (class in pquo() (in module sympy.polys.polytools), 830
sympy.codegen.cnodes), 433 pquo() (sympy.polys.polyclasses.DMP
postorder_traversal() (in module method), 948
sympy.utilities.iterables), 1471 pquo() (sympy.polys.polytools.Poly method),
potential_energy (sympy.physics.mechanics.particle.Particle
876
attribute), 1683 PRECEDENCE (in module
potential_energy (sympy.physics.mechanics.rigidbody.RigidBody
sympy.printing.precedence), 1083
attribute), 1686 precedence() (in module
potential_energy() (in module sympy.printing.precedence), 1083
sympy.physics.mechanics.functions), PRECEDENCE_FUNCTIONS (in module
1690 sympy.printing.precedence), 1083
Pow (class in sympy.core.power), 157 PRECEDENCE_VALUES (in module
Pow() (sympy.assumptions.handlers.calculus.AskFiniteHandler
sympy.printing.precedence), 1083
static method), 1126 PrecisionExhausted (class in
Pow() (sympy.assumptions.handlers.ntheory.AskPrimeHandler
sympy.core.evalf), 202
static method), 1127 PreDecrement (class in

Index 2015
SymPy Documentation, Release 1.3

sympy.codegen.cnodes), 433 preview() (in module

Predicate (class in sympy.printing.preview), 1080
sympy.assumptions.assume), 1122 preview_diagram() (in module
preferred_index (sympy.functions.special.tensor_functions.KroneckerDelta
sympy.categories.diagram_drawing),
attribute), 580 1831
preferred_index (sympy.physics.secondquant.KroneckerDelta
prevprime() (in module
attribute), 1522 sympy.ntheory.generate), 309
Prefix (class in sympy.physics.units.prefixes), prime, 99
1553 prime (sympy.assumptions.ask.AssumptionKeys
prefixes() (in module attribute), 1115
sympy.utilities.iterables), 1472 prime() (in module sympy.ntheory.generate),
PreIncrement (class in 307
sympy.codegen.cnodes), 433 prime_as_sum_of_two_squares() (in module
prem() (in module sympy.polys.polytools), 830 sympy.solvers.diophantine), 1371
prem() (sympy.polys.polyclasses.DMP primefactors() (in module
method), 948 sympy.ntheory.factor_), 321
prem() (sympy.polys.polytools.Poly method), primenu (class in sympy.ntheory.factor_), 328
876 primeomega (class in sympy.ntheory.factor_),
premises (sympy.categories.Diagram at- 328
tribute), 1823 primepi() (in module
presentation() (sympy.combinatorics.perm_groups.PermutationGroup
sympy.ntheory.generate), 308
method), 260 primerange() (in module
pretty() (in module sympy.ntheory.generate), 309
sympy.printing.pretty.pretty), 1050 primerange() (sympy.ntheory.generate.Sieve
pretty_atom() (in module method), 306
sympy.printing.pretty.pretty_symbology),
primitive() (in module sympy.polys.polytools),
1084 839
pretty_print() (in module primitive() (sympy.core.add.Add method),
sympy.printing.pretty.pretty), 1050 165
pretty_symbol() (in module primitive() (sympy.core.expr.Expr method),
sympy.printing.pretty.pretty_symbology), 134
1084 primitive() (sympy.polys.polyclasses.DMP
pretty_try_use_unicode() (in module method), 948
sympy.printing.pretty.pretty_symbology),
primitive() (sympy.polys.polytools.Poly
1083 method), 876
pretty_use_unicode() (in module primitive() (sympy.polys.rings.PolyElement
sympy.printing.pretty.pretty_symbology), method), 1005
1083 primitive_element() (in module
prettyForm (class in sympy.polys.numberfields), 893
sympy.printing.pretty.stringpict), primitive_root() (in module
1086 sympy.ntheory.residue_ntheory),
PrettyPrinter (class in 334
sympy.printing.pretty.pretty), 1050 primorial() (in module
prev() (sympy.combinatorics.prufer.Prufer sympy.ntheory.generate), 311
method), 271 principal_branch (class in
prev_binary() (sympy.combinatorics.subsets.Subset sympy.functions.elementary.complexes),
method), 277 452
prev_gray() (sympy.combinatorics.subsets.Subset principal_value() (sympy.integrals.Integral
method), 277 method), 716
prev_lex() (sympy.combinatorics.partitions.IntegerPartition
Print (class in sympy.codegen.ast), 423
method), 211 print_ccode() (in module
prev_lexicographic() sympy.printing.ccode), 1054
(sympy.combinatorics.subsets.Subset print_dim_base() (sympy.physics.units.dimensions.Dimensio
method), 277 method), 1553

2016 Index
 SymPy Documentation, Release 1.3

print_fcode() (in module attribute), 1078

sympy.printing.fcode), 1059 printmethod (sympy.printing.rust.RustCodePrinter
print_gtk() (in module sympy.printing.gtk), attribute), 1069
1072 printmethod (sympy.printing.str.StrPrinter
print_latex() (in module sympy.printing.latex), attribute), 1079
1076 printmethod (sympy.printing.theanocode.TheanoPrinter
print_mathml() (in module attribute), 1071
sympy.printing.mathml), 1076 prob() (sympy.physics.quantum.state.Wavefunction
print_node() (in module sympy.printing.tree), method), 1749
1079 Probability (class in sympy.stats), 1253
print_nonzero() (sympy.matrices.matrices.MatrixBase
prod() (in module sympy.core.mul), 163
method), 776 Product (class in sympy.concrete.products),
print_rcode() (in module 374
sympy.printing.rcode), 1057 product() (in module
print_tree() (in module sympy.printing.tree), sympy.concrete.products), 380
1079 product() (sympy.polys.agca.ideals.Ideal
print_unit_base() (sympy.physics.units.unitsystem.UnitSystem
method), 920
method), 1554 ProductDomain (class in sympy.stats.rv),
Printer (class in sympy.printing.printer), 1049 1260
printmethod (sympy.printing.ccode.C89CodePrinterProductPSpace (class in sympy.stats.rv), 1260
attribute), 1051 ProductSet (class in sympy.sets.sets), 1174
printmethod (sympy.printing.ccode.C99CodePrinterProgram (class in sympy.codegen.fnodes),
attribute), 1051 436
printmethod (sympy.printing.codeprinter.CodePrinter
project() (sympy.geometry.point.Point static
attribute), 1083 method), 595
printmethod (sympy.printing.cxxcode.CXX11CodePrinter
project() (sympy.matrices.matrices.MatrixBase
attribute), 1054 method), 776
printmethod (sympy.printing.cxxcode.CXX98CodePrinter
projection() (sympy.geometry.line.LinearEntity
attribute), 1054 method), 611
printmethod (sympy.printing.fcode.FCodePrinter projection() (sympy.geometry.plane.Plane
attribute), 1059 method), 679
printmethod (sympy.printing.jscode.JavascriptCodePrinter
projection() (sympy.vector.vector.Vector
attribute), 1062 method), 1874
printmethod (sympy.printing.julia.JuliaCodePrinter
projection_line() (sympy.geometry.plane.Plane
attribute), 1064 method), 679
printmethod (sympy.printing.lambdarepr.LambdaPrinter
Prufer (class in sympy.combinatorics.prufer),
attribute), 1072 270
printmethod (sympy.printing.latex.LatexPrinter prufer_rank() (sympy.combinatorics.prufer.Prufer
attribute), 1072 method), 272
printmethod (sympy.printing.mathematica.MCodePrinter
prufer_repr (sympy.combinatorics.prufer.Prufer
attribute), 1061 attribute), 272
printmethod (sympy.printing.mathml.MathMLContentPrinter
psets (sympy.sets.fancysets.ComplexRegion
attribute), 1076 attribute), 1184
printmethod (sympy.printing.mathml.MathMLPresentationPrinter
psi_n() (in module sympy.physics.qho_1d),
attribute), 1076 1516
printmethod (sympy.printing.octave.OctaveCodePrinter
Psi_nlm() (in module
attribute), 1067 sympy.physics.hydrogen), 1512
printmethod (sympy.printing.pretty.pretty.PrettyPrinter
PSpace (class in sympy.stats.rv), 1260
attribute), 1050 pspace() (in module sympy.stats.rv), 1261
printmethod (sympy.printing.printer.Printer public() (in module sympy.utilities.decorator),
attribute), 1049 1450
printmethod (sympy.printing.rcode.RCodePrinter PurePoly (class in sympy.polys.polytools), 887
attribute), 1055 PxBra (class in sympy.physics.quantum.cartesian),
printmethod (sympy.printing.repr.ReprPrinter 1717

Index 2017
SymPy Documentation, Release 1.3

PxKet (class in sympy.physics.quantum.cartesian),

quo() (sympy.polys.polyclasses.DMP method),
1717 949
PxOp (class in sympy.physics.quantum.cartesian),
quo() (sympy.polys.polytools.Poly method),
1717 877
pycode() (in module sympy.printing.pycode), quo_ground() (sympy.polys.polyclasses.DMP
1077 method), 949
PyTestReporter (class in quo_ground() (sympy.polys.polytools.Poly
sympy.utilities.runtests), 1488 method), 877
Python Enhancement Proposals QuotedString (class in sympy.codegen.ast),
PEP 335, 1934, 1935 423
PythonFiniteField (class in quotient() (sympy.polys.agca.ideals.Ideal
sympy.polys.domains), 944 method), 920
PythonIntegerRing (class in quotient_codomain()
sympy.polys.domains), 944 (sympy.polys.agca.homomorphisms.ModuleHomomo
PythonRationalField (class in method), 928
sympy.polys.domains), 944 quotient_domain() (sympy.polys.agca.homomorphisms.Modu
method), 929
Q quotient_hom() (sympy.polys.agca.modules.QuotientModule
q (sympy.physics.optics.gaussopt.BeamParameter method), 922
attribute), 1771 quotient_hom() (sympy.polys.agca.modules.SubQuotientMod
qapply() (in module method), 923
sympy.physics.quantum.qapply), quotient_module() (sympy.polys.agca.modules.FreeModule
1726 method), 914
QFT (class in sympy.physics.quantum.qft), quotient_module() (sympy.polys.agca.modules.Module
1758 method), 913
quotient_module() (sympy.polys.agca.modules.SubModule
QRdecomposition() (sympy.matrices.matrices.MatrixBase
method), 766 method), 917
QRsolve() (sympy.matrices.matrices.MatrixBasequotient_ring() (sympy.polys.domains.ring.Ring
method), 767 method), 936
quadratic_residues() (in module QuotientModule (class in
sympy.ntheory.residue_ntheory), sympy.polys.agca.modules), 921
335
QuadraticU() (in module sympy.stats), 1244 R
Quantity (class in R_nl() (in module sympy.physics.hydrogen),
sympy.physics.units.quantities), 1512
1554 R_nl() (in module sympy.physics.sho), 1517
QuaternionOrienter (class in racah() (in module sympy.physics.wigner),
sympy.vector.orienters), 1881 1541
Qubit (class in sympy.physics.quantum.qubit), rad_rationalize() (in module
1758 sympy.simplify.radsimp), 1194
qubit_to_matrix() (in module radical() (sympy.polys.agca.ideals.Ideal
sympy.physics.quantum.qubit), 1760 method), 921
QubitBra (class in radius (sympy.geometry.ellipse.Circle at-
sympy.physics.quantum.qubit), 1759 tribute), 649
quo() (in module sympy.polys.polytools), 831 radius (sympy.geometry.polygon.RegularPolygon
quo() (sympy.polys.domains.domain.Domain attribute), 662
method), 933 radius (sympy.physics.optics.gaussopt.BeamParameter
quo() (sympy.polys.domains.field.Field attribute), 1771
method), 935 radius_of_convergence
quo() (sympy.polys.domains.ring.Ring (sympy.functions.special.hyper.hyper
method), 936 attribute), 554
quo() (sympy.polys.polyclasses.DMF method), radsimp() (in module
951 sympy.simplify.radsimp), 1192

2018 Index
 SymPy Documentation, Release 1.3

radsimp() (sympy.core.expr.Expr method), method), 741

135 rank_binary (sympy.combinatorics.subsets.Subset
RaisedCosine() (in module sympy.stats), 1245 attribute), 277
raises() (in module sympy.utilities.pytest), rank_gray (sympy.combinatorics.subsets.Subset
1486 attribute), 278
randMatrix() (in module rank_lexicographic (sympy.combinatorics.subsets.Subset
sympy.matrices.dense), 783 attribute), 278
random() (sympy.combinatorics.perm_groups.PermutationGroup
rank_nonlex() (sympy.combinatorics.permutations.Permutat
method), 260 method), 232
random() (sympy.combinatorics.permutations.Permutation
rank_trotterjohnson()
class method), 231 (sympy.combinatorics.permutations.Permutation
random_bitstring() (sympy.combinatorics.graycode method), 232
method), 284 rat_clear_denoms() (sympy.polys.polytools.Poly
random_circuit() (in module method), 877
sympy.physics.quantum.gate), 1755 rational, 99
random_complex_number() (in module Rational (class in sympy.core.numbers), 145
sympy.utilities.randtest), 1487 rational (sympy.assumptions.ask.AssumptionKeys
random_integer_partition() (in module attribute), 1116
sympy.combinatorics.partitions), rational_algorithm() (in module
211 sympy.series.formal), 1156
random_point() (sympy.geometry.ellipse.Ellipse rational_independent() (in module
method), 644 sympy.series.formal), 1156
random_point() (sympy.geometry.line.LinearEntity
RationalField (class in sympy.polys.domains),
method), 611 940
random_point() (sympy.geometry.plane.Plane rationalize() (in module
method), 680 sympy.parsing.sympy_parser), 1499
random_poly() (in module ratsimp() (in module sympy.simplify.ratsimp),
sympy.polys.specialpolys), 898 1199
random_pr() (sympy.combinatorics.perm_groups.PermutationGroup
ratsimp() (sympy.core.expr.Expr method),
method), 260 135
random_stab() (sympy.combinatorics.perm_groups.PermutationGroup
rawlines() (in module sympy.utilities.misc),
method), 261 1483
random_symbols() (in module sympy.stats.rv), Ray (class in sympy.geometry.line), 615
1261 Ray2D (class in sympy.geometry.line), 623
RandomDomain (class in sympy.stats.rv), Ray3D (class in sympy.geometry.line), 628
1260 Rayleigh() (in module sympy.stats), 1245
RandomSymbol (class in sympy.stats.rv), rayleigh2waist() (in module
1260 sympy.physics.optics.gaussopt),
randprime() (in module 1773
sympy.ntheory.generate), 310 RayTransferMatrix (class in
Range (class in sympy.sets.fancysets), 1180 sympy.physics.optics.gaussopt),
ranges (sympy.tensor.indexed.Indexed at- 1764
tribute), 1409 rcall() (sympy.core.basic.Basic method), 108
rank (sympy.combinatorics.graycode.GrayCode rcode() (in module sympy.printing.rcode),
attribute), 282 1055
rank (sympy.combinatorics.partitions.Partition RCodePrinter (class in sympy.printing.rcode),
attribute), 209 1055
rank (sympy.combinatorics.prufer.Prufer at- rcollect() (in module sympy.simplify.radsimp),
tribute), 272 1196
rank (sympy.tensor.indexed.Indexed at- re (class in sympy.functions.elementary.complexes),
tribute), 1410 447
rank() (sympy.combinatorics.permutations.Permutation
reaction_loads (sympy.physics.continuum_mechanics.beam.B
method), 231 attribute), 1794
rank() (sympy.liealgebras.cartan_type.Standard_Cartan
real, 99

Index 2019
SymPy Documentation, Release 1.3

real (sympy.assumptions.ask.AssumptionKeys sympy.assumptions.refine), 1124

attribute), 1116 refine_Relational() (in module
real_elements (sympy.assumptions.ask.AssumptionKeyssympy.assumptions.refine), 1124
attribute), 1117 refine_root() (in module
real_root() (in module sympy.polys.polytools), 843
sympy.functions.elementary.miscellaneous),
refine_root() (sympy.polys.polyclasses.DMP
478 method), 949
real_roots() (in module refine_root() (sympy.polys.polytools.Poly
sympy.polys.polytools), 844 method), 878
real_roots() (sympy.polys.polytools.Poly RefinementFailed (class in
method), 878 sympy.polys.polyerrors), 1026
RealField (class in sympy.polys.domains), 942 reflect() (sympy.geometry.ellipse.Circle
RealNumber (in module method), 649
sympy.core.numbers), 148 reflect() (sympy.geometry.ellipse.Ellipse
reconstruct() (in module method), 644
sympy.solvers.diophantine), 1372 reflect() (sympy.geometry.entity.GeometryEntity
recurrence_memo() (in module method), 585
sympy.utilities.memoization), 1482 reflect() (sympy.geometry.polygon.RegularPolygon
red_groebner() (in module method), 663
sympy.polys.groebnertools), 1024 refraction_angle() (in module
reduce() (sympy.polys.polytools.GroebnerBasis sympy.physics.optics.utils), 1777
method), 888 refractive_index (sympy.physics.optics.medium.Medium
reduce() (sympy.series.sequences.SeqAdd attribute), 1777
static method), 1149 register_handler() (in module
reduce() (sympy.series.sequences.SeqMul sympy.assumptions.ask), 1121
static method), 1150 RegularPolygon (class in
reduce() (sympy.sets.sets.Complement static sympy.geometry.polygon), 657
method), 1175 Rel (in module sympy.core.relational), 166
reduce_abs_inequalities() (in module rem() (in module sympy.polys.polytools), 831
sympy.solvers.inequalities), 1373 rem() (sympy.polys.domains.domain.Domain
reduce_abs_inequality() (in module method), 934
sympy.solvers.inequalities), 1373 rem() (sympy.polys.domains.field.Field
reduce_element() (sympy.polys.agca.ideals.Ideal method), 935
method), 921 rem() (sympy.polys.domains.ring.Ring
reduce_element() (sympy.polys.agca.modules.SubModule method), 936
method), 918 rem() (sympy.polys.polyclasses.DMP
reduce_inequalities() (in module method), 949
sympy.solvers.inequalities), 1374 rem() (sympy.polys.polytools.Poly method),
reduce_rational_inequalities() (in module 878
sympy.solvers.inequalities), 1373 remove_handler() (in module
reduced() (in module sympy.polys.polytools), sympy.assumptions.ask), 1121
845 remove_load() (sympy.physics.continuum_mechanics.beam.B
reduced_totient (class in method), 1794
sympy.ntheory.factor_), 325 removeO() (sympy.core.expr.Expr method),
ReferenceFrame (class in 135
sympy.physics.vector.frame), 1594 render() (sympy.printing.pretty.stringpict.stringPict
refine() (in module method), 1085
sympy.assumptions.refine), 1123 render_as_module() (in module
refine() (sympy.core.expr.Expr method), 135 sympy.codegen.futils), 443
refine_abs() (in module render_as_module() (in module
sympy.assumptions.refine), 1124 sympy.codegen.pyutils), 443
refine_atan2() (in module render_as_source_file() (in module
sympy.assumptions.refine), 1124 sympy.codegen.cutils), 443
refine_Pow() (in module reorder() (sympy.polys.polytools.Poly

2020 Index
 SymPy Documentation, Release 1.3

method), 878 method), 373

rep_expectation() (in module reversed (sympy.sets.fancysets.Range at-
sympy.physics.quantum.represent), tribute), 1181
1729 ReversedGradedLexOrder (class in
rep_innerproduct() (in module sympy.polys.orderings), 895
sympy.physics.quantum.represent), revert() (sympy.polys.domains.domain.Domain
1729 method), 934
repeated_decimals() (in module revert() (sympy.polys.domains.field.Field
sympy.parsing.sympy_parser), 1499 method), 935
replace() (in module sympy.utilities.misc), revert() (sympy.polys.domains.ring.Ring
1484 method), 936
replace() (sympy.core.basic.Basic method), revert() (sympy.polys.polyclasses.DMP
108 method), 949
replace() (sympy.polys.polytools.Poly revert() (sympy.polys.polytools.Poly method),
method), 879 880
ReplaceOptim (class in rewrite() (in module sympy.series.gruntz),
sympy.codegen.rewriting), 410 1138
Reporter (class in sympy.utilities.runtests), rewrite() (sympy.core.basic.Basic method),
1488 110
represent() (in module RGS (sympy.combinatorics.partitions.Partition
sympy.physics.quantum.represent), attribute), 208
1727 RGS_enum() (in module
reprify() (sympy.printing.repr.ReprPrinter sympy.combinatorics.partitions),
method), 1078 212
ReprPrinter (class in sympy.printing.repr), RGS_generalized() (in module
1078 sympy.combinatorics.partitions),
reset() (sympy.combinatorics.polyhedron.Polyhedron 211
method), 268 RGS_rank() (in module
reshape() (in module sympy.codegen.fnodes), sympy.combinatorics.partitions),
439 213
reshape() (in module RGS_unrank() (in module
sympy.utilities.iterables), 1472 sympy.combinatorics.partitions),
residue() (in module sympy.series.residues), 212
1144 rhs() (sympy.physics.mechanics.kane.KanesMethod
restrict_codomain() (sympy.polys.agca.homomorphisms.ModuleHomomorphism
method), 1694
method), 929 rhs() (sympy.physics.mechanics.lagrange.LagrangesMethod
method), 1697
restrict_domain() (sympy.polys.agca.homomorphisms.ModuleHomomorphism
method), 929 richardson() (in module
Result (class in sympy.utilities.codegen), sympy.series.acceleration), 1143
1440 riemann_cyclic() (in module
result_variables (sympy.utilities.codegen.Routine sympy.tensor.tensor), 1430
attribute), 1439 riemann_cyclic_replace() (in module
resultant() (in module sympy.polys.polytools), sympy.tensor.tensor), 1430
833 right (sympy.sets.sets.Interval attribute),
resultant() (sympy.polys.polyclasses.DMP 1171
method), 949 right() (sympy.printing.pretty.stringpict.stringPict
resultant() (sympy.polys.polytools.Poly method), 1085
method), 879 right_open (sympy.sets.sets.Interval at-
retract() (sympy.polys.polytools.Poly tribute), 1171
method), 879 RigidBody (class in
Return (class in sympy.codegen.ast), 423 sympy.physics.mechanics.rigidbody),
reverse_order() (sympy.concrete.products.Product 1684
method), 378 Ring (class in sympy.polys.domains.ring), 935
reverse_order() (sympy.concrete.summations.Sum ring() (in module sympy.polys.rings), 998

Index 2021
SymPy Documentation, Release 1.3

RisingFactorial (class in rot_axis3() (in module sympy.matrices.dense),

sympy.functions.combinatorial.factorials), 786
494 rotate() (sympy.combinatorics.polyhedron.Polyhedron
Rk (in module sympy.physics.quantum.qft), method), 269
1758 rotate() (sympy.geometry.curve.Curve
RkGate (class in sympy.physics.quantum.qft), method), 634
1758 rotate() (sympy.geometry.ellipse.Ellipse
RL (sympy.matrices.sparse.SparseMatrix at- method), 645
tribute), 793 rotate() (sympy.geometry.entity.GeometryEntity
rmul() (sympy.combinatorics.permutations.Permutationmethod), 585
static method), 232 rotate() (sympy.geometry.point.Point2D
rmul_with_af() (sympy.combinatorics.permutations.Permutation
method), 597
class method), 233 rotate() (sympy.geometry.polygon.RegularPolygon
root (in module sympy.printing.pretty.pretty_symbology), method), 663
1084 rotate_left() (in module
root() (in module sympy.utilities.iterables), 1473
sympy.functions.elementary.miscellaneous),
rotate_right() (in module
475 sympy.utilities.iterables), 1473
root() (sympy.polys.polytools.Poly method), Rotation (class in
880 sympy.physics.quantum.spin), 1731
root() (sympy.printing.pretty.stringpict.stringPict
rotation (sympy.geometry.polygon.RegularPolygon
method), 1085 attribute), 663
root_space() (sympy.liealgebras.root_system.RootSystem
rotation_matrix() (sympy.vector.coordsysrect.CoordSys3D
method), 729 method), 1871
RootOf (class in sympy.polys.rootoftools), 895 rotation_matrix() (sympy.vector.orienters.AxisOrienter
rootof() (in module sympy.polys.rootoftools), method), 1879
895 rotation_matrix() (sympy.vector.orienters.Orienter
roots() (in module sympy.polys.polyroots), method), 1878
897 round() (sympy.core.expr.Expr method), 135
roots() (sympy.liealgebras.type_a.TypeA RoundFunction (class in
method), 730 sympy.functions.elementary.integers),
roots() (sympy.liealgebras.type_b.TypeB 469
method), 732 Routine (class in sympy.utilities.codegen),
roots() (sympy.liealgebras.type_c.TypeC 1439
method), 733 routine() (sympy.utilities.codegen.CodeGen
roots() (sympy.liealgebras.type_d.TypeD method), 1440
method), 735 routine() (sympy.utilities.codegen.JuliaCodeGen
roots() (sympy.liealgebras.type_e.TypeE method), 1444
method), 736 routine() (sympy.utilities.codegen.OctaveCodeGen
roots() (sympy.liealgebras.type_f.TypeF method), 1445
method), 737 routine() (sympy.utilities.codegen.RustCodeGen
roots() (sympy.liealgebras.type_g.TypeG method), 1445
method), 738 row_del() (sympy.matrices.dense.MutableDenseMatrix
RootSum (class in sympy.polys.rootoftools), method), 789
897 row_del() (sympy.matrices.sparse.MutableSparseMatrix
RootSystem (class in method), 799
sympy.liealgebras.root_system), row_join() (sympy.matrices.sparse.MutableSparseMatrix
727 method), 799
Ropen() (sympy.sets.sets.Interval class row_list() (sympy.matrices.sparse.SparseMatrix
method), 1170 method), 795
rot_axis1() (in module sympy.matrices.dense), row_op() (sympy.matrices.dense.MutableDenseMatrix
785 method), 790
rot_axis2() (in module sympy.matrices.dense), row_op() (sympy.matrices.sparse.MutableSparseMatrix
786 method), 800

2022 Index
 SymPy Documentation, Release 1.3

row_structure_symbolic_cholesky() sympy.polys.ring_series), 1040

(sympy.matrices.sparse.SparseMatrix rs_series_reversion() (in module
method), 795 sympy.polys.ring_series), 1041
row_swap() (sympy.matrices.dense.MutableDenseMatrix
rs_sin() (in module sympy.polys.ring_series),
method), 790 1037
row_swap() (sympy.matrices.sparse.MutableSparseMatrix
rs_sinh() (in module sympy.polys.ring_series),
method), 800 1038
rs_asin() (in module sympy.polys.ring_series), rs_square() (in module
1036 sympy.polys.ring_series), 1040
rs_atan() (in module sympy.polys.ring_series), rs_subs() (in module
1036 sympy.polys.ring_series), 1042
rs_atanh() (in module rs_swap() (in module sympy.stats.rv), 1261
sympy.polys.ring_series), 1038 rs_tan() (in module sympy.polys.ring_series),
rs_compose_add() (in module 1036
sympy.polys.ring_series), 1044 rs_tanh() (in module sympy.polys.ring_series),
rs_cos() (in module sympy.polys.ring_series), 1039
1037 rs_trunc() (in module
rs_cos_sin() (in module sympy.polys.ring_series), 1042
sympy.polys.ring_series), 1038 rsa_private_key() (in module
rs_cosh() (in module sympy.crypto.crypto), 357
sympy.polys.ring_series), 1039 rsa_public_key() (in module
rs_cot() (in module sympy.polys.ring_series), sympy.crypto.crypto), 357
1037 rsolve() (in module sympy.solvers.recurr),
rs_diff() (in module sympy.polys.ring_series), 1343
1043 rsolve_hyper() (in module
rs_exp() (in module sympy.polys.ring_series), sympy.solvers.recurr), 1345
1036 rsolve_hypergeometric() (in module
rs_fun() (in module sympy.polys.ring_series), sympy.series.formal), 1158
1045 rsolve_poly() (in module
rs_hadamard_exp() (in module sympy.solvers.recurr), 1344
sympy.polys.ring_series), 1039 rsolve_ratio() (in module
rs_integrate() (in module sympy.solvers.recurr), 1344
sympy.polys.ring_series), 1043 run() (sympy.utilities.runtests.SymPyDocTestRunner
rs_is_puiseux() (in module method), 1488
sympy.polys.ring_series), 1044 run_all_tests() (in module
rs_LambertW() (in module sympy.utilities.runtests), 1490
sympy.polys.ring_series), 1035 run_in_subprocess_with_hash_randomization()
rs_log() (in module sympy.polys.ring_series), (in module sympy.utilities.runtests),
1035 1490
rs_mul() (in module sympy.polys.ring_series), runs() (in module sympy.utilities.iterables),
1040 1473
rs_newton() (in module runs() (sympy.combinatorics.permutations.Permutation
sympy.polys.ring_series), 1043 method), 233
rs_nth_root() (in module rust_code() (in module sympy.printing.rust),
sympy.polys.ring_series), 1041 1069
rs_pow() (in module sympy.polys.ring_series), RustCodeGen (class in
1040 sympy.utilities.codegen), 1445
rs_puiseux() (in module RustCodePrinter (class in
sympy.polys.ring_series), 1044 sympy.printing.rust), 1069
rs_puiseux2() (in module
sympy.polys.ring_series), 1045 S
rs_series_from_list() (in module S (in module sympy.physics.quantum.gate),
sympy.polys.ring_series), 1045 1754
rs_series_inversion() (in module sample() (in module sympy.stats), 1259

Index 2023
SymPy Documentation, Release 1.3

sample_iter() (in module sympy.stats), 1259 sympy.polys.distributedmodules),

satisfiable() (in module 1009
sympy.logic.inference), 753 sdm_ecart() (in module
saturate() (sympy.polys.agca.ideals.Ideal sympy.polys.distributedmodules),
method), 921 1025
scalar_map() (sympy.vector.coordsysrect.CoordSys3D
sdm_from_dict() (in module
method), 1872 sympy.polys.distributedmodules),
scalar_multiply() (sympy.matrices.sparse.SparseMatrix 1007
method), 795 sdm_from_vector() (in module
scalar_potential() (in module sympy.polys.distributedmodules),
sympy.physics.vector.fieldfunctions), 1009
1623 sdm_groebner() (in module
scalar_potential() (in module sympy.vector), sympy.polys.distributedmodules),
1885 1025
scalar_potential_difference() (in module sdm_LC() (in module
sympy.physics.vector.fieldfunctions), sympy.polys.distributedmodules),
1624 1007
scalar_potential_difference() (in module sdm_LM() (in module
sympy.vector), 1886 sympy.polys.distributedmodules),
scale() (sympy.geometry.curve.Curve 1008
method), 634 sdm_LT() (in module
scale() (sympy.geometry.ellipse.Circle sympy.polys.distributedmodules),
method), 649 1008
scale() (sympy.geometry.ellipse.Ellipse sdm_monomial_deg() (in module
method), 645 sympy.polys.distributedmodules),
scale() (sympy.geometry.entity.GeometryEntity 1006
method), 586 sdm_monomial_divides() (in module
scale() (sympy.geometry.point.Point2D sympy.polys.distributedmodules),
method), 597 1006
scale() (sympy.geometry.point.Point3D sdm_monomial_mul() (in module
method), 601 sympy.polys.distributedmodules),
scale() (sympy.geometry.polygon.RegularPolygon 1006
method), 664 sdm_mul_term() (in module
scale() (sympy.series.fourier.FourierSeries sympy.polys.distributedmodules),
method), 1150 1009
scale_factor (sympy.physics.units.quantities.Quantity
sdm_nf_mora() (in module
attribute), 1554 sympy.polys.distributedmodules),
scalex() (sympy.series.fourier.FourierSeries 1025
method), 1150 sdm_spoly() (in module
schreier_sims() (sympy.combinatorics.perm_groups.PermutationGroup
sympy.polys.distributedmodules),
method), 261 1024
schreier_sims_incremental() sdm_to_dict() (in module
(sympy.combinatorics.perm_groups.PermutationGroup
sympy.polys.distributedmodules),
method), 261 1007
schreier_sims_random() sdm_to_vector() (in module
(sympy.combinatorics.perm_groups.PermutationGroup
sympy.polys.distributedmodules),
method), 262 1010
schreier_vector() (sympy.combinatorics.perm_groups.PermutationGroup
sdm_zero() (in module
method), 263 sympy.polys.distributedmodules),
Scope (class in sympy.codegen.ast), 423 1009
sdm_add() (in module search() (sympy.ntheory.generate.Sieve
sympy.polys.distributedmodules), method), 306
1008 search_function (sympy.physics.quantum.grover.OracleGate
sdm_deg() (in module attribute), 1756

2024 Index
 SymPy Documentation, Release 1.3

sec (class in sympy.functions.elementary.trigonometric),

Set (class in sympy.sets.sets), 1162
456 set_acc() (sympy.physics.vector.point.Point
sech (class in sympy.functions.elementary.hyperbolic), method), 1609
465 set_ang_acc() (sympy.physics.vector.frame.ReferenceFrame
second_moment (sympy.physics.continuum_mechanics.beam.Beammethod), 1598
attribute), 1795 set_ang_vel() (sympy.physics.vector.frame.ReferenceFrame
second_moment (sympy.physics.continuum_mechanics.beam.Beam3D
method), 1598
attribute), 1800 set_comm() (sympy.tensor.tensor._TensorManager
second_moment_of_area() method), 1416
(sympy.geometry.ellipse.Ellipse set_comms() (sympy.tensor.tensor._TensorManager
method), 645 method), 1416
second_moment_of_area() set_domain() (sympy.polys.polytools.Poly
(sympy.geometry.polygon.Polygon method), 881
method), 655 set_global_settings()
Segment (class in sympy.geometry.line), 617 (sympy.printing.printer.Printer class
Segment2D (class in sympy.geometry.line), method), 1050
625 set_modulus() (sympy.polys.polytools.Poly
Segment3D (class in sympy.geometry.line), method), 881
630 set_pos() (sympy.physics.vector.point.Point
select() (sympy.simplify.epathtools.EPath method), 1609
method), 1209 set_vel() (sympy.physics.vector.point.Point
selections (sympy.combinatorics.graycode.GrayCode method), 1610
attribute), 283 seterr() (in module sympy.core.numbers), 149
semilatus_rectum (sympy.geometry.ellipse.Ellipsesets (sympy.sets.fancysets.ComplexRegion
attribute), 646 attribute), 1184
separate() (sympy.core.expr.Expr method), shanks() (in module
136 sympy.series.acceleration), 1143
separate() (sympy.physics.vector.vector.Vector shape (sympy.tensor.indexed.Indexed at-
method), 1602 tribute), 1410
separate() (sympy.vector.vector.Vector shape (sympy.tensor.indexed.IndexedBase at-
method), 1874 tribute), 1412
separatevars() (in module shape() (in module sympy.codegen.fnodes),
sympy.simplify.simplify), 1187 439
SeqAdd (class in sympy.series.sequences), ShapeError (class in
1148 sympy.matrices.matrices), 779
SeqBase (class in sympy.series.sequences), shear_force() (sympy.physics.continuum_mechanics.beam.B
1145 method), 1795
SeqFormula (class in shear_force() (sympy.physics.continuum_mechanics.beam.B
sympy.series.sequences), 1146 method), 1800
SeqMul (class in sympy.series.sequences), shear_modulus (sympy.physics.continuum_mechanics.beam.
1149 attribute), 1800
SeqPer (class in sympy.series.sequences), Shi (class in sympy.functions.special.error_functions),
1147 532
sequence() (in module shift() (sympy.polys.polyclasses.DMP
sympy.series.sequences), 1144 method), 949
series() (in module sympy.series.series), 1140 shift() (sympy.polys.polytools.Poly method),
series() (sympy.core.expr.Expr method), 136 881
series() (sympy.holonomic.holonomic.HolonomicFunction
shift() (sympy.series.fourier.FourierSeries
method), 684 method), 1151
series() (sympy.liealgebras.cartan_type.Standard_Cartan
shiftx() (sympy.series.fourier.FourierSeries
method), 741 method), 1151
SeriesApprox (class in shor() (in module
sympy.codegen.approximations), sympy.physics.quantum.shor), 1763
411 Si (class in sympy.functions.special.error_functions),

Index 2025
SymPy Documentation, Release 1.3

529 simplify_logic() (in module

sides (sympy.geometry.polygon.Polygon at- sympy.logic.boolalg), 751
tribute), 656 sin (class in sympy.functions.elementary.trigonometric),
Sieve (class in sympy.ntheory.generate), 305 453
sift() (in module sympy.utilities.iterables), sinc (class in sympy.functions.elementary.trigonometric),
1474 457
sigma_approximation() sine_transform() (in module
(sympy.series.fourier.FourierSeries sympy.integrals.transforms), 693
method), 1151 SingleDomain (class in sympy.stats.rv), 1260
sign (class in sympy.functions.elementary.complexes),
SinglePSpace (class in sympy.stats.rv), 1260
449 SingletonRegistry (class in
sign() (in module sympy.series.gruntz), 1138 sympy.core.singleton), 114
signature() (sympy.combinatorics.permutations.Permutation
singular (sympy.assumptions.ask.AssumptionKeys
method), 233 attribute), 1117
signed_permutations() (in module singularities() (in module
sympy.utilities.iterables), 1475 sympy.calculus.singularities), 1504
SignedIntType (class in sympy.codegen.ast), SingularityFunction (class in
423 sympy.functions.special.singularity_functions),
simple_root() (sympy.liealgebras.type_a.TypeA 503
method), 730 sinh (class in sympy.functions.elementary.hyperbolic),
simple_root() (sympy.liealgebras.type_b.TypeB 464
method), 732 size (sympy.combinatorics.permutations.Permutation
simple_root() (sympy.liealgebras.type_c.TypeC attribute), 234
method), 733 size (sympy.combinatorics.polyhedron.Polyhedron
simple_root() (sympy.liealgebras.type_d.TypeD attribute), 270
method), 735 size (sympy.combinatorics.prufer.Prufer at-
simple_root() (sympy.liealgebras.type_e.TypeE tribute), 273
method), 736 size (sympy.combinatorics.subsets.Subset at-
simple_root() (sympy.liealgebras.type_f.TypeF tribute), 278
method), 737 size() (in module sympy.codegen.fnodes), 440
simple_root() (sympy.liealgebras.type_g.TypeG sizeof() (in module sympy.codegen.cnodes),
method), 739 433
simple_roots() (sympy.liealgebras.root_system.RootSystem
SKIP() (in module sympy.utilities.pytest),
method), 729 1486
simpleDE() (in module sympy.series.formal), skip() (sympy.combinatorics.graycode.GrayCode
1157 method), 283
SimpleDomain (class in slice() (sympy.polys.polyclasses.DMP
sympy.polys.domains.simpledomain), method), 949
936 slice() (sympy.polys.polytools.Poly method),
simplify() (in module sympy.simplify.simplify), 881
1185 slope (sympy.geometry.line.LinearEntity2D
simplify() (sympy.core.expr.Expr method), attribute), 621
137 slope() (sympy.physics.continuum_mechanics.beam.Beam
simplify() (sympy.matrices.dense.MutableDenseMatrix method), 1796
method), 790 slope() (sympy.physics.continuum_mechanics.beam.Beam3D
simplify() (sympy.physics.vector.dyadic.Dyadic method), 1800
method), 1605 smallest_angle_between()
simplify() (sympy.physics.vector.vector.Vector (sympy.geometry.line.LinearEntity
method), 1602 method), 612
simplify_gpgp() (in module smoothness() (in module
sympy.physics.hep.gamma_matrices), sympy.ntheory.factor_), 313
1558 smoothness_p() (in module
simplify_index_permutations() (in module sympy.ntheory.factor_), 313
sympy.physics.secondquant), 1537 solve() (in module sympy.solvers.solvers),

2026 Index
 SymPy Documentation, Release 1.3

1328 110
solve() (sympy.matrices.matrices.MatrixBase sorted_components()
method), 776 (sympy.tensor.tensor.TensMul
solve() (sympy.matrices.sparse.SparseMatrix method), 1429
method), 796 source (sympy.geometry.line.Ray attribute),
solve_congruence() (in module 617
sympy.ntheory.modular), 330 source() (in module sympy.utilities.source),
solve_de() (in module sympy.series.formal), 1495
1159 SpaceOrienter (class in
solve_for_reaction_loads() sympy.vector.orienters), 1880
SparseMatrix
(sympy.physics.continuum_mechanics.beam.Beam (class in
method), 1796 sympy.matrices.sparse), 792
solve_for_reaction_loads() speed (sympy.physics.optics.medium.Medium
(sympy.physics.continuum_mechanics.beam.Beam3D attribute), 1777
method), 1800 speed (sympy.physics.optics.waves.TWave at-
solve_least_squares() tribute), 1783
(sympy.matrices.matrices.MatrixBase speeds (sympy.physics.mechanics.system.SymbolicSystem
method), 776 attribute), 1702
solve_least_squares() spin() (sympy.geometry.polygon.RegularPolygon
(sympy.matrices.sparse.SparseMatrix method), 664
method), 796 split() (sympy.tensor.tensor.TensMul method),
solve_linear() (in module 1429
sympy.solvers.solvers), 1336 split_list() (in module
solve_linear_system() (in module sympy.utilities.runtests), 1491
sympy.solvers.solvers), 1337 split_super_sub() (in module
solve_linear_system_LU() (in module sympy.printing.conventions), 1082
sympy.solvers.solvers), 1338 split_symbols() (in module
sympy.parsing.sympy_parser), 1497
solve_multipliers() (sympy.physics.mechanics.lagrange.LagrangesMethod
method), 1697 split_symbols_custom() (in module
solve_poly_inequality() (in module sympy.parsing.sympy_parser), 1497
sympy.solvers.inequalities), 1372 spoly() (in module
solve_poly_system() (in module sympy.polys.groebnertools), 1024
sympy.solvers.polysys), 1346 sqf() (in module sympy.polys.polytools), 841
solve_rational_inequalities() (in module sqf_list() (in module sympy.polys.polytools),
sympy.solvers.inequalities), 1372 841
solve_triangulated() (in module sqf_list() (sympy.polys.polyclasses.DMP
sympy.solvers.polysys), 1346 method), 949
solve_undetermined_coeffs() (in module sqf_list() (sympy.polys.polytools.Poly
sympy.solvers.solvers), 1338 method), 881
solve_univariate_inequality() (in module sqf_list_include() (sympy.polys.polyclasses.DMP
sympy.solvers.inequalities), 1374 method), 949
solveset() (in module sympy.solvers.solveset), sqf_list_include() (sympy.polys.polytools.Poly
1383 method), 881
solveset_complex() (in module sqf_norm() (in module sympy.polys.polytools),
sympy.solvers.solveset), 1385 841
solveset_real() (in module sqf_norm() (sympy.polys.polyclasses.DMP
sympy.solvers.solveset), 1385 method), 949
SOPform() (in module sympy.logic.boolalg), sqf_norm() (sympy.polys.polytools.Poly
742 method), 882
sort_dims() (sympy.physics.units.dimensions.DimensionSystem
sqf_normal() (in module
static method), 1553 sympy.solvers.diophantine), 1371
sort_key() (sympy.combinatorics.partitions.Partition
sqf_part() (in module sympy.polys.polytools),
method), 209 841
sort_key() (sympy.core.basic.Basic method), sqf_part() (sympy.polys.polyclasses.DMP

Index 2027
SymPy Documentation, Release 1.3

method), 949 stieltjes (class in sympy.functions.special.zeta_functions),

sqf_part() (sympy.polys.polytools.Poly 552
method), 882 stirling() (in module
sqr() (sympy.polys.polyclasses.DMP method), sympy.functions.combinatorial.numbers),
949 495
sqr() (sympy.polys.polytools.Poly method), stop (sympy.series.sequences.SeqBase at-
883 tribute), 1146
Sqrt (class in sympy.codegen.cfunctions), 430 Stream (class in sympy.codegen.ast), 423
sqrt() (in module sympy.functions.elementary.miscellaneous),
StrictGreaterThan (class in
476 sympy.core.relational), 175
sqrt() (sympy.polys.domains.domain.Domain StrictLessThan (class in
method), 934 sympy.core.relational), 178
sqrt_mod() (in module strides (sympy.tensor.indexed.IndexedBase
sympy.ntheory.residue_ntheory), attribute), 1412
335 String (class in sympy.codegen.ast), 423
sqrtdenest() (in module stringify_expr() (in module
sympy.simplify.sqrtdenest), 1204 sympy.parsing.sympy_parser), 1497
square (sympy.assumptions.ask.AssumptionKeys stringPict (class in
attribute), 1117 sympy.printing.pretty.stringpict),
square() (sympy.polys.rings.PolyElement 1084
method), 1005 strip_zero() (sympy.polys.rings.PolyElement
square_factor() (in module method), 1005
sympy.solvers.diophantine), 1361 strong_gens (sympy.combinatorics.perm_groups.Permutatio
srepr() (in module sympy.printing.repr), 1078 attribute), 264
sring() (in module sympy.polys.rings), 999 strong_presentation()
sstrrepr() (in module sympy.printing.str), (sympy.combinatorics.perm_groups.PermutationGro
1079 method), 264
stabilizer() (sympy.combinatorics.perm_groups.PermutationGroup
StrPrinter (class in sympy.printing.str), 1079
method), 263 struct (class in sympy.codegen.cnodes), 434
stack() (sympy.printing.pretty.stringpict.stringPict
StudentT() (in module sympy.stats), 1246
static method), 1085 sturm() (in module sympy.polys.polytools),
Standard_Cartan (class in 840
sympy.liealgebras.cartan_type), sturm() (sympy.polys.polyclasses.DMP
741 method), 949
standard_transformations (in module sturm() (sympy.polys.polytools.Poly method),
sympy.parsing.sympy_parser), 1497 883
start (sympy.series.sequences.SeqBase at- sub (in module sympy.printing.pretty.pretty_symbology),
tribute), 1146 1083
start (sympy.sets.sets.Interval attribute), sub() (sympy.polys.domains.domain.Domain
1171 method), 934
State (class in sympy.physics.quantum.state), sub() (sympy.polys.polyclasses.DMF method),
1743 951
state() (sympy.physics.secondquant.FixedBosonicBasis
sub() (sympy.polys.polyclasses.DMP method),
method), 1529 949
state() (sympy.physics.secondquant.VarBosonicBasis
sub() (sympy.polys.polytools.Poly method),
method), 1528 883
state_to_operators() (in module sub_ground() (sympy.polys.polyclasses.DMP
sympy.physics.quantum.operatorset), method), 949
1725 sub_ground() (sympy.polys.polytools.Poly
StateBase (class in method), 883
sympy.physics.quantum.state), 1742 subdiagram_from_objects()
states (sympy.physics.mechanics.system.SymbolicSystem (sympy.categories.Diagram method),
attribute), 1702 1823
std() (in module sympy.stats), 1259 subfactorial (class in

2028 Index
 SymPy Documentation, Release 1.3

sympy.functions.combinatorial.factorials),
sum_of_four_squares() (in module
486 sympy.solvers.diophantine), 1365
subgroup() (sympy.combinatorics.perm_groups.PermutationGroup
sum_of_powers() (in module
method), 265 sympy.solvers.diophantine), 1365
subgroup_search() (sympy.combinatorics.perm_groups.PermutationGroup
sum_of_squares() (in module
method), 265 sympy.solvers.diophantine), 1366
SubModule (class in sum_of_three_squares() (in module
sympy.polys.agca.modules), 915 sympy.solvers.diophantine), 1364
submodule() (sympy.polys.agca.modules.ModuleSumApprox (class in
method), 913 sympy.codegen.approximations),
submodule() (sympy.polys.agca.modules.QuotientModule 411
method), 923 summation() (in module
submodule() (sympy.polys.agca.modules.SubModule sympy.concrete.summations), 379
method), 918 sup (in module sympy.printing.pretty.pretty_symbology),
SubQuotientModule (class in 1084
sympy.polys.agca.modules), 923 sup (sympy.sets.sets.Set attribute), 1167
subresultants() (in module superposition_basis() (in module
sympy.polys.polytools), 833 sympy.physics.quantum.grover),
subresultants() (sympy.polys.polyclasses.DMP 1756
method), 949 superset (sympy.combinatorics.subsets.Subset
subresultants() (sympy.polys.polytools.Poly attribute), 279
method), 884 superset_size (sympy.combinatorics.subsets.Subset
Subroutine (class in sympy.codegen.fnodes), attribute), 280
436 support() (sympy.combinatorics.permutations.Permutation
SubroutineCall (class in method), 234
sympy.codegen.fnodes), 437 SurfaceBaseSeries (class in
Subs (class in sympy.core.function), 191 sympy.plotting.plot), 1100
subs() (sympy.core.basic.Basic method), 111 SurfaceOver2DRangeSeries (class in
subs() (sympy.physics.vector.dyadic.Dyadic sympy.plotting.plot), 1100
method), 1605 SWAP (in module
subs() (sympy.physics.vector.vector.Vector sympy.physics.quantum.gate), 1754
method), 1603 SwapGate (class in
Subset (class in sympy.combinatorics.subsets), sympy.physics.quantum.gate), 1753
274 swinnerton_dyer_poly() (in module
subset (sympy.combinatorics.subsets.Subset sympy.polys.specialpolys), 898
attribute), 279 sylow_subgroup() (sympy.combinatorics.perm_groups.Permu
subset() (sympy.polys.agca.ideals.Ideal method), 266
method), 921 symarray() (in module
subset() (sympy.polys.agca.modules.Module sympy.matrices.dense), 784
method), 913 symb_2txt (in module
subset_from_bitlist() sympy.printing.pretty.pretty_symbology),
(sympy.combinatorics.subsets.Subset 1083
class method), 279 Symbol (class in sympy.core.symbol), 137
subset_indices() (sympy.combinatorics.subsets.Subset
symbol (sympy.physics.secondquant.AntiSymmetricTensor
class method), 279 attribute), 1536
subsets() (in module Symbol() (sympy.assumptions.handlers.calculus.AskFiniteHa
sympy.utilities.iterables), 1475 static method), 1127
SubsSet (class in sympy.series.gruntz), 1139 SymbolicSystem (class in
substitute_dummies() (in module sympy.physics.mechanics.system),
sympy.physics.secondquant), 1536 1698
substitute_indices() (sympy.tensor.tensor.TensAdd
symbols() (in module sympy.core.symbol),
method), 1427 139
Sum (class in sympy.concrete.summations), symmetric (sympy.assumptions.ask.AssumptionKeys
369 attribute), 1118

Index 2029
SymPy Documentation, Release 1.3

symmetric() (sympy.combinatorics.generators sympy.combinatorics.partitions (module),

method), 237 208
symmetric_difference() (sympy.sets.sets.Set sympy.combinatorics.perm_groups (module),
method), 1167 238
symmetric_poly() (in module sympy.combinatorics.permutations (module),
sympy.polys.specialpolys), 898 213
symmetric_residue() (in module sympy.combinatorics.polyhedron (module),
sympy.ntheory.modular), 329 267
SymmetricGroup() (in module sympy.combinatorics.prufer (module), 270
sympy.combinatorics.named_groups), sympy.combinatorics.subsets (module), 274
285 sympy.combinatorics.tensor_can (module),
symmetrize() (in module 295
sympy.polys.polyfuncs), 889 sympy.combinatorics.testutil (module), 294
sympify() (in module sympy.core.sympify), 95 sympy.combinatorics.util (module), 288
sympy (module), 801 sympy.core.add (module), 163
sympy.assumptions (module), 1105 sympy.core.assumptions (module), 98
sympy.assumptions.ask (module), 1105 sympy.core.basic (module), 100
sympy.assumptions.assume (module), 1121 sympy.core.cache (module), 100
sympy.assumptions.handlers (module), 1125 sympy.core.compatibility (module), 204
sympy.assumptions.handlers.calculus (mod- sympy.core.containers (module), 203
ule), 1125 sympy.core.core (module), 114
sympy.assumptions.handlers.ntheory (mod- sympy.core.evalf (module), 202
ule), 1127 sympy.core.expr (module), 115
sympy.assumptions.handlers.order (module), sympy.core.exprtools (module), 206
1127 sympy.core.function (module), 181
sympy.assumptions.handlers.sets (module), sympy.core.mod (module), 166
1128 sympy.core.mul (module), 160
sympy.assumptions.refine (module), 1123 sympy.core.multidimensional (module), 181
sympy.calculus (module), 1501 sympy.core.numbers (module), 142
sympy.calculus.euler (module), 1501 sympy.core.power (module), 157
sympy.calculus.finite_diff (module), 1505 sympy.core.relational (module), 166
sympy.calculus.singularities (module), 1502 sympy.core.singleton (module), 114
sympy.categories (module), 1815 sympy.core.symbol (module), 137
sympy.categories.diagram_drawing (module), sympy.core.sympify (module), 95
1823 sympy.crypto.crypto (module), 343
sympy.codegen.algorithms (module), 441 sympy.diffgeom (module), 1832
sympy.codegen.approximations (module), sympy.discrete (module), 382
411 sympy.discrete.convolutions (module), 388
sympy.codegen.ast (module), 412 sympy.discrete.transforms (module), 382
sympy.codegen.cfunctions (module), 429 sympy.functions (module), 446
sympy.codegen.cnodes (module), 433 sympy.functions.special.bessel (module), 534
sympy.codegen.cutils (module), 443 sympy.functions.special.beta_functions (mod-
sympy.codegen.cxxnodes (module), 434 ule), 512
sympy.codegen.fnodes (module), 434 sympy.functions.special.elliptic_integrals
sympy.codegen.futils (module), 443 (module), 557
sympy.codegen.pyutils (module), 443 sympy.functions.special.error_functions
sympy.codegen.rewriting (module), 409 (module), 514
sympy.combinatorics.generators (module), sympy.functions.special.gamma_functions
237 (module), 505
sympy.combinatorics.graycode (module), 281 sympy.functions.special.mathieu_functions
sympy.combinatorics.group_constructs (mod- (module), 560
ule), 294 sympy.functions.special.polynomials (mod-
sympy.combinatorics.named_groups (mod- ule), 563
ule), 285

2030 Index
 SymPy Documentation, Release 1.3

sympy.functions.special.singularity_functions sympy.physics.mechanics.linearize (module),

(module), 503 1702
sympy.functions.special.zeta_functions (mod- sympy.physics.mechanics.particle (module),
ule), 547 1681
sympy.geometry.curve (module), 631 sympy.physics.mechanics.rigidbody (mod-
sympy.geometry.ellipse (module), 635 ule), 1684
sympy.geometry.entity (module), 584 sympy.physics.mechanics.system (module),
sympy.geometry.line (module), 602 1698
sympy.geometry.plane (module), 673 sympy.physics.optics.gaussopt (module),
sympy.geometry.point (module), 590 1764
sympy.geometry.polygon (module), 650 sympy.physics.optics.medium (module), 1775
sympy.geometry.util (module), 587 sympy.physics.optics.utils (module), 1777
sympy.holonomic (module), 680 sympy.physics.optics.waves (module), 1781
sympy.holonomic.holonomic (module), 681, sympy.physics.paulialgebra (module), 1515
682, 687, 688 sympy.physics.qho_1d (module), 1516
sympy.integrals (module), 689 sympy.physics.quantum.anticommutator
sympy.integrals.intpoly (module), 725 (module), 1708
sympy.integrals.meijerint_doc (module), 708 sympy.physics.quantum.cartesian (module),
sympy.integrals.transforms (module), 690 1717
sympy.liealgebras (module), 727 sympy.physics.quantum.cg (module), 1709
sympy.logic (module), 742 sympy.physics.quantum.circuitplot (module),
sympy.logic.inference (module), 752 1750
sympy.matrices (module), 754 sympy.physics.quantum.commutator (mod-
sympy.matrices.expressions (module), 803 ule), 1711
sympy.matrices.expressions.blockmatrix sympy.physics.quantum.constants (module),
(module), 809 1712
sympy.matrices.immutable (module), 802 sympy.physics.quantum.dagger (module),
sympy.matrices.matrices (module), 754 1713
sympy.matrices.sparse (module), 792 sympy.physics.quantum.gate (module), 1751
sympy.ntheory.continued_fraction (module), sympy.physics.quantum.grover (module),
338 1755
sympy.ntheory.egyptian_fraction (module), sympy.physics.quantum.hilbert (module),
341 1718
sympy.ntheory.factor_ (module), 313 sympy.physics.quantum.innerproduct (mod-
sympy.ntheory.generate (module), 305 ule), 1714
sympy.ntheory.modular (module), 329 sympy.physics.quantum.operator (module),
sympy.ntheory.multinomial (module), 331 1719
sympy.ntheory.partitions_ (module), 332 sympy.physics.quantum.operatorset (mod-
sympy.ntheory.primetest (module), 333 ule), 1724
sympy.ntheory.residue_ntheory (module), 334 sympy.physics.quantum.piab (module), 1764
sympy.physics (module), 1510 sympy.physics.quantum.qapply (module),
sympy.physics.continuum_mechanics.beam 1726
(module), 1785 sympy.physics.quantum.qft (module), 1758
sympy.physics.hep.gamma_matrices (mod- sympy.physics.quantum.qubit (module), 1758
ule), 1556 sympy.physics.quantum.represent (module),
sympy.physics.hydrogen (module), 1511 1727
sympy.physics.matrices (module), 1513 sympy.physics.quantum.shor (module), 1763
sympy.physics.mechanics.body (module), sympy.physics.quantum.spin (module), 1731
1705 sympy.physics.quantum.state (module), 1742
sympy.physics.mechanics.kane (module), sympy.physics.quantum.tensorproduct (mod-
1692 ule), 1715
sympy.physics.mechanics.lagrange (module), sympy.physics.secondquant (module), 1518
1695 sympy.physics.sho (module), 1516
sympy.physics.units.dimensions (module),

Index 2031
SymPy Documentation, Release 1.3

1550 sympy.simplify.simplify (module), 81

sympy.physics.units.prefixes (module), 1553 sympy.simplify.sqrtdenest (module), 1204
sympy.physics.units.quantities (module), sympy.simplify.traversaltools (module), 1208
1554 sympy.simplify.trigsimp (module), 1200
sympy.physics.units.unitsystem (module), sympy.solvers (module), 1328
1553 sympy.solvers.inequalities (module), 1372
sympy.physics.units.util (module), 1555 sympy.solvers.ode (module), 1316
sympy.physics.vector.functions (module), sympy.solvers.pde (module), 1327
1612 sympy.solvers.recurr (module), 1343
sympy.physics.vector.point (module), 1606 sympy.solvers.solveset (module), 1375
sympy.physics.wigner (module), 1538 sympy.stats (module), 1220
sympy.plotting.plot (module), 1087 sympy.stats.crv (module), 1261
sympy.plotting.pygletplot (module), 1101 sympy.stats.crv_types (module), 1261
sympy.printing.ccode (module), 1051 sympy.stats.Die() (in module
sympy.printing.codeprinter (module), 1082 sympy.stats.crv_types), 1261
sympy.printing.conventions (module), 1082 sympy.stats.frv (module), 1260
sympy.printing.cxxcode (module), 1054 sympy.stats.frv_types (module), 1261
sympy.printing.fcode (module), 1057 sympy.stats.Normal() (in module
sympy.printing.gtk (module), 1072 sympy.stats.crv_types), 1261
sympy.printing.jscode (module), 1062 sympy.stats.rv (module), 1260
sympy.printing.julia (module), 1064 sympy.tensor (module), 1399
sympy.printing.lambdarepr (module), 1072 sympy.tensor.array (module), 1399
sympy.printing.latex (module), 1072 sympy.tensor.index_methods (module), 1412
sympy.printing.mathematica (module), 1061 sympy.tensor.indexed (module), 1405
sympy.printing.mathml (module), 1076 sympy.tensor.tensor (module), 1415
sympy.printing.octave (module), 1067 sympy.utilities (module), 1430
sympy.printing.precedence (module), 1083 sympy.utilities.autowrap (module), 1431
sympy.printing.pretty.pretty (module), 1050 sympy.utilities.codegen (module), 1438
sympy.printing.pretty.pretty_symbology sympy.utilities.decorator (module), 1449
(module), 1083 sympy.utilities.enumerative (module), 1451
sympy.printing.pretty.stringpict (module), sympy.utilities.iterables (module), 1458
1084 sympy.utilities.lambdify (module), 1478
sympy.printing.preview (module), 1080 sympy.utilities.memoization (module), 1482
sympy.printing.printer (module), 1046 sympy.utilities.misc (module), 1482
sympy.printing.pycode (module), 1077 sympy.utilities.pkgdata (module), 1485
sympy.printing.python (module), 1078 sympy.utilities.pytest (module), 1486
sympy.printing.rcode (module), 1055 sympy.utilities.randtest (module), 1487
sympy.printing.repr (module), 1078 sympy.utilities.runtests (module), 1488
sympy.printing.rust (module), 1069 sympy.utilities.source (module), 1495
sympy.printing.str (module), 1079 sympy.utilities.timeutils (module), 1495
sympy.printing.theanocode (module), 1071 SymPyDocTestFinder (class in
sympy.printing.tree (module), 1079 sympy.utilities.runtests), 1488
sympy.sets.fancysets (module), 1177 SymPyDocTestRunner (class in
sympy.sets.sets (module), 1162 sympy.utilities.runtests), 1488
sympy.simplify.combsimp (module), 1204 SymPyOutputChecker (class in
sympy.simplify.cse_main (module), 1133, sympy.utilities.runtests), 1489
1205 sympytestfile() (in module
sympy.simplify.epathtools (module), 1208 sympy.utilities.runtests), 1491
sympy.simplify.hyperexpand (module), 1207 SymPyTestResults (in module
sympy.simplify.hyperexpand_doc (module), sympy.utilities.runtests), 1489
1219 syzygy_module() (sympy.polys.agca.modules.SubModule
sympy.simplify.powsimp (module), 1201 method), 918
sympy.simplify.radsimp (module), 1192
sympy.simplify.ratsimp (module), 1199

2032 Index
 SymPy Documentation, Release 1.3

T 1421
T (in module sympy.physics.quantum.gate), TensorIndex (class in sympy.tensor.tensor),
1754 1418
T (sympy.matrices.expressions.MatrixExpr TensorIndexType (class in
attribute), 804 sympy.tensor.tensor), 1416
t (sympy.physics.quantum.shor.CMod at- TensorProduct (class in sympy.diffgeom),
tribute), 1763 1839
table() (sympy.matrices.matrices.MatrixBase TensorProduct (class in
method), 777 sympy.physics.quantum.tensorproduct),
tail_degree() (sympy.polys.rings.PolyElement 1715
method), 1005 tensorproduct() (in module
tail_degrees() (sympy.polys.rings.PolyElement sympy.tensor.array), 1405
method), 1005 TensorSymmetry (class in
take() (in module sympy.utilities.iterables), sympy.tensor.tensor), 1419
1476 tensorsymmetry() (in module
tan (class in sympy.functions.elementary.trigonometric),sympy.tensor.tensor), 1420
454 TensorType (class in sympy.tensor.tensor),
tangent_lines() (sympy.geometry.ellipse.Ellipse 1420
method), 646 terminal_width() (sympy.printing.pretty.stringpict.stringPict
tanh (class in sympy.functions.elementary.hyperbolic), method), 1086
464 terms() (sympy.polys.polyclasses.DMP
targets (sympy.physics.quantum.gate.CGate method), 949
attribute), 1752 terms() (sympy.polys.polytools.Poly method),
targets (sympy.physics.quantum.gate.CNotGate 884
attribute), 1754 terms() (sympy.polys.rings.PolyElement
targets (sympy.physics.quantum.gate.Gate method), 1006
attribute), 1751 terms_gcd() (in module
targets (sympy.physics.quantum.gate.UGate sympy.polys.polytools), 836
attribute), 1752 terms_gcd() (sympy.polys.polyclasses.DMP
targets (sympy.physics.quantum.grover.OracleGate method), 949
attribute), 1756 terms_gcd() (sympy.polys.polytools.Poly
taxicab_distance() (sympy.geometry.point.Point method), 884
method), 596 termwise() (sympy.polys.polytools.Poly
taylor_term() (sympy.core.expr.Expr method), method), 884
137 test() (in module sympy.utilities.runtests),
TC() (sympy.polys.polyclasses.ANP method), 1493
951 test_derivative_numerically() (in module
TC() (sympy.polys.polyclasses.DMP method), sympy.utilities.randtest), 1487
945 TGate (class in sympy.physics.quantum.gate),
TC() (sympy.polys.polytools.Poly method), 1753
849 theano_function() (in module
TensAdd (class in sympy.tensor.tensor), 1425 sympy.printing.theanocode), 1071
TensExpr (class in sympy.tensor.tensor), 1424 TheanoPrinter (class in
TensMul (class in sympy.tensor.tensor), 1427 sympy.printing.theanocode), 1071
tensor_indices() (in module ThinLens (class in
sympy.tensor.tensor), 1419 sympy.physics.optics.gaussopt),
tensor_mul() (in module sympy.tensor.tensor), 1768
1430 threaded() (in module
tensor_product_simp() (in module sympy.utilities.decorator), 1450
sympy.physics.quantum.tensorproduct),threaded_factory() (in module
1716 sympy.utilities.decorator), 1451
tensorcontraction() (in module time (sympy.physics.quantum.state.TimeDepState
sympy.tensor.array), 1404 attribute), 1745
TensorHead (class in sympy.tensor.tensor), time_derivative() (in module

Index 2033
SymPy Documentation, Release 1.3

sympy.physics.vector.functions), sympy.polys.numberfields), 893

1621 to_prufer() (sympy.combinatorics.prufer.Prufer
time_period (sympy.physics.optics.waves.TWave static method), 273
attribute), 1784 to_rational() (sympy.polys.domains.RealField
timed() (in module sympy.utilities.timeutils), method), 942
1495 to_ring() (sympy.polys.polyclasses.DMP
TimeDepBra (class in method), 950
sympy.physics.quantum.state), 1745 to_ring() (sympy.polys.polytools.Poly
TimeDepKet (class in method), 885
sympy.physics.quantum.state), 1745 to_sequence() (sympy.holonomic.holonomic.HolonomicFunct
TimeDepState (class in method), 684
sympy.physics.quantum.state), 1744 to_sympy() (sympy.polys.domains.AlgebraicField
tiny (sympy.codegen.ast.FloatType attribute), method), 941
420 to_sympy() (sympy.polys.domains.domain.Domain
to_algebraic_integer() method), 934
to_sympy() (sympy.polys.domains.ExpressionDomain
(sympy.polys.numberfields.AlgebraicNumber
method), 893 method), 944
to_cnf() (in module sympy.logic.boolalg), 750 to_sympy() (sympy.polys.domains.FiniteField
to_dict() (sympy.polys.polyclasses.ANP method), 938
method), 951 to_sympy() (sympy.polys.domains.FractionField
to_dict() (sympy.polys.polyclasses.DMP method), 942
method), 949 to_sympy() (sympy.polys.domains.PolynomialRing
to_dnf() (in module sympy.logic.boolalg), 750 method), 940
to_exact() (sympy.polys.polyclasses.DMP to_sympy() (sympy.polys.domains.RealField
method), 949 method), 943
to_exact() (sympy.polys.polytools.Poly to_sympy_dict() (sympy.polys.polyclasses.ANP
method), 885 method), 951
to_expr() (sympy.holonomic.holonomic.HolonomicFunction
to_sympy_dict() (sympy.polys.polyclasses.DMP
method), 686 method), 950
to_field() (sympy.polys.polyclasses.DMP to_sympy_list() (sympy.polys.polyclasses.ANP
method), 950 method), 951
to_field() (sympy.polys.polytools.Poly to_sympy_list() (sympy.polys.polyclasses.DMP
method), 885 method), 950
to_hyper() (sympy.holonomic.holonomic.HolonomicFunction
to_tree() (sympy.combinatorics.prufer.Prufer
method), 686 static method), 273
to_linearizer() (sympy.physics.mechanics.kane.KanesMethod
to_tuple() (sympy.polys.polyclasses.ANP
method), 1695 method), 951
to_linearizer() (sympy.physics.mechanics.lagrange.LagrangesMethod
to_tuple() (sympy.polys.polyclasses.DMP
method), 1697 method), 950
to_list() (sympy.polys.polyclasses.ANP together() (in module
method), 951 sympy.polys.rationaltools), 901
to_list() (sympy.polys.polyclasses.DMP together() (sympy.core.expr.Expr method),
method), 950 137
to_matrix() (sympy.physics.vector.dyadic.DyadicToken (class in sympy.codegen.ast), 424
method), 1605 topological_sort() (in module
to_matrix() (sympy.physics.vector.vector.Vector sympy.utilities.iterables), 1476
method), 1603 topological_sort() (sympy.codegen.ast.CodeBlock
to_matrix() (sympy.vector.dyadic.Dyadic class method), 417
method), 1876 torsional_moment() (sympy.physics.continuum_mechanics.b
to_matrix() (sympy.vector.vector.Vector method), 1800
method), 1875 total_degree() (sympy.polys.polyclasses.DMP
to_meijerg() (sympy.holonomic.holonomic.HolonomicFunctionmethod), 950
method), 686 total_degree() (sympy.polys.polytools.Poly
to_number_field() (in module method), 885

2034 Index
 SymPy Documentation, Release 1.3

totient (class in sympy.ntheory.factor_), 324 489

totientrange() (sympy.ntheory.generate.Sieve TribonacciConstant (class in
method), 307 sympy.core.numbers), 157
Trace (class in sympy.matrices.expressions), trigamma() (in module
807 sympy.functions.special.gamma_functions),
trailing() (in module sympy.ntheory.factor_), 510
314 trigsimp() (in module
transcendental, 99 sympy.simplify.trigsimp), 1200
transcendental (sympy.assumptions.ask.AssumptionKeys
trigsimp() (sympy.core.expr.Expr method),
attribute), 1118 137
transform() (sympy.geometry.point.Point2D trunc() (in module sympy.polys.polytools),
method), 598 838
transform() (sympy.geometry.point.Point3D trunc() (sympy.polys.polyclasses.DMP
method), 601 method), 950
transform() (sympy.integrals.Integral trunc() (sympy.polys.polytools.Poly method),
method), 717 886
transform() (sympy.polys.polyclasses.DMP truncate() (sympy.series.formal.FormalPowerSeries
method), 950 method), 1154
transform() (sympy.polys.polytools.Poly truncate() (sympy.series.fourier.FourierSeries
method), 886 method), 1152
transformation_to_DN() (in module Tuple (class in sympy.core.containers), 203
sympy.solvers.diophantine), 1358 tuple_count() (sympy.core.containers.Tuple
transitivity_degree (sympy.combinatorics.perm_groups.PermutationGroup
method), 203
attribute), 267 TWave (class in sympy.physics.optics.waves),
translate() (in module sympy.utilities.misc), 1782
1484 twoform_to_matrix() (in module
translate() (sympy.geometry.curve.Curve sympy.diffgeom), 1845
method), 635 TwoQubitGate (class in
translate() (sympy.geometry.entity.GeometryEntity sympy.physics.quantum.gate), 1752
method), 586 Type (class in sympy.codegen.ast), 424
translate() (sympy.geometry.point.Point2D TypeA (class in sympy.liealgebras.type_a),
method), 598 729
translate() (sympy.geometry.point.Point3D TypeB (class in sympy.liealgebras.type_b),
method), 601 731
Transpose (class in TypeC (class in sympy.liealgebras.type_c),
sympy.matrices.expressions), 807 732
transpose() (sympy.matrices.expressions.blockmatrix.BlockMatrix
TypeD (class in sympy.liealgebras.type_d),
method), 809 734
transpositions() (sympy.combinatorics.permutations.Permutation
TypeE (class in sympy.liealgebras.type_e),
method), 234 735
transverse_magnification() (in module TypeF (class in sympy.liealgebras.type_f), 736
sympy.physics.optics.utils), 1781 TypeG (class in sympy.liealgebras.type_g),
tree() (in module sympy.printing.tree), 1079 738
tree_cse() (in module
sympy.simplify.cse_main), 1207 U
tree_repr (sympy.combinatorics.prufer.Prufer U() (in module sympy.printing.pretty.pretty_symbology),
attribute), 274 1083
Triangle (class in sympy.geometry.polygon), udivisor_count() (in module
665 sympy.ntheory.factor_), 323
triangular (sympy.assumptions.ask.AssumptionKeys udivisor_sigma (class in
attribute), 1118 sympy.ntheory.factor_), 326
Triangular() (in module sympy.stats), 1247 udivisors() (in module sympy.ntheory.factor_),
tribonacci (class in 323
sympy.functions.combinatorial.numbers),

Index 2035
SymPy Documentation, Release 1.3

ufuncify() (in module unrank() (sympy.combinatorics.graycode.GrayCode

sympy.utilities.autowrap), 1435 class method), 284
UfuncifyCodeWrapper (class in unrank() (sympy.combinatorics.prufer.Prufer
sympy.utilities.autowrap), 1433 class method), 274
UGate (class in sympy.physics.quantum.gate), unrank_binary() (sympy.combinatorics.subsets.Subset
1752 class method), 280
uncouple() (in module unrank_gray() (sympy.combinatorics.subsets.Subset
sympy.physics.quantum.spin), 1741 class method), 280
Unequality (class in sympy.core.relational), unrank_lex() (sympy.combinatorics.permutations.Permutatio
174 class method), 235
UnevaluatedExpr (class in sympy.core.expr), unrank_nonlex() (sympy.combinatorics.permutations.Permut
137 class method), 235
unflatten() (in module unrank_trotterjohnson()
sympy.utilities.iterables), 1477 (sympy.combinatorics.permutations.Permutation
UnificationFailed (class in class method), 235
sympy.polys.polyerrors), 1026 UnsignedIntType (class in
Uniform() (in module sympy.stats), 1248 sympy.codegen.ast), 426
UniformSum() (in module sympy.stats), 1249 upper (sympy.physics.secondquant.AntiSymmetricTensor
unify() (sympy.polys.domains.domain.Domain attribute), 1536
method), 934 upper (sympy.tensor.indexed.Idx attribute),
unify() (sympy.polys.polyclasses.ANP 1408
method), 951 upper_triangular (sympy.assumptions.ask.AssumptionKeys
unify() (sympy.polys.polyclasses.DMP attribute), 1120
method), 950 upper_triangular_solve()
unify() (sympy.polys.polytools.Poly method), (sympy.matrices.matrices.MatrixBase
886 method), 778
union (class in sympy.codegen.cnodes), 434 uppergamma (class in
Union (class in sympy.sets.sets), 1172 sympy.functions.special.gamma_functions),
union() (sympy.polys.agca.ideals.Ideal 510
method), 921 use (class in sympy.codegen.fnodes), 440
union() (sympy.polys.agca.modules.SubModule use() (in module sympy.simplify.traversaltools),
method), 918 1208
union() (sympy.series.gruntz.SubsSet use_rename (class in sympy.codegen.fnodes),
method), 1140 440
union() (sympy.sets.sets.Set method), 1167 using (class in sympy.codegen.cxxnodes), 434
uniq() (in module sympy.utilities.iterables),
1477 V
unit (sympy.geometry.point.Point attribute), v1pt_theory() (sympy.physics.vector.point.Point
596 method), 1610
unit (sympy.polys.polytools.Poly attribute), v2pt_theory() (sympy.physics.vector.point.Point
887 method), 1611
unit_triangular (sympy.assumptions.ask.AssumptionKeys
values() (sympy.core.containers.Dict
attribute), 1119 method), 204
unitary (sympy.assumptions.ask.AssumptionKeys var() (in module sympy.core.symbol), 141
attribute), 1119 VarBosonicBasis (class in
UnitaryOperator (class in sympy.physics.secondquant), 1527
sympy.physics.quantum.operator), Variable (class in sympy.codegen.ast), 426
1721 variable (sympy.physics.continuum_mechanics.beam.Beam
UnitSystem (class in attribute), 1797
sympy.physics.units.unitsystem), variable_map() (sympy.physics.vector.frame.ReferenceFram
1553 method), 1599
UnivariatePolynomialError (class in variables (sympy.core.function.Lambda at-
sympy.polys.polyerrors), 1026 tribute), 182
UniversalSet (class in sympy.sets.sets), 1176

2036 Index
 SymPy Documentation, Release 1.3

variables (sympy.core.function.Subs at- W

tribute), 191 w (sympy.physics.optics.gaussopt.BeamParameter
variables (sympy.physics.quantum.operator.DifferentialOperator
attribute), 1772
attribute), 1724 w_0 (sympy.physics.optics.gaussopt.BeamParameter
variables (sympy.physics.quantum.state.Wavefunction attribute), 1772
attribute), 1749 waist2rayleigh() (in module
variables (sympy.series.sequences.SeqBase sympy.physics.optics.gaussopt),
attribute), 1146 1772
variables (sympy.utilities.codegen.Routine waist_approximation_limit
attribute), 1439 (sympy.physics.optics.gaussopt.BeamParameter
Variance (class in sympy.stats), 1257 attribute), 1772
variance() (in module sympy.stats), 1256 Wavefunction (class in
variations() (in module sympy.physics.quantum.state), 1746
sympy.utilities.iterables), 1477 wavelength (sympy.physics.optics.waves.TWave
vech() (sympy.matrices.matrices.MatrixBase attribute), 1784
method), 778 wavenumber (sympy.physics.optics.waves.TWave
Vector (class in sympy.physics.vector.vector), attribute), 1784
1599 WedgeProduct (class in sympy.diffgeom),
Vector (class in sympy.vector.vector), 1872 1840
vectorize (class in Weibull() (in module sympy.stats), 1250
sympy.core.multidimensional), 181 WeylGroup (class in
vectors_in_basis() (in module sympy.liealgebras.weyl_group), 739
sympy.diffgeom), 1844 WGate (class in sympy.physics.quantum.grover),
vel() (sympy.physics.vector.point.Point 1756
method), 1611 where() (in module sympy.stats), 1256
verify_numerically() (in module While (class in sympy.codegen.ast), 428
sympy.utilities.randtest), 1487 wicks() (in module
vertices (sympy.combinatorics.polyhedron.Polyhedron sympy.physics.secondquant), 1531
attribute), 270 width (sympy.categories.diagram_drawing.DiagramGrid
vertices (sympy.geometry.polygon.Polygon attribute), 1826
attribute), 656 width() (sympy.printing.pretty.stringpict.stringPict
vertices (sympy.geometry.polygon.RegularPolygon method), 1086
attribute), 664 Wigner3j (class in
vertices (sympy.geometry.polygon.Triangle sympy.physics.quantum.cg), 1710
attribute), 672 Wigner6j (class in
VF() (in module sympy.printing.pretty.pretty_symbology), sympy.physics.quantum.cg), 1710
1084 Wigner9j (class in
viete() (in module sympy.polys.polyfuncs), sympy.physics.quantum.cg), 1710
890 wigner_3j() (in module
vlatex() (in module sympy.physics.wigner), 1541
sympy.physics.vector.printing), 1617 wigner_6j() (in module
vobj() (in module sympy.physics.wigner), 1543
sympy.printing.pretty.pretty_symbology), wigner_9j() (in module
1084 sympy.physics.wigner), 1544
VonMises() (in module sympy.stats), 1250 WignerD (class in
vpprint() (in module sympy.physics.quantum.spin), 1733
sympy.physics.vector.printing), 1617 WignerSemicircle() (in module sympy.stats),
vprint() (in module 1251
sympy.physics.vector.printing), 1616 Wild (class in sympy.core.symbol), 138
vradius (sympy.geometry.ellipse.Circle at- WildFunction (class in sympy.core.function),
tribute), 649 182
vradius (sympy.geometry.ellipse.Ellipse at- write() (sympy.utilities.codegen.CodeGen
tribute), 647 method), 1441
vring() (in module sympy.polys.rings), 999 write() (sympy.utilities.runtests.PyTestReporter

Index 2037
SymPy Documentation, Release 1.3

method), 1488 y (sympy.physics.vector.frame.ReferenceFrame

wronskian() (in module attribute), 1599
sympy.matrices.dense), 782 ydirection (sympy.geometry.line.Ray2D at-
tribute), 625
X ydirection (sympy.geometry.line.Ray3D at-
X (in module sympy.physics.quantum.gate), tribute), 629
1754 YGate (class in sympy.physics.quantum.gate),
x (sympy.geometry.point.Point2D attribute), 1753
598 yn (class in sympy.functions.special.bessel),
x (sympy.geometry.point.Point3D attribute), 539
601 Ynm (class in sympy.functions.special.spherical_harmonics),
x (sympy.physics.vector.frame.ReferenceFrame 573
attribute), 1599 Ynm_c() (in module
XBra (class in sympy.physics.quantum.cartesian), sympy.functions.special.spherical_harmonics),
1717 575
xdirection (sympy.geometry.line.Ray2D at- YOp (class in sympy.physics.quantum.cartesian),
tribute), 625 1717
xdirection (sympy.geometry.line.Ray3D at-
tribute), 629 Z
XGate (class in sympy.physics.quantum.gate), Z (in module sympy.physics.quantum.gate),
1753 1754
XKet (class in sympy.physics.quantum.cartesian), z (sympy.geometry.point.Point3D attribute),
1717 602
xobj() (in module z (sympy.physics.vector.frame.ReferenceFrame
sympy.printing.pretty.pretty_symbology), attribute), 1599
1084 zdirection (sympy.geometry.line.Ray3D at-
XOp (class in sympy.physics.quantum.cartesian), tribute), 630
1717 zero, 99
Xor (class in sympy.logic.boolalg), 747 Zero (class in sympy.core.numbers), 149
xreplace() (sympy.core.basic.Basic method), zero (sympy.assumptions.ask.AssumptionKeys
113 attribute), 1120
xring() (in module sympy.polys.rings), 998 zero (sympy.polys.polytools.Poly attribute),
xstr() (in module sympy.printing.pretty.pretty_symbology),887
1083 ZeroMatrix (class in
xsym() (in module sympy.matrices.expressions), 808
zeros() (in module sympy.matrices.dense),
sympy.printing.pretty.pretty_symbology),
1084 779
xthreaded() (in module zeta (class in sympy.functions.special.zeta_functions),
sympy.utilities.decorator), 1451 547
xypic_draw_diagram() (in module ZGate (class in sympy.physics.quantum.gate),
sympy.categories.diagram_drawing), 1753
1831 zip_row_op() (sympy.matrices.dense.MutableDenseMatrix
XypicDiagramDrawer (class in method), 791
sympy.categories.diagram_drawing), zip_row_op() (sympy.matrices.sparse.MutableSparseMatrix
1828 method), 800
Znm (class in sympy.functions.special.spherical_harmonics),
Y 575
Y (in module sympy.physics.quantum.gate), ZOp (class in sympy.physics.quantum.cartesian),
1754 1717
y (sympy.geometry.point.Point2D attribute),
598
y (sympy.geometry.point.Point3D attribute),
602

2038 Index