0
# Pyccel
1

2
A Python-to-Fortran/C transpiler for scientific high-performance computing that automatically converts Python code into optimized low-level code while maintaining Python syntax. Pyccel enables significant performance improvements for mathematical and scientific computations by transpiling Python functions and classes to compiled languages, with seamless integration into existing Python workflows.
3

4
## Package Information
5

6
- **Package Name**: pyccel
7
- **Language**: Python
8
- **Installation**: `pip install pyccel`
9
- **Version**: 2.0.1
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import pyccel
16
from pyccel import epyccel, lambdify
17
```
18

19
For decorators:
20

21
```python
22
from pyccel.decorators import pure, elemental, inline, stack_array
23
```
24

25
## Basic Usage
26

27
```python
28
from pyccel import epyccel
29
import numpy as np
30

31
# Define a function to accelerate
32
def compute_sum(x, y):
33
    """Simple computation function."""
34
    return x + y
35

36
# Accelerate the function using Fortran backend
37
compute_sum_fast = epyccel(compute_sum, language='fortran')
38

39
# Use the accelerated function
40
result = compute_sum_fast(5.0, 3.0)
41
print(result)  # 8.0
42

43
# For NumPy array operations
44
def array_multiply(arr1, arr2):
45
    """Multiply two NumPy arrays element-wise."""
46
    return arr1 * arr2
47

48
# Accelerate array operations
49
array_multiply_fast = epyccel(array_multiply, language='fortran')
50

51
# Use with NumPy arrays
52
a = np.array([1.0, 2.0, 3.0])
53
b = np.array([4.0, 5.0, 6.0])
54
result = array_multiply_fast(a, b)
55
print(result)  # [4. 10. 18.]
56
```
57

58
## Architecture
59

60
Pyccel follows a multi-stage compilation pipeline:
61

62
- **Parser**: Converts Python source code to Abstract Syntax Tree (AST)
63
- **Semantic Analysis**: Type inference and validation
64
- **Code Generation**: Translates Python AST to target language (Fortran/C)
65
- **Compilation**: Compiles generated code and creates Python extensions
66
- **Runtime Integration**: Seamless integration with Python via compiled extensions
67

68
The transpiler supports both embedded mode (epyccel function) for interactive use and command-line mode for batch processing, enabling flexible integration into existing Python scientific computing workflows.
69

70
## Capabilities
71

72
### Embedded Acceleration Functions
73

74
Core functions for accelerating Python code from within Python scripts, enabling interactive transpilation and immediate performance improvements without external tooling.
75

76
```python { .api }
77
def epyccel(function_class_or_module, *, language='fortran', **kwargs): ...
78
def lambdify(expr, args, *, result_type=None, **kwargs): ...
79
```
80

81
[Embedded Acceleration](./embedded-acceleration.md)
82

83
### Command-Line Interface
84

85
Console commands for transpiling Python files and managing Pyccel projects from the command line, supporting batch processing and integration with build systems.
86

87
```bash { .api }
88
pyccel filename.py [options]
89
pyccel-clean [options]  
90
pyccel-test [options]
91
```
92

93
[Command-Line Tools](./command-line.md)
94

95
### Function Decorators
96

97
Decorators that provide fine-grained control over transpilation behavior, optimization hints, and code generation options for enhanced performance.
98

99
```python { .api }
100
@pure
101
@elemental  
102
@inline
103
@stack_array('array1', 'array2')
104
@allow_negative_index('arr')
105
```
106

107
[Decorators](./decorators.md)
108

109
### Type System Integration
110

111
Comprehensive type system supporting Python's native types, NumPy arrays, and custom data structures with automatic type inference and manual type annotations.
112

113
```python { .api }
114
# Type annotation support
115
def func(x: 'float', y: 'int[:]') -> 'float': ...
116

117
# NumPy type integration
118
from pyccel.ast.numpytypes import NumpyFloat64Type, NumpyNDArrayType
119
```
120

121
[Type System](./type-system.md)
122

123
## Types
124

125
### Exception Types
126

127
```python { .api }
128
from pyccel.errors.errors import PyccelError
129

130
class PyccelError(Exception):
131
    """Base exception for Pyccel transpilation errors."""
132
```
133

134
### Import Types
135

136
```python { .api }
137
from types import FunctionType, ModuleType
138
from typing import Union, Dict, List, Tuple, Optional, Any, Callable
139

140
# Common type aliases used throughout Pyccel
141
FunctionOrClass = Union[FunctionType, type]
142
ModuleOrString = Union[ModuleType, str]
143
AcceleratedObject = Union[FunctionType, type, ModuleType]
144
CompilerOptions = Optional[Union[str, List[str]]]
145
```
146

147
## Version Information
148

149
```python { .api }
150
import pyccel
151
print(pyccel.__version__)  # "2.0.1"
152

153
# Version components
154
from pyccel.version import __version__
155
```