tessl/pypi-pyccel
Python-to-Fortran/C transpiler for scientific high-performance computing that automatically converts Python code into optimized low-level code.
—
Pending
decorators.mddocs/
Decorators
Function decorators that provide fine-grained control over transpilation behavior, optimization hints, and code generation options for enhanced performance.
Capabilities
Performance Optimization Decorators
Decorators that influence code generation and optimization strategies for improved performance.
from pyccel.decorators import pure, elemental, inline
def pure(f):
"""
Mark function as pure (no side effects).
Indicates that the function has no side effects and its output
depends only on its inputs. Enables aggressive optimizations.
Parameters:
- f: Function to mark as pure
Returns:
Original function (decorator is a compile-time hint)
"""
def elemental(f):
"""
Mark function as elemental for array operations.
Indicates that the function can be applied element-wise to arrays,
enabling vectorization and parallel execution optimizations.
Parameters:
- f: Function to mark as elemental
Returns:
Original function (decorator is a compile-time hint)
"""
def inline(f):
"""
Inline function calls for performance.
Indicates that function calls should print the function body
directly instead of generating a function call, reducing
call overhead for small functions.
Parameters:
- f: Function to inline
Returns:
Original function (decorator is a compile-time hint)
"""Usage examples:
from pyccel.decorators import pure, elemental, inline
@pure
def square(x):
"""Pure function - no side effects."""
return x * x
@elemental
def add_arrays(a, b):
"""Elemental function - operates element-wise."""
return a + b
@inline
def small_computation(x, y):
"""Small function to be inlined."""
return x * 2 + y * 3Memory Management Decorators
Decorators that control memory allocation and access patterns for arrays.
from pyccel.decorators import stack_array, allow_negative_index
def stack_array(f, *args):
"""
Store specified arrays on the stack instead of heap.
Decorator indicates that arrays mentioned in args should be stored
on the stack for faster access, suitable for small, fixed-size arrays.
Parameters:
- f: Function to which decorator is applied
- args: list of str
Names of arrays to store on stack
Returns:
Decorator function that returns original function
"""
def allow_negative_index(f, *args):
"""
Enable negative indexing for specified arrays.
Decorator indicates that arrays mentioned in args can be accessed
with negative indexes. Uses modulo function for non-constant indexing,
which may impact performance.
Parameters:
- f: Function to which decorator is applied
- args: list of str
Names of arrays that support negative indexing
Returns:
Decorator function that returns original function
"""Usage examples:
from pyccel.decorators import stack_array, allow_negative_index
import numpy as np
@stack_array('temp_array', 'result')
def matrix_computation(input_data):
"""Function with stack-allocated temporary arrays."""
temp_array = np.zeros(10) # Allocated on stack
result = np.zeros(5) # Allocated on stack
# ... computation logic
return result
@allow_negative_index('data', 'indices')
def process_with_negative_indexing(data, indices):
"""Function that supports negative array indexing."""
# Can use data[-1], data[-2], etc.
return data[indices[-1]] + data[indices[-2]]Compilation Control Decorators
Decorators that control the transpilation process and code generation behavior.
from pyccel.decorators import bypass, private, sympy
def bypass(f):
"""
Bypass Pyccel processing for the function.
Indicates that the function should not be transpiled by Pyccel
and should remain as native Python code.
Parameters:
- f: Function to bypass
Returns:
Original function unchanged
"""
def private(f):
"""
Mark function as private to the module.
Indicates that the function should not be exposed in the
public interface of the generated code.
Parameters:
- f: Function to mark as private
Returns:
Original function (decorator is a compile-time hint)
"""
def sympy(f):
"""
Enable SymPy integration for the function.
Indicates that the function may use SymPy expressions
and should be processed with SymPy support enabled.
Parameters:
- f: Function with SymPy integration
Returns:
Original function (decorator is a compile-time hint)
"""Usage examples:
from pyccel.decorators import bypass, private, sympy
import sympy as sp
@bypass
def debug_function(data):
"""This function remains in Python (not transpiled)."""
print(f"Debug: processing {len(data)} items")
return data
@private
def internal_helper(x, y):
"""Private function not exposed in public interface."""
return x * y + 1
@sympy
def symbolic_computation(expr, x_val):
"""Function that works with SymPy expressions."""
return expr.subs('x', x_val)Decorator Combinations
Multiple decorators can be combined for fine-grained control:
from pyccel.decorators import pure, elemental, inline, stack_array
@pure
@elemental
@inline
@stack_array('temp')
def optimized_function(a, b):
"""Highly optimized function with multiple decorators."""
temp = a + b # Stack allocated
return temp * temp # Pure, elemental, inlinedImportant Notes
Decorator Behavior
- All decorators return the original function unchanged at runtime
- Decorators provide compile-time hints to the Pyccel transpiler
- They have no effect when functions are run in pure Python mode
- Decorator effects only apply when code is transpiled via epyccel or command-line tools
Performance Considerations
@pureenables aggressive optimizations but requires no side effects@elementalenables vectorization but requires element-wise operations@inlinereduces call overhead but may increase code size@stack_arrayimproves access speed but limited by stack size@allow_negative_indexadds modulo operations, potentially reducing performance
Module Import
from pyccel.decorators import (
allow_negative_index,
bypass,
elemental,
inline,
private,
pure,
stack_array,
sympy,
)Install with Tessl CLI
npx tessl i tessl/pypi-pyccel