Documentation

Your First Optimization

Step-by-step guide to optimizing your first function.

The Problem: Slow Python Loops

Here's a typical CPU-bound Python function that's too slow:

import time
def calculate_statistics(data):
    results = []
    window_size = 50
    
    for i in range(len(data) - window_size):
        window = data[i:i + window_size]
        mean = sum(window) / window_size
        variance = sum((x - mean) ** 2 for x in window) / window_size
        results.append((mean, variance ** 0.5))
    
    return results
data = [i * 0.1 for i in range(100000)]
start = time.perf_counter()
results = calculate_statistics(data)
print(f"Time: {time.perf_counter() - start:.2f}s")

This takes 15-30 seconds on most systems.

Step 1: Add Epochly

Add one line — the @epochly.optimize decorator:

import epochly
import time
@epochly.optimize
def calculate_statistics(data):
    results = []
    window_size = 50
    
    for i in range(len(data) - window_size):
        window = data[i:i + window_size]
        mean = sum(window) / window_size
        variance = sum((x - mean) ** 2 for x in window) / window_size
        results.append((mean, variance ** 0.5))
    
    return results
data = [i * 0.1 for i in range(100000)]
start = time.perf_counter()
results = calculate_statistics(data)
print(f"Time: {time.perf_counter() - start:.2f}s")

Now runs significantly faster with Epochly's optimization levels.

Step 2: Understanding Output

When you run the optimized code, Epochly shows what it's doing:

[Epochly] Analyzing: calculate_statistics
[Epochly] Pattern: nested_loop_numeric
[Epochly] Enhancement: Level 2 (JIT)
[Epochly] First call: 0.8s (compilation)
[Epochly] Subsequent: 0.02s
[Epochly] Verification: PASSED

What this means:

  • Epochly detected a nested loop pattern
  • Applied Level 2 (JIT compilation)
  • First call was slow (compilation overhead)
  • Subsequent calls are dramatically faster
  • Result verification passed

Step 3: Control Enhancement Level

You can control which level Epochly uses:

@epochly.optimize(level=3)       # Force multicore
@epochly.optimize(level="auto")  # Let Epochly choose (default)
@epochly.optimize(max_level=2)   # Cap at JIT (no multicore)
@epochly.optimize(disabled=True) # Temporarily disable

Step 4: Verify Results

Always verify results match vanilla Python:

import epochly
@epochly.optimize
def my_function(x):
    return x * 2 + 1
# Epochly automatically verifies results on first call
result = my_function(10)  # Returns 21, verification passes
# Manual verification
epochly.verify(my_function, args=(10,))

What Gets Accelerated?

Epochly accelerates these patterns:

  • Nested loops with numeric operations
  • List/array processing (map, filter, reduce patterns)
  • Mathematical computations (statistics, physics, finance)
  • Data transformation pipelines
  • Simulation and Monte Carlo
  • Custom pandas apply() functions

What Doesn't Benefit?

  • I/O-bound code (file reads, network calls) → ~1.0x
  • Already vectorized NumPy → ~1.0x (already C-optimized)
  • Very small workloads → overhead > benefit
  • Complex object methods → difficult to optimize

Next Steps

Previous
System Requirements
Next
Overview