Metadata-Version: 2.4
Name: nexus-ml-metrics
Version: 0.0.1
Summary: NEXUS: A Novel Energy eXamination Using Switching-activity-based Tokens — Physics-grounded energy efficiency framework for machine learning systems
Project-URL: Homepage, https://github.com/jemsbhai/nexus-ml
Project-URL: Repository, https://github.com/jemsbhai/nexus-ml
Project-URL: Documentation, https://github.com/jemsbhai/nexus-ml/tree/main/docs
Project-URL: Issues, https://github.com/jemsbhai/nexus-ml/issues
Author-email: Muntaser Syed <msyed2020@my.fit.edu>
License: MIT
License-File: LICENSE
Keywords: energy-efficiency,green-ai,machine-learning,power-measurement,sustainable-ml,transistor-operations
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Provides-Extra: all
Requires-Dist: fvcore>=0.1.5; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: mypy>=1.7; extra == 'all'
Requires-Dist: plotly>=5.18; extra == 'all'
Requires-Dist: pre-commit>=3.6; extra == 'all'
Requires-Dist: psutil>=5.9; extra == 'all'
Requires-Dist: pynvml>=11.5; extra == 'all'
Requires-Dist: pytest-cov>=4.1; extra == 'all'
Requires-Dist: pytest-mock>=3.12; extra == 'all'
Requires-Dist: pytest>=7.4; extra == 'all'
Requires-Dist: ruff>=0.1; extra == 'all'
Requires-Dist: scikit-learn>=1.3; extra == 'all'
Requires-Dist: torch>=2.1; extra == 'all'
Requires-Dist: xgboost>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.7; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: measurement
Requires-Dist: psutil>=5.9; extra == 'measurement'
Requires-Dist: pynvml>=11.5; extra == 'measurement'
Provides-Extra: pytorch
Requires-Dist: fvcore>=0.1.5; extra == 'pytorch'
Requires-Dist: torch>=2.1; extra == 'pytorch'
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.3; extra == 'sklearn'
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.8; extra == 'visualization'
Requires-Dist: plotly>=5.18; extra == 'visualization'
Provides-Extra: xgboost
Requires-Dist: xgboost>=2.0; extra == 'xgboost'
Description-Content-Type: text/markdown

# NEXUS-ML

**NEXUS: A Novel Energy eXamination Using Switching-activity-based Tokens**

A physics-grounded energy efficiency framework for machine learning systems.

> ⚠️ **Pre-alpha**: This package is under active development as part of PhD research.

## Overview

NEXUS moves beyond traditional FLOP-based energy proxies to transistor-level energy modeling derived from semiconductor circuit physics. It provides a complete pipeline for understanding, measuring, and optimizing the energy consumption of ML models.

### The Problem

FLOPs are a poor proxy for energy consumption. A single memory access costs 100× more energy than a compute operation, yet FLOP counts treat all operations equally. This leads to misleading efficiency comparisons and misguided optimization efforts.

### The NEXUS Approach

NEXUS uses β-coefficients derived from Horowitz (ISSCC 2014) semiconductor data to decompose model energy into transistor operations, then computes six novel metrics that reveal where energy actually goes:

| Metric | What It Measures |
|--------|-----------------|
| **SAF-T** | Switching Activity Factor per Token |
| **LSRT** | Logic State Residence Time |
| **ECU** | Energy per Capability Unit |
| **MCER** | Memory-Compute Energy Ratio |
| **DDEV** | Data-Dependent Energy Variation |
| **CpTO** | Capability per Transistor Operation |

## Pipeline

```
Analyze → Measure → Diagnose → Recommend → Optimize
```

1. **Analyze**: Profile a model — compute FLOPs (baseline) and transistor operations (NEXUS)
2. **Measure**: Collect actual hardware energy measurements (GPU via NCU, CPU power monitors)
3. **Diagnose**: Identify energy bottlenecks at the layer/operation level
4. **Recommend**: Propose targeted optimizations ranked by expected energy impact
5. **Optimize**: Apply optimizations (quantization, pruning, activation swaps) guided by NEXUS metrics

## Installation

```bash
# Core (metrics computation only)
pip install nexus-ml

# With PyTorch support
pip install nexus-ml[pytorch]

# With hardware measurement support
pip install nexus-ml[measurement]

# Everything
pip install nexus-ml[all]
```

## Quick Start

```python
import nexus_ml

# Coming soon — API is under active development
```

## Supported Backends

### ML Frameworks
- **PyTorch** — Full support (CNNs, RNNs, Transformers)
- **XGBoost** — Gradient boosted decision trees
- **scikit-learn** — Traditional ML models
- *Extensible* — Implement `ModelBackend` for custom frameworks

### Hardware
- **NVIDIA GPU** — Via Nsight Compute (NCU) and pynvml
- **CPU** — Via system power monitoring
- *Extensible* — Implement `HardwareBackend` for custom hardware

## Development

```powershell
# Clone the repository
git clone https://github.com/jemsbhai/nexus-ml.git
cd nexus-ml

# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install in development mode with all dependencies
pip install -e ".[all]"

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ -v --cov=nexus_ml --cov-report=term
```

## Project Structure

```
nexus-ml/
├── src/nexus_ml/          # Main package
│   ├── core/              # β-coefficients, TO counting, energy model
│   ├── metrics/           # NEXUS metrics + baseline (FLOPs) metrics
│   ├── analyze/           # Model profiling & decomposition
│   ├── measure/           # Hardware energy measurement
│   ├── diagnose/          # Bottleneck identification
│   ├── recommend/         # Optimization suggestions
│   ├── optimize/          # Apply optimizations
│   ├── backends/          # ML framework adapters (pluggable)
│   ├── hardware/          # Hardware adapters (pluggable)
│   └── report/            # Visualization & export
├── tests/                 # Test suite (TDD)
├── examples/              # Usage examples
├── docs/                  # Documentation
└── packages/              # Future ports (JS/TS)
```

## Citation

If you use NEXUS in your research, please cite:

```bibtex
@inproceedings{syed2026toml,
  title={TOML: Transistor Operations for Machine Learning -- A Physics-Grounded Energy Efficiency Framework},
  author={Syed, Muntaser and Silaghi, Marius},
  booktitle={Proceedings of the Florida Artificial Intelligence Research Society (FLAIRS-39)},
  year={2026}
}
```

## License

MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

- β-coefficient data derived from Horowitz, "Computing's Energy Problem (and what we can do about it)", ISSCC 2014
- PhD research conducted at Florida Institute of Technology under Dr. Marius Silaghi
