SymPy: symbolic computing in Python

Basic usage

Symbolic variables, called symbols, must be defined and assigned to Python variables before they can be used. This is typically done through the symbols function, which may create multiple symbols in a single function call. For instance,

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

creates three symbols representing variables named x, y, and z. In this particular instance, these symbols are all assigned to Python variables of the same name. However, the user is free to assign them to different Python variables, while representing the same symbol, such as a, b, c = symbols('x y z'). In order to minimize potential confusion, though, all examples in this paper will assume that the symbols x , y , and z have been assigned to Python variables identical to their symbolic names.

Expressions are created from symbols using Python’s mathematical syntax. For instance, the following Python code creates the expression (x² − 2x + 3)∕y. Note that the expression remains unevaluated: it is represented symbolically.

>>> (x**2 - 2*x + 3)/y 
(x**2 - 2*x + 3)/y

List of features

Although SymPy’s extensive feature set cannot be covered in depth in this paper, bedrock areas, that is, those areas that are used throughout the library, are discussed in their own subsections below. Additionally, Table 1 gives a compact listing of all major capabilities present in the SymPy codebase. This grants a sampling from the breadth of topics and application domains that SymPy services. Unless stated otherwise, all features noted in Table 1 are symbolic in nature. Numeric features are discussed in Section ‘Numerics.’

Table 1:

SymPy features and descriptions.

Feature (submodules)	Description
Calculus (sympy.core, sympy.calculus, sympy.integrals, sympy.series)	Algorithms for computing derivatives, integrals, and limits.
Category Theory (sympy.categories)	Representation of objects, morphisms, and diagrams. Tools for drawing diagrams with Xy-pic (Rose, 1999).
Code Generation (sympy.printing, sympy.codegen)	Generation of compilable and executable code in a variety of different programming languages from expressions directly. Target languages include C, Fortran, Julia, JavaScript, Mathematica, MATLAB and Octave, Python, and Theano.
Combinatorics & Group Theory (sympy.combinatorics)	Permutations, combinations, partitions, subsets, various permutation groups (such as polyhedral, Rubik, symmetric, and others), Gray codes (Nijenhuis & Wilf, 1978), and Prufer sequences (Biggs, Lloyd & Wilson, 1976).
Concrete Math (sympy.concrete)	Summation, products, tools for determining whether summation and product expressions are convergent, absolutely convergent, hypergeometric, and for determining other properties; computation of Gosper’s normal form (Petkovšek, Wilf & Zeilberger, 1997) for two univariate polynomials.
Cryptography (sympy.crypto)	Block and stream ciphers, including shift, Affine, substitution, Vigenère’s, Hill’s, bifid, RSA, Kid RSA, linear-feedback shift registers, and Elgamal encryption.
Differential Geometry (sympy.diffgeom)	Representations of manifolds, metrics, tensor products, and coordinate systems in Riemannian and pseudo-Riemannian geometries (Sussman & Wisdom, 2013).
Geometry (sympy.geometry)	Representations of 2D geometrical entities, such as lines and circles. Enables queries on these entities, such as asking the area of an ellipse, checking for collinearity of a set of points, or finding the intersection between objects.
Lie Algebras (sympy.liealgebras)	Representations of Lie algebras and root systems.
Logic (sympy.logic)	Boolean expressions, equivalence testing, satisfiability, and normal forms.
Matrices (sympy.matrices)	Tools for creating matrices of symbols and expressions. Both sparse and dense representations, as well as symbolic linear algebraic operations (e.g., inversion and factorization), are supported.
Matrix Expressions (sympy.matrices.expressions)	Matrices with symbolic dimensions (unspecified entries). Block matrices.
Number Theory (sympy.ntheory)	Prime number generation, primality testing, integer factorization, continued fractions, Egyptian fractions, modular arithmetic, quadratic residues, partitions, binomial and multinomial coefficients, prime number tools, hexidecimal digits of π, and integer factorization.
Plotting (sympy.plotting)	Hooks for visualizing expressions via matplotlib (Hunter, 2007) or as text drawings when lacking a graphical back-end. 2D function plotting, 3D function plotting, and 2D implicit function plotting are supported.
Polynomials (sympy.polys)	Polynomial algebras over various coefficient domains. Functionality ranges from simple operations (e.g., polynomial division) to advanced computations (e.g., Gröbner bases (Adams & Loustaunau, 1994) and multivariate factorization over algebraic number domains).
Printing (sympy.printing)	Functions for printing SymPy expressions in the terminal with ASCII or Unicode characters and converting SymPy expressions to and MathML.
Quantum Mechanics (sympy.physics.quantum)	Quantum states, bra–ket notation, operators, basis sets, representations, tensor products, inner products, outer products, commutators, anticommutators, and specific quantum system implementations.
Series (sympy.series)	Series expansion, sequences, and limits of sequences. This includes Taylor, Laurent, and Puiseux series as well as special series, such as Fourier and formal power series.
Sets (sympy.sets)	Representations of empty, finite, and infinite sets (including special sets such as the natural, integer, and complex numbers). Operations on sets such as union, intersection, Cartesian product, and building sets from other sets are supported.
Simplification (sympy.simplify)	Functions for manipulating and simplifying expressions. Includes algorithms for simplifying hypergeometric functions, trigonometric expressions, rational functions, combinatorial functions, square root denesting, and common subexpression elimination.
Solvers (sympy.solvers)	Functions for symbolically solving equations, systems of equations, both linear and non-linear, inequalities, ordinary differential equations, partial differential equations, Diophantine equations, and recurrence relations.
Special Functions (sympy.functions)	Implementations of a number of well known special functions, including Dirac delta, Gamma, Beta, Gauss error functions, Fresnel integrals, Exponential integrals, Logarithmic integrals, Trigonometric integrals, Bessel, Hankel, Airy, B-spline, Riemann Zeta, Dirichlet eta, polylogarithm, Lerch transcendent, hypergeometric, elliptic integrals, Mathieu, Jacobi polynomials, Gegenbauer polynomial, Chebyshev polynomial, Legendre polynomial, Hermite polynomial, Laguerre polynomial, and spherical harmonic functions.
Statistics (sympy.stats)	Support for a random variable type as well as the ability to declare this variable from prebuilt distribution functions such as Normal, Exponential, Coin, Die, and other custom distributions (Rocklin & Terrel, 2012).
Tensors (sympy.tensor)	Symbolic manipulation of indexed objects.
Vectors (sympy.vector)	Basic operations on vectors and differential calculus with respect to 3D Cartesian coordinate systems.

