<!--
HF-spec model card (https://huggingface.co/docs/hub/model-cards).
Populated by /write-modelcard from PROJECT_STATE.md + W&B run + eval results.
The YAML block at the top is what HF Spaces / Hub renders as searchable
metadata. Keep it accurate.
-->

---
language: [en]
license: mit
library_name: pytorch
tags:
  - diffusion
  - scenario-generation
  - power-systems
  - renewable-energy
  - physics-constrained
datasets:
  - aeso-2016-2025
  - era5-alberta
metrics:
  - scenario-feasibility
  - wasserstein-1
model-index:
  - name: pc-ddpm-alberta
    results:
      - task:
          type: scenario-generation
          name: 24-hour wind/solar/load joint scenario generation
        dataset:
          name: AESO + ERA5 Alberta
          type: tabular-time-series
        metrics:
          - type: scenario-feasibility-operational
            value: TBD (filled by /write-modelcard)
          - type: scenario-feasibility-strict-ansi
            value: TBD
          - type: wasserstein-1-load
            value: TBD
---

# Model Card for pc-ddpm-alberta

PC-DDPM is a physics-constrained denoising diffusion probabilistic model that generates 24-hour joint scenarios of wind generation, solar generation, and load for the Alberta electricity grid. A frozen GraphSAGE surrogate provides differentiable AC power flow voltage gradients during training; a ReLU voltage-violation penalty on a three-phase λ_phys annealing schedule drives generated scenarios toward AC-feasible operating points. Trained on 9 years of real AESO observations and evaluated on the IEEE 118-bus proxy network scaled to Alberta loads.

## Model Details

- **Developed by**: jbobym (single-author portfolio project)
- **Model type**: Generative — diffusion (DDPM)
- **Architecture**: 1D temporal U-Net for noise prediction; frozen GraphSAGE AC power flow surrogate (3-layer mean aggregator) provides physics gradients during training only
- **Language(s)**: N/A (tabular time series)
- **License**: MIT (code); AESO Open Data + ERA5 CC-BY-4.0 (data)
- **Trained from**: scratch
- **W&B run backing this card**: TBD (filled by /write-modelcard)

## Uses

### Direct use

Operational planning for grid operators and system planners — reserve sizing, contingency analysis, and stress-testing the transmission network against renewable variability. Generates ensembles of plausible 24-hour wind/solar/load joint trajectories that respect AC power flow on the IEEE 118-bus proxy network scaled to Alberta loads.

### Downstream use

[If applicable: how this model could feed into a larger system or be
fine-tuned for related tasks.]

### Out-of-scope use

- **Do NOT use this for**: real-time control loops, dispatch decisions, or any sub-hourly intervals — the model generates hourly trajectories only.
- **Do NOT use this for**: balancing authorities outside Alberta without retraining — the model is conditioned on AESO-specific generation and load patterns.
- **Do NOT use this for**: production deployment on the actual AESO network — we evaluate on the IEEE 118-bus proxy because real AESO topology is non-public; results may not transfer.
- **Do NOT use this for**: thermal-feasibility claims — we evaluate voltage bounds only; line thermal limits are not exercised at Alberta loadings on this proxy network.

## Bias, Risks, and Limitations

[Two to four paragraphs of honest limitations. The kinds of failures
matter more than the rates. If your model underperforms on a specific
demographic, regime, or slice, name it.]

### Recommendations

[How a careful user should handle the limitations. Monitoring, fallback
strategies, retraining cadence.]

## How to Get Started

```python
from your_project.modeling.predict import load_model, predict
model = load_model()
y = predict(model, x)
```

Full reproducibility instructions: [README.md](README.md).

## Training Details

### Training Data

[What data, how much, splits, license, preprocessing. Cross-link to
`eda/data_profile.md` for the full schema and gotchas.]

### Training Procedure

- **Compute**: [HARDWARE]
- **Optimizer**: [OPTIMIZER + hyperparams]
- **Batch size**: [BS]
- **Epochs**: [N]
- **Wall time**: [TRAIN TIME]
- **Seed**: 42 (in `src/pc_ddpm_alberta/config.py`)

## Evaluation

### Testing Data, Factors & Metrics

[How was evaluation set selected? What slices were measured?]

### Results

[Headline metrics table — same as README's, but with full precision and
extra slices. Cross-link to `/eval-report` output if you have a deeper
analysis doc.]

| Metric | Value | 95% CI | Notes |
|---|---|---|---|
| [METRIC] | — | — | — |

### Per-slice performance

[Table of metrics by slice (season, user segment, etc.). The point
isn't averages — it's where the model behaves differently.]

## Environmental Impact

- **Hardware type**: [GPU MODEL]
- **Hours used**: [TRAIN HOURS]
- **Cloud provider** (if applicable): [PROVIDER]
- **Carbon emitted** (kgCO2eq): [ESTIMATE — use ml-co2-impact.com or similar]

## Technical Specifications

### Model architecture and objective

[More detail than the summary. Equations welcome here.]

### Compute Infrastructure

#### Hardware

[Hardware spec.]

#### Software

[Framework versions, CUDA version, any relevant libs.]

## Citation

```
[CITATION BLOCK — populated by /init-project]
```

## Model Card Authors

[YOUR NAME]

## Model Card Contact

[CONTACT — email, LinkedIn, or repo issues]