Codegen¶

This module provides functionality to generate directly compilable code from SymPy expressions. 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 application. 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 compilable 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.

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 compilable 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
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 cannot 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.Argument(name, datatype=None, dimensions=None, precision=None)[source]¶

An abstract Argument data structure: a name and a data type.

This structure is refined in the descendants below.

class sympy.utilities.codegen.CCodeGen(project='project', printer=None, preprocessor_statements=None, cse=False)[source]¶

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.

dump_c(routines, f, prefix, header=True, empty=True)[source]¶

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]

dump_h(routines, f, prefix, header=True, empty=True)[source]¶

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

Returns a string for the function prototype of the routine.

If the routine has multiple result objects, an CodeGenError is raised.

See: https://en.wikipedia.org/wiki/Function_prototype

class sympy.utilities.codegen.CodeGen(project='project', cse=False)[source]¶

Abstract class for the code generators.

dump_code(routines, f, prefix, header=True, empty=True)[source]¶

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

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. Additional outputs are OutputArguments (e.g., pointers on right-hand-side or pass-by-reference). Matrices are always returned via OutputArguments. If argument_sequence is None, arguments will be ordered alphabetically, but with all InputArguments first, and then OutputArgument and InOutArguments.

write(routines, prefix, to_files=False, header=True, empty=True)[source]¶

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 (filename, 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.DataType(cname, fname, pyname, jlname, octname, rsname)[source]¶: Holds strings for a certain datatype in different languages.

class sympy.utilities.codegen.FCodeGen(project='project', printer=None)[source]¶

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.

dump_f95(routines, f, prefix, header=True, empty=True)[source]¶

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]

dump_h(routines, f, prefix, header=True, empty=True)[source]¶

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

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: https://en.wikipedia.org/wiki/Function_prototype

class sympy.utilities.codegen.JuliaCodeGen(project='project', printer=None)[source]¶

Generator for Julia code.

The .write() method inherited from CodeGen will output a code file <prefix>.jl.

dump_jl(routines, f, prefix, header=True, empty=True)[source]¶

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)[source]¶: Specialized Routine creation for Julia.

class sympy.utilities.codegen.OctaveCodeGen(project='project', printer=None)[source]¶

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

dump_m(routines, f, prefix, header=True, empty=True, inline=True)[source]¶

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)[source]¶: Specialized Routine creation for Octave.

class sympy.utilities.codegen.OutputArgument(name, result_var, expr, datatype=None, dimensions=None, precision=None)[source]¶: OutputArgument are always initialized in the routine.

class sympy.utilities.codegen.Result(expr, name=None, result_var=None, datatype=None, dimensions=None, precision=None)[source]¶

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.Routine(name, arguments, results, local_vars, global_vars)[source]¶

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

property result_variables¶

Returns a list of OutputArgument, InOutArgument and Result.

If return values are present, they are at the end of the list.

property 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.RustCodeGen(project='project', printer=None)[source]¶

Generator for Rust code.

The .write() method inherited from CodeGen will output a code file <prefix>.rs

dump_rs(routines, f, prefix, header=True, empty=True)[source]¶

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

Returns a string for the function prototype of the routine.

If the routine has multiple result objects, an CodeGenError is raised.

See: https://en.wikipedia.org/wiki/Function_prototype

routine(name, expr, argument_sequence, global_vars)[source]¶: Specialized Routine creation for Rust.

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

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) tuples. 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 insensitive. 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 CodeGenError 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, optional

code_gen : CodeGen instance, optional

An instance of a CodeGen subclass. Overrides language.

printer : Printer instance, optional

An instance of a Printer subclass.

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

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

Another example using Equality objects to give named outputs. Here the filename (prefix) 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;
}

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

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

sympy.utilities.codegen.get_default_datatype(expr, complex_allowed=None)[source]¶: Derives an appropriate datatype based on the expression.

sympy.utilities.codegen.make_routine(name, expr, argument_sequence=None, global_vars=None, language='F95')[source]¶

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 depend on the language. [default: “F95”].

Notes

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 appropriate). Otherwise, typically, the calculated expression is made a return values of the routine.

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]  
[result_5397460570204848505]
>>> [arg.expr for arg in r.results]
[x*y]
>>> [arg.name for arg in r.arguments]  
[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)]  
[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]