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.

Introduction

There are four main levels of abstractions:

expression
   |
code printers
   |
code generators
   |
autowrap

sympy.utilities.autowrap uses codegen, and codegen uses the code printers. sympy.utilities.autowrap does everything: it lets you go from SymPy expression 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).

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 simplifications) should happen before the code printers.

Currently, sympy.simplify.cse_main.cse() is not applied automatically anywhere 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)

Code printers (sympy.printing)

This is where the meat of code generation is; the translation of SymPy expressions to specific languages. Supported languages are C (sympy.printing.ccode.ccode()), R (sympy.printing.rcode.rcode()), Fortran 95 (sympy.printing.fcode.fcode()), JavaScript (sympy.printing.jscode.jscode()), Julia (sympy.printing.julia.julia_code()), Mathematica (sympy.printing.mathematica.mathematica_code()), Octave/Matlab (sympy.printing.octave.octave_code()), Rust (sympy.printing.rust.rust_code()), Python (print_python, which is actually more like a lightweight version of codegen for Python, and sympy.printing.lambdarepr.lambdarepr(), which supports many libraries (like NumPy), and theano (sympy.printing.theanocode.theano_function()). 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.printing.codeprinter.Assignment object).This serves as building blocks for the code printers and hence the codegen module. An example that shows the use of Assignment:

>>> from sympy.codegen.ast import Assignment
>>> mat = Matrix([x, y, z]).T
>>> known_mat = MatrixSymbol('K', 1, 3)
>>> Assignment(known_mat, mat)
K := [x  y  z]
>>> Assignment(known_mat, mat).lhs
K
>>> Assignment(known_mat, mat).rhs
[x  y  z]

Here is a 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:

>>> from sympy.codegen.cfunctions import expm1
>>> ccode(expm1(x), standard='C99')
expm1(x)

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

>>> 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⋅γ₁⋅γ₂⋅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

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 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 routine for a set of expressions. This is only good for internal use by the CodeGen objects, as an intermediate representation from SymPy expression to generated code. It is not recommended 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]   
[result₅₁₄₂₃₄₁₆₈₁₃₉₇₇₁₉₄₂₈]
>>> [arg.expr for arg in routine.results]
⎡                ___________                                           ⎤
⎢          y    ╱ (-y + 2)!   -2⋅x                                     ⎥
⎢4⋅√6⋅(4⋅x) ⋅  ╱  ───────── ⋅ℯ    ⋅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.

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

>>> 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 unnecessary costs when chained together. Consider the following operation

>>> x = get_numpy_array(...) 
>>> y = sin(x) / x

The operators sin and / call routines that execute tight for loops in C. The resulting computation looks something like this

for(int i = 0; i < n; i++)
{
    temp[i] = sin(x[i]);
}
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 fashion. 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) 

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 outperforms 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)⋅ℯ
────────────────────
         3

The lambdify function translates SymPy expressions into Python functions, leveraging a variety 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 powerful vectorized ufuncs that are backed by compiled C code.

Let us compare the speeds:

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

There are other facilities available with SymPy to do efficient numeric computation. See this page for a comparison among them.

Special (finite precision arithmetic) math functions

Functions with corresponding implementations in C.

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[source]

Represents the cube root function.

The reason why one would use Cbrt(x) over cbrt(x) is that the latter is internally represented as Pow(x, Rational(1, 3)) which may not be what one wants when doing code-generation.

See also

Sqrt

Examples

>>> from sympy.abc import x
>>> from sympy.codegen.cfunctions import Cbrt
>>> Cbrt(x)
Cbrt(x)
>>> Cbrt(x).diff(x)
1/(3*x**(2/3))
fdiff(argindex=1)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.Sqrt[source]

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

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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.exp2[source]

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

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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.expm1[source]

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.

See also

log1p

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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.fma[source]

Represents “fused multiply add”.

The benefit of using fma(x, y, z) over x*y + z is that, under finite precision arithmetic, 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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.hypot[source]

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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.log10[source]

Represents the logarithm function with base ten.

See also

log2

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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.log1p[source]

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

Examples

>>> from sympy.abc import x
>>> from sympy.codegen.cfunctions import log1p
>>> '%.0e' % 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)[source]

Returns the first derivative of this function.

class sympy.codegen.cfunctions.log2[source]

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

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)[source]

Returns the first derivative of this function.

Fortran specific functions

Functions with corresponding implementations in 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.ffunctions.cmplx[source]

Fortran complex conversion function.

class sympy.codegen.ffunctions.dsign[source]

Fortran sign intrinsic with for double precision arguments.

class sympy.codegen.ffunctions.isign[source]

Fortran sign intrinsic with for integer arguments.

class sympy.codegen.ffunctions.kind[source]

Fortran kind function.

class sympy.codegen.ffunctions.literal_dp[source]

Fortran double precision real literal

Attributes

is_irrational  
is_rational  
class sympy.codegen.ffunctions.literal_sp[source]

Fortran single precision real literal

Attributes

is_irrational  
is_rational  
class sympy.codegen.ffunctions.merge[source]

Fortran merge function

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*
     |--->Assignment
     |             |--->AugmentedAssignment
     |                                    |--->AddAugmentedAssignment
     |                                    |--->SubAugmentedAssignment
     |                                    |--->MulAugmentedAssignment
     |                                    |--->DivAugmentedAssignment
     |                                    |--->ModAugmentedAssignment
     |
     |--->CodeBlock
     |
     |--->For
     |
     |--->Token
     |        |--->Attribute
     |        |--->Type
     |                |--->IntBaseType
     |                |              |--->_SizedIntType
     |                |                               |--->SignedIntType
     |                |                               |--->UnsignedIntType
     |                |--->FloatType
     |                             |--->ComplexType
     |
     |--->Variable
     |           |---> Pointer
     |
     |--->Declaration

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
class sympy.codegen.ast.Assignment[source]

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)
Assignment(A, Matrix([[x, y, z]]))
>>> Assignment(A[0, 1], x)
Assignment(A[0, 1], x)
class sympy.codegen.ast.Attribute[source]

