Metadata-Version: 2.4
Name: ml-ecolyzer
Version: 1.1.0
Summary: Machine Learning Environmental Impact Analysis Framework supporting HuggingFace, scikit-learn, and PyTorch
Author: Jose Marie Antonio Minoza, Rex Gregor Laylo, Christian Villarin, Sebastian Ibanez
Author-email: Center for AI Research PH <contact@cair.ph>
Maintainer: Jose Marie Antonio Minoza
License: MIT
Project-URL: Homepage, https://github.com/JomaMinoza/ml-ecolyzer
Project-URL: Repository, https://github.com/JomaMinoza/ml-ecolyzer
Project-URL: Documentation, https://ml-ecolyzer.readthedocs.io
Project-URL: Bug Reports, https://github.com/JomaMinoza/ml-ecolyzer/issues
Project-URL: Paper, https://arxiv.org/abs/xxxx.xxxxx
Project-URL: PyPI, https://pypi.org/project/ml-ecolyzer
Project-URL: Discussions, https://github.com/JomaMinoza/ml-ecolyzer/discussions
Keywords: machine-learning,ml,environmental-impact,carbon-emissions,sustainability,pytorch,huggingface,scikit-learn,sklearn,benchmarking,green-ai,carbon-footprint,neural-networks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: codecarbon>=2.0.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: click>=8.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: joblib>=1.0.0
Provides-Extra: huggingface
Requires-Dist: torch>=1.9.0; extra == "huggingface"
Requires-Dist: transformers>=4.20.0; extra == "huggingface"
Requires-Dist: datasets>=2.0.0; extra == "huggingface"
Requires-Dist: diffusers>=0.10.0; extra == "huggingface"
Requires-Dist: evaluate>=0.3.0; extra == "huggingface"
Requires-Dist: sacrebleu>=2.0.0; extra == "huggingface"
Requires-Dist: accelerate>=0.20.0; extra == "huggingface"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.0.0; extra == "sklearn"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "sklearn"
Requires-Dist: yellowbrick>=1.4.0; extra == "sklearn"
Requires-Dist: openpyxl>=3.0.0; extra == "sklearn"
Requires-Dist: xlrd>=2.0.0; extra == "sklearn"
Provides-Extra: pytorch
Requires-Dist: torch>=1.9.0; extra == "pytorch"
Requires-Dist: torchvision>=0.10.0; extra == "pytorch"
Requires-Dist: torchaudio>=0.9.0; extra == "pytorch"
Requires-Dist: pytorch-lightning>=1.5.0; extra == "pytorch"
Requires-Dist: torchmetrics>=0.6.0; extra == "pytorch"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py3>=7.352.0; extra == "gpu"
Requires-Dist: pynvml>=11.0.0; extra == "gpu"
Provides-Extra: audio
Requires-Dist: librosa>=0.8.0; extra == "audio"
Requires-Dist: soundfile>=0.10.0; extra == "audio"
Requires-Dist: jiwer>=2.0.0; extra == "audio"
Requires-Dist: torchaudio>=0.9.0; extra == "audio"
Provides-Extra: vision
Requires-Dist: opencv-python>=4.5.0; extra == "vision"
Requires-Dist: pillow>=8.0.0; extra == "vision"
Requires-Dist: torchvision>=0.10.0; extra == "vision"
Provides-Extra: tracking
Requires-Dist: wandb>=0.13.0; extra == "tracking"
Requires-Dist: rich>=12.0.0; extra == "tracking"
Provides-Extra: metrics
Requires-Dist: sentence-transformers>=2.0.0; extra == "metrics"
Requires-Dist: scipy>=1.7.0; extra == "metrics"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Requires-Dist: plotly>=5.0.0; extra == "visualization"
Requires-Dist: ipywidgets>=7.6.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: pre-commit>=2.15.0; extra == "dev"
Requires-Dist: memory-profiler>=0.60.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: myst-parser>=0.15; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.12; extra == "docs"
Requires-Dist: nbsphinx>=0.8.0; extra == "docs"
Requires-Dist: jupyter>=1.0.0; extra == "docs"
Provides-Extra: config
Requires-Dist: omegaconf>=2.1.0; extra == "config"
Requires-Dist: hydra-core>=1.1.0; extra == "config"
Provides-Extra: research
Requires-Dist: jupyter>=1.0.0; extra == "research"
Requires-Dist: notebook>=6.4.0; extra == "research"
Requires-Dist: ipykernel>=6.0.0; extra == "research"
Requires-Dist: requests>=2.25.0; extra == "research"
Provides-Extra: all
Requires-Dist: torch>=1.9.0; extra == "all"
Requires-Dist: transformers>=4.20.0; extra == "all"
Requires-Dist: datasets>=2.0.0; extra == "all"
Requires-Dist: diffusers>=0.10.0; extra == "all"
Requires-Dist: evaluate>=0.3.0; extra == "all"
Requires-Dist: sacrebleu>=2.0.0; extra == "all"
Requires-Dist: accelerate>=0.20.0; extra == "all"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "all"
Requires-Dist: yellowbrick>=1.4.0; extra == "all"
Requires-Dist: openpyxl>=3.0.0; extra == "all"
Requires-Dist: xlrd>=2.0.0; extra == "all"
Requires-Dist: torchvision>=0.10.0; extra == "all"
Requires-Dist: torchaudio>=0.9.0; extra == "all"
Requires-Dist: pytorch-lightning>=1.5.0; extra == "all"
Requires-Dist: torchmetrics>=0.6.0; extra == "all"
Requires-Dist: nvidia-ml-py3>=7.352.0; extra == "all"
Requires-Dist: pynvml>=11.0.0; extra == "all"
Requires-Dist: librosa>=0.8.0; extra == "all"
Requires-Dist: soundfile>=0.10.0; extra == "all"
Requires-Dist: jiwer>=2.0.0; extra == "all"
Requires-Dist: opencv-python>=4.5.0; extra == "all"
Requires-Dist: pillow>=8.0.0; extra == "all"
Requires-Dist: wandb>=0.13.0; extra == "all"
Requires-Dist: rich>=12.0.0; extra == "all"
Requires-Dist: sentence-transformers>=2.0.0; extra == "all"
Requires-Dist: scipy>=1.7.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: seaborn>=0.11.0; extra == "all"
Requires-Dist: plotly>=5.0.0; extra == "all"
Requires-Dist: ipywidgets>=7.6.0; extra == "all"
Requires-Dist: omegaconf>=2.1.0; extra == "all"
Requires-Dist: jupyter>=1.0.0; extra == "all"
Requires-Dist: requests>=2.25.0; extra == "all"
Requires-Dist: memory-profiler>=0.60.0; extra == "all"
Provides-Extra: minimal
Requires-Dist: scikit-learn>=1.0.0; extra == "minimal"
Requires-Dist: joblib>=1.0.0; extra == "minimal"
Provides-Extra: text
Requires-Dist: torch>=1.9.0; extra == "text"
Requires-Dist: transformers>=4.20.0; extra == "text"
Requires-Dist: datasets>=2.0.0; extra == "text"
Requires-Dist: evaluate>=0.3.0; extra == "text"
Requires-Dist: sacrebleu>=2.0.0; extra == "text"
Provides-Extra: cv
Requires-Dist: torch>=1.9.0; extra == "cv"
Requires-Dist: torchvision>=0.10.0; extra == "cv"
Requires-Dist: opencv-python>=4.5.0; extra == "cv"
Requires-Dist: pillow>=8.0.0; extra == "cv"
Provides-Extra: classical
Requires-Dist: scikit-learn>=1.0.0; extra == "classical"
Requires-Dist: imbalanced-learn>=0.8.0; extra == "classical"
Requires-Dist: yellowbrick>=1.4.0; extra == "classical"
Requires-Dist: openpyxl>=3.0.0; extra == "classical"
Requires-Dist: xlrd>=2.0.0; extra == "classical"
Dynamic: license-file