DOI: 10.7717/peerjcs.103/table-1

Assumptions

The assumptions system allows users to specify that symbols have certain common mathematical properties, such as being positive, imaginary, or integer. SymPy is careful to never perform simplifications on an expression unless the assumptions allow them. For instance, the simplification $\sqrt{t^2}=t$ holds if t is nonnegative (t ≥ 0), but it does not hold for a general complex t.⁴

By default, SymPy performs all calculations assuming that symbols are complex valued. This assumption makes it easier to treat mathematical problems in full generality.

>>> t = Symbol('t') 
>>> sqrt(t**2) 
sqrt(t**2)

By assuming the most general case, that t is complex by default, SymPy avoids performing mathematically invalid operations. However, in many cases users will wish to simplify expressions containing terms like $\sqrt{t^2}$.

Assumptions are set on Symbol objects when they are created. For instance Symbol('t', positive=True) will create a symbol named t that is assumed to be positive.

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

Some of the common assumptions are negative, real, nonpositive, integer, prime and commutative.⁵ Assumptions on any SymPy object can be checked with the is_ assumption attributes, like t.is_positive .

Assumptions are only needed to restrict a domain so that certain simplifications can be performed. They are not required to make the domain match the input of a function. For instance, one can create the object ${\sum }_{n=0}^{m}f\left(n\right)$ as Sum(f(n), (n, 0, m)) without setting integer=True when creating the Symbol object n.

The assumptions system additionally has deductive capabilities. The assumptions use a three-valued logic using the Python built in objects True, False, and None. Note that False is returned if the SymPy object doesn’t or can’t have the assumption. For example, both I.is_real and I.is_prime return False for the imaginary unit I.

None represents the “unknown” case. This could mean that given assumptions do not unambiguously specify the truth of an attribute. For instance, Symbol('x', real=True).is_positive will give None because a real symbol might be positive or negative. None could also mean that not enough is known or implemented to compute the given fact. For instance, (pi + E).is_irrational gives None—indeed, the rationality of π + e is an open problem in mathematics (Lang, 1966).

Basic implications between the facts are used to deduce assumptions. Deductions are made using the Rete algorithm (Doorenbos, 1995).⁶ For instance, the assumptions system knows that being an integer implies being rational.

>>> i = Symbol('i', integer=True) 
>>> i.is_rational 
True

Furthermore, expressions compute the assumptions on themselves based on the assumptions of their arguments. For instance, if x and y are both created with positive=True, then (x + y).is_positive will be True (whereas (x - y).is_positive will be None).

Simplification

The generic way to simplify an expression is by calling the simplify function. It must be emphasized that simplification is not a rigorously defined mathematical operation (Moses, 1971). The simplify function applies several simplification routines along with heuristics to make the output expression “simple”.⁷

