eco-route 0.5.0

Thermal-aware GPU tensor routing with Active Carbon Mitigation for energy-efficient deep learning

Eco-Route

Thermal-Aware Dynamic Tensor Routing & Active Carbon Mitigation for Energy-Efficient Deep Learning

Eco-Route is a Python framework that bridges hardware physics (thermals, power draw) with software orchestration (dynamic tensor routing). It monitors NVIDIA GPUs in real-time, predicts thermal throttling before it happens, migrates workloads to cooler devices, and actively reduces carbon emissions by adjusting GPU power limits based on grid carbon intensity.

Installation

# Core package (CLI + monitoring)
pip install eco-route

# With web dashboard
pip install eco-route[dashboard]

# With TensorFlow training benchmark
pip install eco-route[train]

# With system tray app
pip install eco-route[tray]

# Everything
pip install eco-route[all]

Or install from GitHub:

pip install git+https://github.com/Navaneeth270/eco-route.git

Requirements

• Python 3.10+
• NVIDIA GPU with drivers installed (the tool will clearly tell you if no GPU is detected)
• No GPU? You can still explore with --synthetic mode for testing

Quick Start

# Check your system
eco-route info

# Live terminal monitor
eco-route monitor

# Launch web dashboard
eco-route dashboard

# Run training benchmark
eco-route train --steps 200 --batch-size 64

# System tray icon
eco-route tray

No GPU? No Problem

If you don't have an NVIDIA GPU, Eco-Route tells you clearly instead of faking data:

+------------------------------- GPU Not Found --------------------------------+
| No NVIDIA GPU detected on this system.                                       |
|                                                                              |
| Reason: NVIDIA driver not available (NVML Shared Library Not Found)          |
|                                                                              |
| Eco-Route requires an NVIDIA GPU with proper drivers to monitor              |
| real hardware telemetry (temperature, power draw, clock speed).              |
|                                                                              |
| To run with simulated data for testing, use:                                 |
|   eco-route monitor --synthetic                                              |
+------------------------------------------------------------------------------+

For testing and development, use synthetic mode:

eco-route monitor --synthetic
eco-route train --synthetic --steps 100

Features

Real-Time GPU Monitoring

• Temperature, power draw, clock speed, utilization via NVIDIA NVML
• Energy consumption tracking (Joules, kWh) with trapezoidal integration
• Carbon footprint estimation using grid carbon intensity

Thermal-Aware Tensor Routing

• Predicts GPU temperature 3 seconds ahead using scikit-learn
• Automatically migrates TensorFlow operations to cooler GPUs
• Cooldown mechanism prevents migration oscillation

Active Carbon Mitigation (ACM)

• Monitors real-time grid carbon intensity
• Dynamically caps GPU power based on grid cleanliness:
  • Clean grid (<200 gCO2/kWh): Full power
  • Moderate grid (200-400 gCO2/kWh): 85% power
  • Dirty grid (>400 gCO2/kWh): 60% power
• Tracks carbon saved vs. training time trade-off

Web Dashboard

• Real-time Streamlit dashboard with Plotly charts
• Live GPU metrics, grid carbon intensity, power draw
• Carbon Mitigation Impact visualizations (publication-ready)
• ACM toggle and training controls

System Tray App

• Taskbar icon with live GPU temperature (color-coded by grid zone)
• Quick access to dashboard and ACM toggle

Architecture

eco_route/
  telemetry.py        Async NVML GPU monitor + energy accounting
  predictor.py        Thermal forecaster (scikit-learn)
  router.py           TensorFlow device routing + ACM integration
  carbon_controller.py  Active Carbon Mitigation engine
  train_loop.py       Benchmark training loop with analytical report
  cli.py              Command-line interface
  tray_app.py         System tray application
  mock_hardware.py    Synthetic GPU telemetry for testing

app/
  dashboard.py        Streamlit web dashboard

CLI Reference

Command	Description
eco-route info	System hardware and framework detection report
eco-route monitor	Live terminal GPU & carbon monitor
eco-route monitor --synthetic	Monitor with simulated GPU data
eco-route dashboard	Launch Streamlit web dashboard
eco-route dashboard --port 8502	Dashboard on custom port
eco-route train --steps 200	Run training benchmark
eco-route train --synthetic --no-acm	Baseline without ACM
eco-route tray	Start system tray icon

License

MIT