# FEM Solver Performance Optimization Summary

## Evolution of Performance

### Baseline: Original Python (v2)
```
Element assembly:     ~120 ms (75.6%)
Postprocessing:       ~36 ms (22.5%)
Other:                ~3 ms (1.9%)
────────────────────────────────
Total per timestep:   ~159 ms
```

### Stage 1: Pre-computation + Numba (v3, all output)
```
Element assembly:     ~8 ms (35.1%)
Postprocessing:      ~13 ms (52.3%)  ← Still biggest bottleneck!
Linear solve:        ~2.5 ms (10.4%)
Other:               ~0.5 ms (2.2%)
────────────────────────────────
Total per timestep:  ~24 ms
Speedup from baseline: 6.6x
```

### Stage 2: On-Demand Flux Computation (v3, current)
**Non-output steps (90% of timesteps):**
```
Element assembly:     ~7.5 ms (76.5%)
Linear solve:        ~2.1 ms (21.4%)
Other:               ~0.3 ms (2.1%)
Postprocessing:      SKIPPED
File I/O:            SKIPPED
────────────────────────────────
Total per timestep:  ~9.8 ms
```

**Output steps (10% of timesteps):**
```
Element assembly:     ~7.5 ms (32.8%)
Postprocessing:      ~12.8 ms (56.1%)
Linear solve:        ~2.1 ms (9.1%)
Other:               ~0.5 ms (2.0%)
────────────────────────────────
Total per timestep:  ~23 ms
```

**Average across all timesteps:**
- Average = (90% × 9.8ms) + (10% × 23ms) = 11.1 ms
- **Speedup from Stage 1: 2.2x**
- **Speedup from baseline: 14.3x**

## Performance Breakdown

| Stage | Per Step | Speedup vs Original | Total Time (80 steps) |
|-------|----------|---------------------|----------------------|
| Original Python | 159 ms | 1.0x | 12.7 s |
| Pre-comp + Numba | 24 ms | 6.6x | 1.9 s |
| + On-demand flux | 11 ms | 14.3x | 0.9 s |

## Key Optimization: On-Demand Flux Computation

### The Problem
- Postprocessing (heat flux calculation) was taking 52% of runtime
- But output was only needed every 10 timesteps
- Computing flux every timestep = wasted computation

### The Solution
```python
# Only compute flux when writing output
write_output = (t % output_freq == 0) or (t == nt - 1)

if write_output:
    # Compute heat flux and write to file
    Q_x, Q_y = compute_heat_flux_numba(...)
    writer.write_data(...)
else:
    # Skip postprocessing entirely
    pass
```

### Impact
- **90% of timesteps:** Skip postprocessing → 2.4x faster
- **10% of timesteps:** Still compute flux for output
- **Net result:** 2.2x overall speedup

## Configuration

Users can control output frequency in `main()`:
```python
time_params = TimeParams(
    dt=0.015,
    nt=80,
    output_freq=10  # Write every 10 steps
)
```

Set `output_freq=1` for every timestep (like original).
Set `output_freq=10` or higher for faster simulations with less output.

## Remaining Bottlenecks

After on-demand optimization, the time is now dominated by:
1. **Element assembly: 76.5%** (~7.5 ms)
2. **Linear solve: 21.4%** (~2.1 ms)
3. **Other: 2.1%** (~0.3 ms)

### Next Optimization Opportunities

**1. Parallelize Element Assembly (Highest Impact)**
- Use `numba.prange` to parallelize the element loop
- Expected speedup: 2-4x on multi-core CPUs
- Implementation: Change `range(nel)` → `prange(nel)`

**2. Element Blocking + Vectorization**
- Process elements in blocks for better cache locality
- Expected speedup: 1.5-2x additional
- More complex to implement

**3. Optimize Linear Solver**
- Linear solve is already using scipy sparse solver
- Limited optimization potential without changing algorithm

### Theoretical Best Case
With parallelization (4 cores):
- Element assembly: 7.5ms / 4 = 1.9 ms
- Linear solve: 2.1 ms (not parallelizable)
- Total: ~4 ms per timestep
- **Overall speedup from original: ~40x**

## Educational Value

This optimization demonstrates:
1. **Profiling first:** Identified postprocessing as bottleneck
2. **Quick wins:** On-demand computation = big impact, low effort
3. **Trade-offs:** Less frequent output for faster simulation
4. **Incremental improvement:** Step-by-step optimization strategy

Perfect for teaching students about:
- Performance profiling
- Algorithmic optimization (not just JIT)
- The cost of I/O operations
- Making informed optimization choices