It is often preferable to apply more directed simplification functions. These apply very specific rules to the input expression and are typically able to make guarantees about the output. For instance, the factor function, given a polynomial with rational coefficients in several variables, is guaranteed to produce a factorization into irreducible factors. Table 2 lists common simplification functions.

Examples for these simplification functions can be found in Section S10.

Calculus

SymPy provides all the basic operations of calculus, such as calculating limits, derivatives, integrals, or summations.

Limits are computed with the limit function, using the Gruntz algorithm (Gruntz, 1996) for computing symbolic limits and heuristics (a description of the Gruntz algorithm may be found in Section S1). For example, the following computes $\underset{x\to \infty }{lim}xsin\left(\frac{1}{x}\right)=1$. Note that SymPy denotes ∞ as oo (two lower case “o”s).

>>> limit(x*sin(1/x), x, oo) 
1

As a more complex example, SymPy computes ${\displaystyle \underset{x\to 0}{lim}{\left(2e^{\frac{1-cos\left(x\right)}{sin\left(x\right)}}-1\right)}^{\frac{sinh\left(x\right)}{{\mathrm{a}tan}^2\left(x\right)}}=e.}$

>>> limit((2*exp((1-cos(x))/sin(x))-1)**(sinh(x)/atan(x)**2), x, 0) 
E

Derivatives are computed with the diff function, which recursively uses the various differentiation rules.

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

Integrals are calculated with the integrate function. SymPy implements a combination of the Risch algorithm (Bronstein, 2005b), table lookups, a reimplementation of Manuel Bronstein’s “Poor Man’s Integrator” (Bronstein, 2005a), and an algorithm for computing integrals based on Meijer G-functions (Roach, 1996; Roach, 1997). These allow SymPy to compute a wide variety of indefinite and definite integrals. The Meijer G-function algorithm and the Risch algorithm are respectively demonstrated below by the computation of ${\displaystyle {\int }_0^{\infty }{e}^{-st}log\left(t\right)dt=-\frac{log\left(s\right)+\gamma }{s}}$

and ${\displaystyle \int \frac{-2x^2\left(log\left(x\right)+1\right)e^{x^2}+{\left(e^{x^2}+1\right)}^2}{x{\left(e^{x^2}+1\right)}^2\left(log\left(x\right)+1\right)}dx=log\left(log\left(x\right)+1\right)+\frac{1}{e^{x^2}+1}.}$

>>> s, t = symbols('s t', positive=True) 
>>> integrate(exp(-s*t)*log(t), (t, 0, oo)).simplify() 
-(log(s) + EulerGamma)/s 
>>> integrate((-2*x**2*(log(x) + 1)*exp(x**2) + 
... (exp(x**2) + 1)**2)/(x*(exp(x**2) + 1)**2*(log(x) + 1)), x) 
log(log(x) + 1) + 1/(exp(x**2) + 1)

Summations are computed with the summation function, which uses a combination of Gosper’s algorithm (Gosper, 1978), an algorithm that uses Meijer G-functions (Roach, 1996; Roach, 1997), and heuristics. Products are computed with product function via a suite of heuristics.

>>> i, n = symbols('i n') 
>>> summation(2**i, (i, 0, n - 1)) 
2**n - 1 
>>> summation(i*factorial(i), (i, 1, n)) 
n*factorial(n) + factorial(n) - 1

Series expansions are computed with the series function. This example computes the power series of sin(x) around x = 0 up to x⁶.

>>> series(sin(x), x, 0, 6) 
x - x**3/6 + x**5/120 + O(x**6)

Section S2 discusses series expansions methods in more depth. Integrals, derivatives, summations, products, and limits that cannot be computed return unevaluated objects. These can also be created directly if the user chooses.

>>> integrate(x**x, x) 
Integral(x**x, x) 
>>> Sum(2**i, (i, 0, n - 1)) 
Sum(2**i, (i, 0, n - 1))

Polynomials

SymPy implements a suite of algorithms for polynomial manipulation, which ranges from relatively simple algorithms for doing arithmetic of polynomials, to advanced methods for factoring multivariate polynomials into irreducibles, symbolically determining real and complex root isolation intervals, or computing Gröbner bases.

Polynomial manipulation is useful in its own right. Within SymPy, though, it is mostly used indirectly as a tool in other areas of the library. In fact, many mathematical problems in symbolic computing are first expressed using entities from the symbolic core, preprocessed, and then transformed into a problem in the polynomial algebra, where generic and efficient algorithms are used to solve the problem. The solutions to the original problem are subsequently recovered from the results. This is a common scheme in symbolic integration or summation algorithms.

