0
# Embedded Acceleration
1
2
Core functions for accelerating Python code from within Python scripts, enabling interactive transpilation and immediate performance improvements without external tooling.
3
4
## Capabilities
5
6
### Main Acceleration Function
7
8
Accelerates Python functions, classes, or modules using Pyccel in embedded mode, generating optimized code in the specified target language.
9
10
```python { .api }
11
from pyccel import epyccel
12
13
def epyccel(
14
function_class_or_module,
15
*,
16
language='fortran',
17
compiler_family=None,
18
compiler_config=None,
19
flags=None,
20
wrapper_flags=None,
21
debug=None,
22
include=(),
23
libdir=(),
24
libs=(),
25
folder=None,
26
mpi=False,
27
openmp=False,
28
verbose=0,
29
time_execution=False,
30
developer_mode=False,
31
conda_warnings='basic',
32
context_dict=None,
33
comm=None,
34
root=0,
35
bcast=True
36
):
37
"""
38
Accelerate Python function or module using Pyccel in embedded mode.
39
40
Parameters:
41
- function_class_or_module: function | class | module | str
42
Python function, class, module, or string code to accelerate
43
- language: {'fortran', 'c', 'python'}
44
Target language for generated code (default: 'fortran')
45
- compiler_family: {'GNU', 'intel', 'PGI', 'nvidia', 'LLVM'}
46
Compiler family (default: 'GNU')
47
- compiler_config: pathlib.Path | str
48
Path to JSON compiler configuration file
49
- flags: iterable of str
50
Additional compiler flags
51
- wrapper_flags: iterable of str
52
Compiler flags for wrapper code
53
- debug: bool
54
Compile in debug mode
55
- include: tuple
56
Additional include directories
57
- libdir: tuple
58
Additional library directories
59
- libs: tuple
60
Additional libraries to link
61
- folder: str
62
Output folder for compiled code
63
- mpi: bool
64
Enable MPI parallel execution (default: False)
65
- openmp: bool
66
Enable OpenMP parallel execution (default: False)
67
- verbose: int
68
Verbosity level (default: 0)
69
- time_execution: bool
70
Time Pyccel's internal stages
71
- developer_mode: bool
72
Enable developer error mode
73
- conda_warnings: {'off', 'basic', 'verbose'}
74
Conda warning level
75
- context_dict: dict[str, obj]
76
Additional context objects for translated code
77
- comm: mpi4py.MPI.Comm
78
MPI communicator (for parallel mode)
79
- root: int
80
MPI root process rank (default: 0)
81
- bcast: bool
82
Broadcast results to all processes (default: True)
83
84
Returns:
85
Accelerated function, class, or module
86
"""
87
```
88
89
Usage examples:
90
91
```python
92
from pyccel import epyccel
93
94
# Accelerate a simple function
95
def add_numbers(a, b):
96
return a + b
97
98
add_fast = epyccel(add_numbers, language='fortran')
99
result = add_fast(5.0, 3.0)
100
101
# Accelerate with compiler options
102
multiply_fast = epyccel(
103
lambda x, y: x * y,
104
language='c',
105
compiler_family='GNU',
106
debug=True,
107
verbose=1
108
)
109
110
# Accelerate with MPI support
111
def parallel_compute(data):
112
return sum(data)
113
114
parallel_fast = epyccel(parallel_compute, mpi=True, openmp=True)
115
```
116
117
### SymPy Expression Acceleration
118
119
Converts SymPy mathematical expressions into Pyccel-accelerated functions for fast numerical evaluation.
120
121
```python { .api }
122
from pyccel import lambdify
123
124
def lambdify(
125
expr,
126
args,
127
*,
128
result_type=None,
129
use_out=False,
130
**kwargs
131
):
132
"""
133
Convert a SymPy expression into a Pyccel-accelerated function.
134
135
Parameters:
136
- expr: sympy.Expr
137
SymPy expression to convert
138
- args: dict[sympy.Symbol, str]
139
Dictionary mapping symbols to type annotations
140
- result_type: str
141
Type annotation for function result
142
- use_out: bool
143
Modify 'out' parameter instead of returning (default: False)
144
- **kwargs: dict
145
Additional arguments passed to epyccel
146
147
Returns:
148
Pyccel-accelerated function for expression evaluation
149
"""
150
```
151
152
Usage examples:
153
154
```python
155
import sympy as sp
156
from pyccel import lambdify
157
158
# Create symbolic variables
159
x, y = sp.symbols('x y')
160
161
# Define symbolic expression
162
expr = x**2 + 2*x*y + y**2
163
164
# Convert to accelerated function
165
args = {x: 'float', y: 'float'}
166
fast_func = lambdify(expr, args, result_type='float')
167
168
# Use the accelerated function
169
result = fast_func(3.0, 4.0) # (3^2 + 2*3*4 + 4^2) = 49.0
170
171
# Array operations with SymPy
172
import numpy as np
173
arr_expr = sp.sin(x) + sp.cos(y)
174
array_args = {x: 'float[:]', y: 'float[:]'}
175
array_func = lambdify(arr_expr, array_args, result_type='float[:]')
176
177
x_vals = np.linspace(0, np.pi, 100)
178
y_vals = np.linspace(0, 2*np.pi, 100)
179
result = array_func(x_vals, y_vals)
180
```
181
182
### Utility Functions
183
184
Internal utilities for source code extraction and context management.
185
186
```python { .api }
187
from pyccel.commands.epyccel import get_source_code_and_context
188
189
def get_source_code_and_context(func_or_class):
190
"""
191
Extract source code and context from function or class.
192
193
Parameters:
194
- func_or_class: Function | type
195
Python function or class object
196
197
Returns:
198
- code: list[str]
199
Source code lines
200
- context_dict: dict[str, object]
201
Context objects for execution
202
203
Raises:
204
- TypeError: If object is not callable
205
"""
206
```
207
208
## Types
209
210
### Type Annotations
211
212
```python { .api }
213
# Common type strings for annotations
214
'int' # Integer type
215
'float' # Floating point type
216
'complex' # Complex number type
217
'bool' # Boolean type
218
'str' # String type
219
'int[:]' # 1D integer array
220
'float[:,:]' # 2D float array
221
'complex[::1]' # Contiguous 1D complex array
222
```
223
224
### Exception Types
225
226
```python { .api }
227
from pyccel.errors.errors import PyccelError
228
229
class PyccelError(Exception):
230
"""Base exception for Pyccel transpilation errors."""
231
```