End-to-end pipeline: from user input through profiling, energy estimation, carbon calculation, AGCM scoring, to visualization.
9-stage processing pipeline from input to green recommendation
How every module connects and interacts within the AGCM system
Entry point. CLI or Streamlit interface. Orchestrates all modules.
Global constants: CPU power, energy units, default region & hardware.
sorting.py · fibonacci.py · graph.py — all algorithm implementations.
Wraps algorithm execution. Returns time, CPU %, memory (KB).
EnergyModel class. Computes E = P × t in millijoules.
CarbonCalculator class. Uses regions.py for R_c lookup.
Core AGCM computation. Combines all metrics into final score.
Ranks algorithms by AGCM. Generates textual recommendations.
Filters algorithms exceeding user-defined CO₂ budget.
matplotlib bar, scatter, line charts. Exports PNG.
pandas DataFrame formatting. tabulate output for CLI.
CSV export, PNG charts, CLI summary, Streamlit dashboard.
What each module receives and what it returns
| # | Module | Receives | Returns | Data Type |
|---|---|---|---|---|
| 1 | User Input Layer | CLI args / Streamlit form | Config object | dict / dataclass |
| 2 | Algorithm Loader | Algorithm name, input size n | Algorithm function reference + input data | callable list |
| 3 | Runtime Profiler | Algorithm function + data | ProfileResult(time_s, cpu_pct, memory_kb) | dataclass |
| 4 | Energy Model | time_s, cpu_watt | energy_mJ (float) | float |
| 5 | Carbon Calculator | energy_mJ, region_key | carbon_mg (float) | float |
| 6 | AGCM Engine | complexity_order, E_unit, H_f, R_c, n | agcm_score (float) | float |
| 7 | Recommender | List[AlgorithmResult] | Ranked list + recommendation strings | list[dataclass] str |
| 8 | Budget Mode | List[AlgorithmResult], budget_mg | Compliant list, Filtered list | list[dataclass] |
| 9 | Visualization | List[AlgorithmResult], charts config | matplotlib figures / pandas tables / Streamlit widgets | Figure DataFrame |
Step-by-step mathematical foundation of the Adaptive Green Complexity Metric
Traditional Big-O gives us the operation count growth rate. We use a complexity multiplier to convert this to an absolute operation estimate for input size n.
Where P_cpu is the CPU's TDP in watts and t_exec is the measured execution time in seconds. We then normalize to get E_unit = E_total / f(n) — energy cost per logical operation.
R_c is the regional carbon intensity (gCO₂/kWh). We convert E_total from joules to kWh first: E_kWh = E_total / 3,600,000.
H_f accounts for hardware efficiency. An ARM laptop (H_f = 0.6) uses less energy than a legacy desktop (H_f = 1.5) for the same algorithm and input size.
The AGCM score integrates all four dimensions. A lower AGCM score means the algorithm is greener and more carbon-efficient in the given hardware and regional context.
| Symbol | Meaning | Units | Source |
|---|---|---|---|
| n | Input size | integer | User input |
| O(f(n)) | Time complexity order multiplier | dimensionless | Algorithm metadata |
| E_unit | Energy per operation | nJ/op | energy_model.py |
| H_f | Hardware efficiency factor | dimensionless [0.6–1.5] | config/settings.py |
| R_c | Regional carbon intensity | gCO₂/kWh | carbon/regions.py |
| AGCM | Adaptive Green Complexity Metric | μgCO₂-equivalent | agcm/agcm_engine.py |
Time, space, and expected AGCM ranking for all implemented algorithms
| Algorithm | Category | Best | Average | Worst | Space | AGCM Rank | Green? |
|---|---|---|---|---|---|---|---|
| Quick Sort | Sorting | O(n log n) | O(n log n) | O(n²) | O(log n) | 🥇 1st | ✅ Yes |
| Merge Sort | Sorting | O(n log n) | O(n log n) | O(n log n) | O(n) | 🥈 2nd | ✅ Yes |
| Insertion Sort | Sorting | O(n) | O(n²) | O(n²) | O(1) | 🥉 3rd | ⚠️ Small n |
| Bubble Sort | Sorting | O(n) | O(n²) | O(n²) | O(1) | 4th | ❌ No |
| Memo Fibonacci | Recursion | O(n) | O(n) | O(n) | O(n) | 🥇 1st | ✅ Yes |
| Naive Fibonacci | Recursion | O(2ⁿ) | O(2ⁿ) | O(2ⁿ) | O(n) | 2nd | ❌ No |
| DFS | Graph | O(V+E) | O(V+E) | O(V+E) | O(V) | 🥇 1st | ✅ Yes |
| BFS | Graph | O(V+E) | O(V+E) | O(V+E) | O(V) | 2nd | ⚠️ Memory |
How experiments are designed for reproducibility and academic rigor
time.perf_counter() — microsecond precisionpsutil.cpu_percent(interval=None) before and aftertracemalloc.get_traced_memory() peak allocation