SymPy implements dense and sparse polynomial representations.⁸ Both are used in the univariate and multivariate cases. The dense representation is the default for univariate polynomials. For multivariate polynomials, the choice of representation is based on the application. The most common case for the sparse representation is algorithms for computing Gröbner bases (Buchberger, F4, and F5) (Buchberger, 1965; Faugère, 1999; Faugère, 2002). This is because different monomial orderings can be expressed easily in this representation. However, algorithms for computing multivariate GCDs or factorizations, at least those currently implemented in SymPy (Paprocki, 2010), are better expressed when the representation is dense. The dense multivariate representation is specifically a recursively-dense representation, where polynomials in K[x₀, x₁, …, x_n] are viewed as a polynomials in K[x₀][x₁]…[x_n]. Note that despite this, the coefficient domain K, can be a multivariate polynomial domain as well. The dense recursive representation in Python gets inefficient as the number of variables increases.

Some examples for the sympy.polys submodule can be found in Section S10.

Printers

SymPy has a rich collection of expression printers. By default, an interactive Python session will render the str form of an expression, which has been used in all the examples in this paper so far. The str form of an expression is valid Python and roughly matches what a user would type to enter the expression.⁹

>>> phi0 = Symbol('phi0') 
>>> str(Integral(sqrt(phi0), phi0)) 
'Integral(sqrt(phi0), phi0)'

A two-dimensional (2D) textual representation of the expression can be printed with monospace fonts via pprint. Unicode characters are used for rendering mathematical symbols such as integral signs, square roots, and parentheses. Greek letters and subscripts in symbol names that have Unicode code points associated are also rendered automatically.

Alternately, the use_unicode=False flag can be set, which causes the expression to be printed using only ASCII characters.

>>> pprint(Integral(sqrt(phi0 + 1), phi0), use_unicode=False) 
  / 
 | 
 |   __________ 
 | \/ phi0 + 1  d(phi0) 
 | 
/

The function latex returns a representation of an expression.

>>> print(latex(Integral(sqrt(phi0 + 1), phi0))) 
\int \sqrt{\phi_{0} + 1}\, d\phi_{0}

Users are encouraged to run the init_printing function at the beginning of interactive sessions, which automatically enables the best pretty printing supported by their environment. In the Jupyter Notebook or Qt Console (Pérez & Granger, 2007), the printer is used to render expressions using MathJax or , if it is installed on the system. The 2D text representation is used otherwise.

Other printers such as MathML are also available. SymPy uses an extensible printer subsystem, which allows extending any given printer, and also allows custom objects to define their printing behavior for any printer. The code generation functionality of SymPy relies on this subsystem to convert expressions into code in various target programming languages.

Solvers

SymPy has equation solvers that can handle ordinary differential equations, recurrence relationships, Diophantine equations,¹⁰ and algebraic equations. There is also rudimentary support for simple partial differential equations.

There are two functions for solving algebraic equations in SymPy: solve and solveset. solveset has several design changes with respect to the older solve function. This distinction is present in order to resolve the usability issues with the previous solve function API while maintaining backward compatibility with earlier versions of SymPy. solveset only requires essential input information from the user. The function signatures of solve and solveset are

solve(f, *symbols, **flags) 
solveset(f, symbol, domain=S.Complexes)

The domain parameter can be any set from the sympy.sets module (see Section S5 for details on sympy.sets), but is typically either S.Complexes (the default) or S.Reals; the latter causes solveset to only return real solutions.

An important difference between the two functions is that the output API of solve varies with input (sometimes returning a Python list and sometimes a Python dictionary) whereas solveset always returns a SymPy set object.

Both functions implicitly assume that expressions are equal to 0. For instance, solveset(x - 1, x) solves x − 1 = 0 for x.

solveset is under active development as a planned replacement for solve. There are certain features which are implemented in solve that are not yet implemented in solveset, including multivariate systems, and some transcendental equations.

Some examples for solveset and solve can be found in Section S10.

Matrices

Besides being an important feature in its own right, computations on matrices with symbolic entries are important for many algorithms within SymPy. The following code shows some basic usage of the Matrix class.

>>> A = Matrix([[x, x + y], [y, x]]) 
>>> A 
Matrix([ 
[x, x + y], 
[y,     x]])

SymPy matrices support common symbolic linear algebra manipulations, including matrix addition, multiplication, exponentiation, computing determinants, solving linear systems, singular values, and computing inverses using LU decomposition, LDL decomposition, Gauss-Jordan elimination, Cholesky decomposition, Moore–Penrose pseudoinverse, or adjugate matrices.

All operations are performed symbolically. For instance, eigenvalues are computed by generating the characteristic polynomial using the Berkowitz algorithm and then finding its zeros using polynomial routines.