Variable attribute

class sympy.codegen.ast.AugmentedAssignment[source]

Base class for augmented assignments

class sympy.codegen.ast.CodeBlock[source]

Represents a block of code

For now only assignments are supported. This restriction will be lifted in the future.

Useful methods 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.
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')[source]

Return a new code block with common subexpressions eliminated

See the docstring of sympy.simplify.cse_main.cse() for more information.

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)[source]

Return a CodeBlock with topologically sorted assignments so that variables are assigned 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.ComplexType[source]

Represents a complex floating point number.

class sympy.codegen.ast.Declaration[source]

Represents a variable declaration

Parameters:

var : Variable, Pointer or IndexedBase

val : Value (optional)

Value to be assigned upon declaration.

cast : bool

If val is not None val will be casted using var.Type.cast_check().

Examples

>>> from sympy import Symbol
>>> from sympy.codegen.ast import Declaration, Type, Variable, integer
>>> x = Symbol('x')
>>> xvar = Variable(x)
>>> decl = Declaration.deduced(xvar, 3)
>>> decl.variable.type == integer
True
>>> k = Symbol('k', integer=True)
>>> k_decl = Declaration.deduced(k, 3.0)
>>> k_decl.variable.type == integer
True
classmethod deduced(symbol, value=None, attrs=EmptySet(), **kwargs)[source]

Deduces type primarily from symbol, secondarily from value.

Examples

>>> from sympy import Symbol
>>> from sympy.codegen.ast import Declaration, real, integer
>>> x = Symbol('x', real=True)
>>> decl = Declaration.deduced(x)
>>> decl.variable.type == real
True
>>> decl.value is None
True
>>> n = Symbol('n', integer=True)
>>> Declaration.deduced(n).variable
Variable(n, EmptySet(), IntBaseType(name='integer'))
value

Initialization value of the declaration

variable

Variable of the declaration

class sympy.codegen.ast.FloatType[source]

Represents a floating point value.

Base 2 & one sign bit is assumed.

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)  
Traceback (most recent call last):
  ...
ValueError: Maximum value for data type smaller than new value.

Arguments

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

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[source]

Represents a ‘for-loop’ in the code.

Expressions are of the form:
“for target in iter:
body…”
Parameters:

target : symbol

iter : iterable

body : sympy expr

Examples

>>> from sympy import symbols, Range
>>> from sympy.codegen.ast import aug_assign, For
>>> x, n = symbols('x n')
>>> For(n, Range(10), [aug_assign(x, '+', n)])
For(n, Range(0, 10, 1), CodeBlock(AddAugmentedAssignment(x, n)))
body

Return the sympy expression (body) from the for-loop representation. This is run for each value of target. Must be an iterable object or CodeBlock.

iterable

Return the iterable from the for-loop representation. This is the object that target takes values from. Must be an iterable object.

target

Return the symbol (target) from the for-loop representation. This object changes each iteration. Target must be a symbol.

class sympy.codegen.ast.IntBaseType[source]

Integer base type, contains no size information.

class sympy.codegen.ast.Pointer[source]

Represents a pointer

pointer_const

Boolean value describing whether the pointer address is constant.

class sympy.codegen.ast.Token[source]

Similar to Symbol, but takes no assumptions.

Defining fields are set in __slots__.

class sympy.codegen.ast.Type[source]

Represents a type.

The naming is a super-set of NumPy naming, see [R25]. 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).

References

[R25](1, 2) Numpy types https://docs.scipy.org/doc/numpy/user/basics.types.html

Examples

>>> from sympy.codegen.ast import Type
>>> Type.from_expr(42).name
'integer'
>>> from sympy.codegen.ast import uint8
>>> uint8.cast_check(-1)   
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)  
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(Symbol('x'), type_=boost_mp50)))
'boost::multiprecision::cpp_dec_float_50 x'

Arguments

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.
cast_check(value, rtol=None, atol=0, limits=None, precision_targets=None)[source]

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)  
Traceback (most recent call last):
  ...
ValueError: Minimum value for data type bigger than new value.
>>> int8.cast_check(256)  
Traceback (most recent call last):
  ...
ValueError: Maximum value for data type smaller than new value.
>>> v10 = 12345.67894
>>> float32.cast_check(v10)  
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)[source]

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)  
Traceback (most recent call last):
  ...
ValueError: Could not deduce type from expr.
class sympy.codegen.ast.Variable[source]

Represents a variable

Parameters:

symbol : Symbol

attrs : iterable of Attribute instances

Will be stored as a FiniteSet.

type_ : Type (optional)

Type of the variable.

Examples

>>> from sympy import Symbol
>>> from sympy.codegen.ast import Variable, float32, integer
>>> x = Symbol('x')
>>> 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

classmethod deduced(symbol, attrs=EmptySet())[source]

Alt. constructor with type deduction from Type.from_expr.

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
Type(name='real')
>>> z = Symbol('z', complex=True)
>>> Variable.deduced(z).type == complex_
True
value_const

Boolean value describing whether the value is constant.

sympy.codegen.ast.aug_assign(lhs, op, rhs)[source]

Create ‘lhs op= rhs’.

Represents augmented variable assignment for code generation. This is a convenience function. You can also use the AugmentedAssignment classes directly, like AddAugmentedAssignment(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)