Metadata-Version: 2.4
Name: crusoe-estimator
Version: 0.1.2
Summary: PyTorch Training Cost & Carbon Estimator for Crusoe Cloud
Author: HackEurope Team
License: MIT
Project-URL: Homepage, https://github.com/hackeurope/crusoe-estimator
Project-URL: Repository, https://github.com/hackeurope/crusoe-estimator
Keywords: pytorch,gpu,training,estimator,carbon,co2,crusoe,cloud
Classifier: Development Status :: 3 - 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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: full
Requires-Dist: torch>=2.0; extra == "full"
Requires-Dist: pynvml>=11.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: torch>=2.0; extra == "dev"

# ⚡ crusoe-estimator

**PyTorch Training Cost & Carbon Estimator for Crusoe Cloud**

Benchmark your PyTorch training loop locally on a small sample, then get instant estimates for:
- ⏱️ **Training time** on every Crusoe Cloud GPU (A100, H100, H200, MI300X)
- 💰 **Cost** on Crusoe Cloud
- 🌍 **CO₂ savings** — your local emissions vs Crusoe's near-zero carbon footprint

## Installation

```bash
pip install crusoe-estimator
```

Or with PyTorch (if not already installed):
```bash
pip install "crusoe-estimator[torch]"
```

## Quick Start

### Pattern 1: Training Loop Wrapper (Recommended)
```python
from crusoe_estimator import CrusoeEstimator

estimator = CrusoeEstimator(total_epochs=100, location="HR")

for epoch in estimator.epochs(sample=3):
    # Your normal training code — runs only 3 epochs
    for batch_x, batch_y in train_loader:
        optimizer.zero_grad()
        output = model(batch_x)
        loss = criterion(output, batch_y)
        loss.backward()
        optimizer.step()

# Generate a beautiful HTML report
estimator.generate_report("training_report.html")

# Or print a text summary
print(estimator.summary())
```

### Pattern 2: Decorator
```python
estimator = CrusoeEstimator(total_epochs=100, location="DE")

@estimator.watch(sample_epochs=3)
def train_epoch(model, dataloader, optimizer, criterion):
    for x, y in dataloader:
        optimizer.zero_grad()
        loss = criterion(model(x), y)
        loss.backward()
        optimizer.step()

# Calling the decorated function runs 3 epochs and benchmarks
train_epoch(model, train_loader, optimizer, criterion)
estimator.generate_report("report.html")
```

### Pattern 3: Context Manager
```python
estimator = CrusoeEstimator(total_epochs=100, sample_epochs=5, location="US")

with estimator.track():
    for epoch in range(5):
        train_one_epoch(model, train_loader, optimizer, criterion)

estimator.generate_report("report.html")
```

### Pattern 4: Function Wrapper
```python
estimator = CrusoeEstimator(total_epochs=100, location="HR")

result = estimator.estimate(
    train_fn=lambda: train_one_epoch(model, loader, optimizer, criterion),
    sample_epochs=3,
)

estimator.generate_report("report.html")
```

## Dataset Scaling

If you benchmark with a smaller dataset:
```python
estimator = CrusoeEstimator(
    total_epochs=100,
    total_dataset_size=50000,
    sample_dataset_size=5000,  # Using 10% of data
    location="HR",
)
```

## Supported GPUs

### Crusoe Cloud
| GPU | FP16 TFLOPS | Memory | Price/hr |
|-----|-------------|--------|----------|
| A100 80GB | 312 | 80 GB | $1.47 |
| H100 SXM | 989 | 80 GB | $2.25 |
| H200 SXM | 989 | 141 GB | $3.25 |
| MI300X | 1307 | 192 GB | $2.49 |

### Local GPU Detection
Automatically detects 50+ GPUs:
- NVIDIA: RTX 20/30/40 series, A100, H100, V100, T4
- AMD: MI300X, MI250X
- Apple Silicon: M1–M4 (all variants)

## How It Works

1. **Detect** local GPU and its specifications (FLOPS, memory, TDP)
2. **Benchmark** your training loop for N sample epochs
3. **Extrapolate** total training time using average epoch time
4. **Scale** to Crusoe GPUs using FLOPS ratio (70% compute + 30% memory bandwidth weighting)
5. **Calculate** cost based on Crusoe pricing
6. **Estimate** CO₂ using regional carbon intensity (local) vs near-zero (Crusoe)
7. **Generate** an HTML report with tables, charts, and recommendations

## Carbon Intensity

Uses real-world carbon intensity data (kg CO₂/kWh):
- 🇭🇷 Croatia: 0.170
- 🇩🇪 Germany: 0.340
- 🇫🇷 France: 0.056
- 🇺🇸 USA: 0.390
- 🇨🇳 China: 0.560
- ☁️ **Crusoe: ≈ 0.000** (renewable energy)

## API Reference

### `CrusoeEstimator`
Main class. Constructor parameters:
- `total_epochs` — how many epochs the full training would run
- `sample_epochs` — how many epochs to actually benchmark (default: 3)
- `total_dataset_size` — full dataset size (optional, for scaling)
- `sample_dataset_size` — dataset size used in sample (optional)
- `location` — country code for CO₂ calculation (e.g., "HR", "US", "DE")
- `power_watts_override` — override auto-detected GPU power draw

### Reports
- `estimator.generate_report("report.html")` — HTML report
- `estimator.summary()` — text summary

---

Built with 💚 at HackEurope 2026 • Powered by [Crusoe Cloud](https://crusoe.ai)