>>> A.eigenvals() 
{x - sqrt(y*(x + y)): 1, x + sqrt(y*(x + y)): 1}

Internally these matrices store the elements as Lists of Lists (LIL) (Jones et al., 2001), meaning the matrix is stored as a list of lists of entries (effectively, the input format used to create the matrix A above), making it a dense representation.¹¹ For storing sparse matrices, the SparseMatrix class can be used. Sparse matrices store their elements in Dictionary of Keys (DOK) format, meaning that the entries are stored as a dict of (row, column) pairs mapping to the elements.

SymPy also supports matrices with symbolic dimension values. MatrixSymbol represents a matrix with dimensions m × n, where m and n can be symbolic. Matrix addition and multiplication, scalar operations, matrix inverse, and transpose are stored symbolically as matrix expressions.

Block matrices are also implemented in SymPy. BlockMatrix elements can be any matrix expression, including explicit matrices, matrix symbols, and other block matrices. All functionalities of matrix expressions are also present in BlockMatrix .

When symbolic matrices are combined with the assumptions submodule for logical inference, they provide powerful reasoning over invertibility, semi-definiteness, orthogonality, etc., which are valuable in the construction of numerical linear algebra systems (Rocklin, 2013).

More examples for Matrix and BlockMatrix may be found in Section S10.

Floating-point numbers

Floating-point numbers in SymPy are implemented by the Float class, which represents an arbitrary-precision binary floating-point number by storing its value and precision (in bits). This representation is distinct from the Python built-in float type, which is a wrapper around machine double types and uses a fixed precision (53-bit).

Because Python float literals are limited in precision, strings should be used to input precise decimal values:

>>> Float(1.1) 
1.10000000000000 
>>> Float(1.1, 30)   # precision equivalent to 30 digits 
1.10000000000000008881784197001 
>>> Float("1.1", 30) 
1.10000000000000000000000000000

The evalf method converts a constant symbolic expression to a Float with the specified precision, here 25 digits:

>>> (pi + 1).evalf(25) 
4.141592653589793238462643

Float numbers do not track their accuracy, and should be used with caution within symbolic expressions since familiar dangers of floating-point arithmetic apply (Goldberg, 1991). A notorious case is that of catastrophic cancellation:

>>> cos(exp(-100)).evalf(25) - 1 
0

Applying the evalf method to the whole expression solves this problem. Internally, evalf estimates the number of accurate bits of the floating-point approximation for each sub-expression, and adaptively increases the working precision until the estimated accuracy of the final result matches the sought number of decimal digits:

>>> (cos(exp(-100)) - 1).evalf(25) 
-6.919482633683687653243407e-88

The evalf method works with complex numbers and supports more complicated expressions, such as special functions, infinite series, and integrals. The internal error tracking does not provide rigorous error bounds (in the sense of interval arithmetic) and cannot be used to accurately track uncertainty in measurement data; the sole purpose is to mitigate loss of accuracy that typically occurs when converting symbolic expressions to numerical values.

The mpmath library

The implementation of arbitrary-precision floating-point arithmetic is supplied by the mpmath library (Johansson & The mpmath Development Team, 2014). Originally, it was developed as a SymPy submodule but has subsequently been moved to a standalone pure-Python package. The basic datatypes in mpmath are mpf and mpc, which respectively act as multiprecision substitutes for Python’s float and complex. The floating-point precision is controlled by a global context:

>>> import mpmath 
>>> mpmath.mp.dps = 30    # 30 digits of precision 
>>> mpmath.mpf("0.1") + mpmath.exp(-50) 
mpf('0.100000000000000000000192874984794') 
>>> print(_)   # pretty-printed 
0.100000000000000000000192874985

Like SymPy, mpmath is a pure Python library. A design decision of SymPy is to keep it and its required dependencies pure Python. This is a primary advantage of mpmath over other multiple precision libraries such as GNU MPFR (Fousse et al., 2007), which is faster. Like SymPy, mpmath is also BSD licensed (GNU MPFR is licensed under the GNU Lesser General Public License (Rosen, 2005)).

Internally, mpmath represents a floating-point number (−1)^sx⋅2^y by a tuple (s, x, y, b) where x and y are arbitrary-size Python integers and the redundant integer b stores the bit length of x for quick access. If GMPY (Horsen, 2015) is installed, mpmath automatically uses the gmpy.mpz type for x, and GMPY methods for rounding-related operations, improving performance.

Most mpmath and SymPy functions use the same naming scheme, although this is not true in every case. For example, the symbolic SymPy summation expression Sum(f(x), (x, a, b)) representing ${\sum }_{x=a}^{b}f\left(x\right)$ is represented in mpmath as nsum(f, (a, b)), where f is a numeric Python function.