# ML-EcoLyzer: Machine Learning Environmental Impact Analysis Framework

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/ml-ecolyzer.svg)](https://badge.fury.io/py/ml-ecolyzer)

**ML-EcoLyzer** is a reproducible benchmarking and analysis framework for quantifying the environmental cost of machine learning inference. It supports modern transformers, vision models, and classical ML pipelines, adaptable to both edge and datacenter-scale deployments.

---

![ML-EcoLyzer Overview](docs/assets/ml_ecolyzer.png)  
*Environmental profiling across tasks, models, and hardware tiers.*

---

## 🌍 Key Features

- **Inference-Centric Analysis**: Quantifies CO₂ emissions, energy use, and water impact from real-time inference
- **Cross-Hardware Profiling**: Supports A100, T4, RTX, GTX, and CPU-only setups
- **Model-Agnostic Framework**: Runs LLMs, ViTs, audio models, and traditional ML
- **ESS Metric**: Introduces the Environmental Sustainability Score for normalized emissions comparison
- **Quantization Insights**: Analyzes FP16 and INT8 savings for sustainable deployment
- **Frequency-Aware Monitoring**: Adjusts sampling dynamically for short and long-running workloads
- **Lightweight and Extensible**: Runs on mobile, edge, and low-resource devices

---

## 📊 What It Measures

### ✅ CO₂ Emissions  
- Based on PUE, regional carbon intensity, and power consumption  
- Adaptive to cloud, desktop, or edge scenarios

### ✅ Energy Usage  
- Instantaneous power profiling via NVIDIA-SMI, `psutil`, or RAPL  
- Sample-level granularity for each inference configuration

### ✅ Water Footprint  
- Derived from power-to-water coefficients by tier (e.g., datacenter vs. mobile)

### ✅ Environmental Sustainability Score (ESS) Metric  

$$\text{ESS} = \frac{\text{Effective Parameters (M)}}{\text{CO₂ (g)}}$$

- A normalized environmental efficiency metric for sustainable ML comparisons

---

## 🔧 Installation

```bash
pip install ml-ecolyzer
```

---

## 🚀 Quick Example

```python
from mlecolyzer import EcoLyzer

config = {
    "project": "sustainability_demo",
    "models": [{"name": "gpt2", "task": "text"}],
    "datasets": [{"name": "wikitext", "task": "text"}]
}

eco = EcoLyzer(config)
results = eco.run()

print(f"CO₂: {results['final_report']['analysis_summary']['total_co2_emissions_kg']:.6f} kg")
```

---

## 📚 Scientific Foundation

Built on rigorously defined environmental assessment literature and standards:

- IEEE 754 (numeric precision)
- ASHRAE TC 9.9 (thermal/infra cooling)
- JEDEC JESD51 (thermal/power envelopes)
- Strubell et al. (2019), Patterson et al. (2021), Henderson et al. (2020), Lacoste et al. (2019)

---

## 🔬 Benchmark Coverage

- 1,500+ inference runs
- 4 hardware tiers: GTX 1650, RTX 4090, Tesla T4, A100
- Tasks: text, audio, vision, classification, regression
- Model families: GPT-2, OPT, Qwen, LLaMA, Phi, Whisper, ViT, etc.
- Precisions: FP32, FP16, INT8

---

## 🛠️ Configuration Template

```yaml
project: "ml_sustainability_benchmark"

models:
  - name: "facebook/opt-2.7b"
    task: "text"
    quantization:
      enabled: true
      method: "dynamic"
      target_dtype: "int8"

datasets:
  - name: "wikitext"
    task: "text"
    limit: 1000

monitoring:
  frequency_hz: 5
  enable_quantization_analysis: true

hardware:
  device_profile: "auto"

output:
  export_formats: ["json", "csv"]
  output_dir: "./results"
```

---

## 🧪 Research Insights

### Quantization Efficiency

```text
INT8 models show up to 74% higher ESS than FP32 equivalents.
```

### Hardware Utilization

```text
A100 performs worst in ESS when underutilized; RTX/T4 yield better emissions-per-parameter for single-batch workloads.
```

### Task-Wise Trends

```text
Traditional models like SVC or Logistic Regression incur high ECEP due to small parameter count, despite low energy.
```

---

## 📜 Citation

```bibtex
@inproceedings{mlecolyzer2025,
  title={ML-EcoLyzer: Comprehensive Environmental Impact Analysis for Machine Learning Systems},
  author={Minoza, Jose Marie Antonio and Laylo, Rex Gregor and Villarin, Christian and Ibanez, Sebastian},
  booktitle={Proceedings of the Asian Conference on Machine Learning (ACML)},
  year={2025}
}
```

---
**ML-EcoLyzer** — Advancing sustainable inference in resource-constrained and production-scale deployments. 🌱
