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
Impementation 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 and python 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
- 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 can not be
translated into c. ccode(integrate(sin(x)/x, x)) does not make sense.
- Complex numbers as input and output
- A default complex datatype
- Include extra information in the header: date, user, hostname, sha1
hash, ...
- Fortran 77
- C++
- Python
- ...
-
class sympy.utilities.codegen.Routine(name, expr, argument_sequence=None)
Generic description of an evaluation routine for a set of sympy expressions.
A CodeGen class can translate instances of this class into C/Fortran/...
code. 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.
-
result_variables
Returns a list of OutputArgument, InOutArgument and Result.
If return values are present, they are at the end ot the list.
-
variables
Returns a set containing all variables possibly used in this routine.
For routines with unnamed return values, the dummies that may or may
not be used will be included in the set.
-
class sympy.utilities.codegen.DataType(cname, fname, pyname)
Holds strings for a certain datatype in different programming languages.
-
sympy.utilities.codegen.get_default_datatype(expr)
Derives a decent data type based on the assumptions on the expression.
-
class sympy.utilities.codegen.Argument(name, datatype=None, dimensions=None, precision=None)
An abstract Argument data structure: a name and a data type.
This structure is refined in the descendants below.
-
class sympy.utilities.codegen.Result(expr, datatype=None, precision=None)
An expression for a scalar 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.
-
class sympy.utilities.codegen.CodeGen(project='project')
Abstract class for the code generators.
-
dump_code(routines, f, prefix, header=True, empty=True)
Write the code file by calling language specific methods in correct order
The generated file contains all the definitions of the routines in
low-level code and refers to the header file if appropriate.
- routines
- A list of Routine instances
- f
- A file-like object to write the file to
- prefix
- The filename prefix, used to refer to the proper header file. Only
the basename of the prefix is used.
- header
- When True, a header comment is included on top of each source file.
[DEFAULT=True]
- empty
- When True, empty lines are included to structure the source files.
[DEFAULT=True]
-
write(routines, prefix, to_files=False, header=True, empty=True)
Writes all the source code files for the given routines.
The generate source is returned as a list of (filename, contents)
tuples, or is written to files (see options). Each filename consists
of the given prefix, appended with an appropriate extension.
- routines
- A list of Routine instances to be written
- prefix
- The prefix for the output files
- to_files
- When True, the output is effectively written to files.
[DEFAULT=False] Otherwise, a list of (filename, contents)
tuples is returned.
- header
- When True, a header comment is included on top of each source
file. [DEFAULT=True]
- empty
- When True, empty lines are included to structure the source
files. [DEFAULT=True]
-
class sympy.utilities.codegen.CCodeGen(project='project')
Generator for C code
The .write() method inherited from CodeGen will output a code file and an
inteface file, <prefix>.c and <prefix>.h respectively.
-
dump_c(routines, f, prefix, header=True, empty=True)
Write the code file by calling language specific methods in correct order
The generated file contains all the definitions of the routines in
low-level code and refers to the header file if appropriate.
- routines
- A list of Routine instances
- f
- A file-like object to write the file to
- prefix
- The filename prefix, used to refer to the proper header file. Only
the basename of the prefix is used.
- header
- When True, a header comment is included on top of each source file.
[DEFAULT=True]
- empty
- When True, empty lines are included to structure the source files.
[DEFAULT=True]
-
dump_h(routines, f, prefix, header=True, empty=True)
Writes the C header file.
This file contains all the function declarations.
- routines
- A list of Routine instances
- f
- A file-like object to write the file to
- prefix
- The filename prefix, used to construct the include guards.
- header
- When True, a header comment is included on top of each source
file. [DEFAULT=True]
- empty
- When True, empty lines are included to structure the source
files. [DEFAULT=True]
-
get_prototype(routine)
Returns a string for the function prototype for the given routine.
If the routine has multiple result objects, an CodeGenError is
raised.
See: http://en.wikipedia.org/wiki/Function_prototype
-
class sympy.utilities.codegen.FCodeGen(project='project')
Generator for Fortran 95 code
The .write() method inherited from CodeGen will output a code file and an
inteface file, <prefix>.f90 and <prefix>.h respectively.
-
dump_f95(routines, f, prefix, header=True, empty=True)
Write the code file by calling language specific methods in correct order
The generated file contains all the definitions of the routines in
low-level code and refers to the header file if appropriate.
- routines
- A list of Routine instances
- f
- A file-like object to write the file to
- prefix
- The filename prefix, used to refer to the proper header file. Only
the basename of the prefix is used.
- header
- When True, a header comment is included on top of each source file.
[DEFAULT=True]
- empty
- When True, empty lines are included to structure the source files.
[DEFAULT=True]
-
dump_h(routines, f, prefix, header=True, empty=True)
Writes the interface to a header file.
This file contains all the function declarations.
- routines
- A list of Routine instances
- f
- A file-like object to write the file to
- prefix
- The filename prefix
- header
- When True, a header comment is included on top of each source
file. [DEFAULT=True]
- empty
- When True, empty lines are included to structure the source
files. [DEFAULT=True]
-
get_interface(routine)
Returns a string for the function interface for the given routine and
a single result object, which can be None.
If the routine has multiple result objects, a CodeGenError is
raised.
See: http://en.wikipedia.org/wiki/Function_prototype
-
sympy.utilities.codegen.codegen(name_expr, language, prefix, project='project', to_files=False, header=True, empty=True, argument_sequence=None)
Write source code for the given expressions in the given language.
- name_expr
- 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.
- language
- A string that indicates the source code language. This is case
insensitive. For the moment, only ‘C’ and ‘F95’ is supported.
- prefix
- A prefix for the names of the files that contain the source code.
Proper (language dependent) suffixes will be appended.
- project
- A project name, used for making unique preprocessor instructions.
[DEFAULT=”project”]
- to_files
- 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
- When True, a header is written on top of each source file.
[DEFAULT=True]
- empty
- When True, empty lines are used to structure the code. [DEFAULT=True]
- argument_sequence
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 aguments first, and then output or in-out arguments.
>>> 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), "C", "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) {
return x + y*z;
}
>>> 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