The mpmath library supports special functions, root-finding, linear algebra, polynomial approximation, and numerical computation of limits, derivatives, integrals, infinite series, and solving ODEs. All features work in arbitrary precision and use algorithms that allow computing hundreds of digits rapidly (except in degenerate cases).

The double exponential (tanh-sinh) quadrature is used for numerical integration by default. For smooth integrands, this algorithm usually converges extremely rapidly, even when the integration interval is infinite or singularities are present at the endpoints (Takahasi & Mori, 1974; Bailey, Jeyabalan & Li, 2005). However, for good performance, singularities in the middle of the interval must be specified by the user. To evaluate slowly converging limits and infinite series, mpmath automatically tries Richardson extrapolation and the Shanks transformation (Euler-Maclaurin summation can also be used) (Bender & Orszag, 1999). A function to evaluate oscillatory integrals by means of convergence acceleration is also available.

A wide array of higher mathematical functions is implemented with full support for complex values of all parameters and arguments, including complete and incomplete gamma functions, Bessel functions, orthogonal polynomials, elliptic functions and integrals, zeta and polylogarithm functions, the generalized hypergeometric function, and the Meijer G-function. The Meijer G-function instance $G_{1,3}^{3,0}\left(0;\frac{1}{2},-1,\left.-\frac{3}{2}\right|x\right)$ is a good test case (Toth, 2007); past versions of both Maple and Mathematica produced incorrect numerical values for large x > 0. Here, mpmath automatically removes an internal singularity and compensates for cancellations (amounting to 656 bits of precision when x = 10, 000), giving correct values:

>>> mpmath.mp.dps = 15 
>>> mpmath.meijerg([[],[0]], [[-0.5,-1,-1.5],[]], 10000) 
mpf('2.4392576907199564e-94')

Equivalently, with SymPy’s interface this function can be evaluated as:

>>> meijerg([[],[0]], [[-S(1)/2,-1,-S(3)/2],[]], 10000).evalf() 
2.43925769071996e-94

Symbolic integration and summation often produce hypergeometric and Meijer G-function closed forms (see Section ‘Calculus’); numerical evaluation of such special functions is a useful complement to direct numerical integration and summation.

Classical mechanics

One of the core domains that SymPy suports is the physics of classical mechanics. This is in turn separated into two distinct components: vector algebra and mechanics.

>>> from sympy.physics.vector import ReferenceFrame 
>>> A, B, C = symbols('A B C', cls=ReferenceFrame) 
>>> B.orient(A, 'body', (pi, pi/3, pi/4), 'zxz') 
>>> C.orient(B, 'axis', (pi/2, B.x)) 
>>> v = 1*A.x + 2*B.z + 3*C.y 
>>> v 
A.x + 2*B.z + 3*C.y 
>>> v.express(A) 
A.x + 5*sqrt(3)/2*A.y + 5/2*A.z

Quantum mechanics

The sympy.physics.quantum submodule has extensive capabilities to solve problems in quantum mechanics, using Python objects to represent the different mathematical objects relevant in quantum theory (Sakurai & Napolitano, 2010): states (bras and kets), operators (unitary, Hermitian, etc.), and basis sets, as well as operations on these objects such as representations, tensor products, inner products, outer products, commutators, and anticommutators. The base objects are designed in the most general way possible to enable any particular quantum system to be implemented by subclassing the base operators and defining the relevant class methods to provide system-specific logic.

Symbolic quantum operators and states may be defined, and one can perform a full range of operations with them.

>>> from sympy.physics.quantum import Commutator, Dagger, Operator 
>>> from sympy.physics.quantum import Ket, qapply 
>>> A, B, C, D = symbols('A B C D', cls=Operator) 
>>> a = Ket('a') 
>>> comm = Commutator(A, B) 
>>> comm 
[A,B] 
>>> qapply(Dagger(comm*a)).doit() 
-<a|*(Dagger(A)*Dagger(B) - Dagger(B)*Dagger(A)) 
Commutators can be expanded using common commutator identities: 
>>> Commutator(C+B, A*D).expand(commutator=True) 
-[A,B]*D - [A,C]*D + A*[B,D] + A*[C,D]

On top of this set of base objects, a number of specific quantum systems have been implemented in a fully symbolic framework. These include:

• Many of the exactly solvable quantum systems, including simple harmonic oscillator states and raising/lowering operators, infinite square well states, and 3D position and momentum operators and states.

• Second quantized formalism of non-relativistic many-body quantum mechanics (Fetter & Walecka, 2003).

