Metadata-Version: 2.3
Name: carbonaware-ml
Version: 0.1.1
Summary: Carbon-aware PyTorch training plugin (multi-region via Electricity Maps/WattTime).
License: MIT License
         
         Copyright (c) 2025 Carbon Aware Ontario
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Keywords: pytorch,carbon,sustainability,scheduling,electricity,carbon-aware,ml
Author: Carbon Aware ML Maintainers
Requires-Python: >=3.9
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Provides-Extra: all
Provides-Extra: scheduler
Provides-Extra: tensorboard
Requires-Dist: apscheduler (>=3.10.4) ; extra == "all"
Requires-Dist: apscheduler (>=3.10.4) ; extra == "scheduler"
Requires-Dist: requests (>=2.31.0)
Requires-Dist: tensorboard (>=2.12.0) ; extra == "all"
Requires-Dist: tensorboard (>=2.12.0) ; extra == "tensorboard"
Requires-Dist: torch (>=2.0.0)
Project-URL: Homepage, https://github.com/tomalmog/carbonaware-ml
Project-URL: Issues, https://github.com/tomalmog/carbonaware-ml/issues
Project-URL: Repository, https://github.com/tomalmog/carbonaware-ml
Description-Content-Type: text/markdown

### Carbon Aware ML

Carbon-aware training for PyTorch that pauses or schedules training based on real-time grid carbon intensity (and optionally electricity prices). Works in any region supported by Electricity Maps or WattTime. Each user supplies their own API credentials and region.

#### Installation

```bash
pip install 'carbonaware-ml[all]'         # includes scheduler + tensorboard extras
# or minimal
pip install carbonaware-ml

# zsh users: extras must be quoted
```

#### Configure environment

```bash
export CARBONAWARE_REGION="CA-ON"                 # your authorized zone (e.g., US-CAL-CISO, DE)
export ELECTRICITYMAPS_API_TOKEN="<your_token>"   # required for Electricity Maps
# Optional if your plan requires Basic Auth
export ELECTRICITYMAPS_EMAIL="you@example.com"

# Optional WattTime instead of Electricity Maps
# export WATTTIME_USERNAME="<user>"
# export WATTTIME_PASSWORD="<pass>"
```

#### Quickstart (Python)

```python
import os
from carbonaware_ml import CarbonAwareTrainer, providers

# model/optimizer/dataloader are your own objects
trainer = CarbonAwareTrainer(
    model=my_model,
    optimizer=my_optimizer,
    dataloader=my_dataloader,
    region=os.environ.get("CARBONAWARE_REGION"),
    carbon_provider=providers.ElectricityMapsProvider(),
)

# Start only when favorable
trainer.train_until_green(threshold=200, num_epochs=3)

# Or train now, pausing when conditions exceed thresholds
trainer.train(num_epochs=3, threshold=200, check_interval_s=300)
```

Providers:
- Electricity Maps (real-time/forecast carbon intensity)
  - Env: `ELECTRICITYMAPS_API_TOKEN` (required), `ELECTRICITYMAPS_EMAIL` (optional for Basic Auth)
- WattTime (alternative intensity source via `WATTTIME_USERNAME`/`WATTTIME_PASSWORD`)

If no external provider is configured, the trainer defaults to an "always-allow" mode.

#### CLI

```bash
# Use env region or pass explicitly
carbonaware intensity --region "$CARBONAWARE_REGION"
carbonaware price --region "$CARBONAWARE_REGION"
```

#### TensorBoard (optional)

```python
trainer = CarbonAwareTrainer(..., tb_log_dir="runs/demo")
```

#### Scheduler (optional)

```python
from carbonaware_ml.scheduler import run_when_favorable
sched = run_when_favorable(trainer, num_epochs=1, threshold=150, price_threshold_cents=12.0, check_interval_s=300)
```

#### Author

- Tom Almog (https://github.com/tomalmog)

#### License

MIT