• Quantum angular momentum (Zare, 1991). Spin operators and their eigenstates can be represented in any basis and for any quantum numbers. A rotation operator representing the Wigner D-matrix, which may be defined symbolically or numerically, is also implemented to rotate spin eigenstates. Functionality for coupling and uncoupling of arbitrary spin eigenstates is provided, including symbolic representations of Clebsch-Gordon coefficients and Wigner symbols.

• Quantum information and computing (Nielsen & Chuang, 2011). Multidimensional qubit states, and a full set of one- and two-qubit gates are provided and can be represented symbolically or as matrices/vectors. With these building blocks, it is possible to implement a number of basic quantum algorithms including the quantum Fourier transform, quantum error correction, quantum teleportation, Grover’s algorithm, dense coding, etc. In addition, any quantum circuit may be plotted using the circuit_plot function (Fig. 1).

Here are a few short examples of the quantum information and computing capabilities in sympy.physics.quantum . Start with a simple four-qubit state and flip the second qubit from the right using a Pauli-X gate:

>>> from sympy.physics.quantum.qubit import Qubit 
>>> from sympy.physics.quantum.gate import XGate 
>>> q = Qubit('0101') 
>>> q 
|0101> 
>>> X = XGate(1) 
>>> qapply(X*q) 
|0111>

Qubit states can also be used in adjoint operations, tensor products, inner/outer products:

>>> Dagger(q) 
<0101| 
>>> ip = Dagger(q)*q 
>>> ip 
<0101|0101> 
>>> ip.doit() 
1

Quantum gates (unitary operators) can be applied to transform these states and then classical measurements can be performed on the results:

>>> from sympy.physics.quantum.qubit import measure_all 
>>> from sympy.physics.quantum.gate import H, X, Y, Z 
>>> 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)]

Lastly, the following example demonstrates creating a three-qubit quantum Fourier transform, decomposing it into one- and two-qubit gates, and then generating a circuit plot for the sequence of gates (see Fig. 1).

>>> from sympy.physics.quantum.qft import QFT 
>>> from sympy.physics.quantum.circuitplot import circuit_plot 
>>> fourier = QFT(0,3).decompose() 
>>> fourier 
SWAP(0,2)*H(0)*C((0),S(1))*H(1)*C((0),T(2))*C((1),S(2))*H(2) 
>>> c = circuit_plot(fourier, nqubits=3)

The core

A computer algebra system stores mathematical expressions as data structures. For example, the mathematical expression x + y is represented as a tree with three nodes, +, x, and y, where x and y are ordered children of +. As users manipulate mathematical expressions with traditional mathematical syntax, the CAS manipulates the underlying data structures. Symbolic computations such as integration, simplification, etc. are all functions that consume and produce expression trees.

In SymPy every symbolic expression is an instance of the class Basic,¹² the superclass of all SymPy types providing common methods to all SymPy tree-elements, such as traversals. The children of a node in the tree are held in the args attribute. A leaf node in the expression tree has empty args.

For example, consider the expression xy + 2:

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

By order of operations, the parent of the expression tree for expr is an addition. It is of type Add. The child nodes of expr are 2 and x*y.

>>> type(expr) 
<class 'sympy.core.add.Add'> 
>>> expr.args 
(2, x*y)

Descending further down into the expression tree yields the full expression. For example, the next child node (given by expr.args[0]) is 2. Its class is Integer, and it has an empty args tuple, indicating that it is a leaf node.

>>> expr.args[0] 
2 
>>> type(expr.args[0]) 
<class 'sympy.core.numbers.Integer'> 
>>> expr.args[0].args 
()

Symbols or symbolic constants, like e or π, are other examples of leaf nodes.

>>> exp(1) 
E 
>>> exp(1).args 
() 
>>> x.args 
()

A useful way to view an expression tree is using the srepr function, which returns a string representation of an expression as valid Python code¹³ with all the nested class constructor calls to create the given expression.

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

Every SymPy expression satisfies a key identity invariant:

expr.func(*expr.args) == expr

This means that expressions are rebuildable from their args.¹⁴ Note that in SymPy the == operator represents exact structural equality, not mathematical equality. This allows testing if any two expressions are equal to one another as expression trees. For example, even though (x + 1)² and x² + 2x + 1 are equal mathematically, SymPy gives

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

because they are different as expression trees (the former is a Pow object and the latter is an Add object).

Another important property of SymPy expressions is that they are immutable. This simplifies the design of SymPy, and enables expression interning. It also enables expressions to be hashed, which allows expressions to be used as keys in Python dictionaries, and is used to implement caching in SymPy.

Python allows classes to override mathematical operators. The Python interpreter translates the above x*y + 2 to, roughly, (x.__mul__(y)).__add__(2) . Both x and y, returned from the symbols function, are Symbol instances. The 2 in the expression is processed by Python as a literal, and is stored as Python’s built in int type. When 2 is passed to the __add__ method of Symbol, it is converted to the SymPy type Integer(2) before being stored in the resulting expression tree. In this way, SymPy expressions can be built in the natural way using Python operators and numeric literals.

Extensibility

While the core of SymPy is relatively small, it has been extended to a wide variety of domains by a broad range of contributors. This is due, in part, to the fact that the same language, Python, is used both for the internal implementation and the external usage by users. All of the extensibility capabilities available to users are also utilized by SymPy itself. This eases the transition pathway from SymPy user to SymPy developer.

The typical way to create a custom SymPy object is to subclass an existing SymPy class, usually Basic, Expr, or Function. As it was stated before, all SymPy classes used for expression trees should be subclasses of the base class Basic. Expr is the Basic subclass for mathematical objects that can be added and multiplied together. The most commonly seen classes in SymPy are subclasses of Expr, including Add, Mul, and Symbol. Instances of Expr typically represent complex numbers, but may also include other “rings”, like matrix expressions. Not all SymPy classes are subclasses of Expr. For instance, logic expressions, such as And(x, y) , are subclasses of Basic but not of Expr.¹⁵

The Function class is a subclass of Expr which makes it easier to define mathematical functions called with arguments. This includes named functions like sin(x) and log(x) as well as undefined functions like f(x). Subclasses of Function should define a class method eval, which returns an evaluated value for the function application (usually an instance of some other class, e.g., a Number), or None if for the given arguments it should not be automatically evaluated.

Many SymPy functions perform various evaluations down the expression tree. Classes define their behavior in such functions by defining a relevant _eval_ * method. For instance, an object can indicate to the diff function how to take the derivative of itself by defining the _eval_derivative(self, x) method, which may in turn call diff on its args. (Subclasses of Function should implement the fdiff method instead; it returns the derivative of the function without considering the chain rule.) The most common _eval_ * methods relate to the assumptions: _eval_is_ assumption is used to deduce assumption on the object.

Listing 1 presents an example of this extensibility. It gives a stripped down version of the gamma function Γ(x) from SymPy. The methods defined allow it to evaluate itself on positive integer arguments, define the real assumption, allow it to be rewritten in terms of factorial (with gamma(x).rewrite(factorial) ), and allow it to be differentiated. self.func is used throughout instead of referencing gamma explicitly so that potential subclasses of gamma can reuse the methods.

Listing 1: A minimal implementation of sympy.gamma. 
from  sympy  import  Function, Integer, factorial, polygamma 
class  gamma(Function): 
     @classmethod 
     def  eval(cls, arg): 
          if  isinstance(arg, Integer) and  arg.is_positive: 
               return  factorial(arg - 1) 
     def  _eval_is_real(self): 
          x = self.args[0] 
          # noninteger  means  real  and  not  integer 
          if x.is_positive  or x.is_noninteger: 
               return  True 
     def  _eval_rewrite_as_factorial(self, z): 
          return  factorial(z - 1) 
     def  fdiff(self, argindex=1): 
          from  sympy.core.function  import  ArgumentIndexError 
          if  argindex  == 1: 
               return  self.func(self.args[0])*polygamma(0, self.args[0]) 
          else: 
               raise  ArgumentIndexError(self, argindex)

The gamma function implemented in SymPy has many more capabilities than the above listing, such as evaluation at rational points and series expansion.

Performance

Due to being written in pure Python without the use of extension modules, SymPy’s performance characteristics are generally poorer than that of its commercial competitors. For many applications, the performance of SymPy, as measured by clock cycles, memory usage, and memory layout, is sufficient. However, the boundaries for when SymPy’s pure Python strategy becomes insufficient are when the user requires handling of very long expressions or many small expressions. Where this boundray lies depends on the system at hand, but tends to be within the range of 10⁴–10⁶ symbols for modern computers.

For this reason, a new project called SymEngine (The SymPy Developers, 2016a) has been started. The aim of this poject is to develop a library with better performance characteristics for symbolic manipulation. SymEngine is a pure C++ library, which allows it fine-grained control over the memory layout of expressions. SymEngine has thin wrappers to other languages (Python, Ruby, Julia, etc.). Its aim is to be the fastest symbolic manipulation library. Preliminary benchmarks suggest that SymEngine performs as well as its commercial and open source competitors.

The development version of SymPy has recently started to use SymEngine as an optional backend, initially in sympy.physics.mechanics only. Future work will involve allowing more algorithms in SymPy to use SymEngine as a backend.