🦋 ButterflAI

Synthetic Solar Cycle Generation via Score-Based Diffusion Models
COFFIES Science Center · 11-Week Student Research Program

---

Overview

ButterflAI is an 11-week undergraduate research program (~40 students) building a synthetic solar cycle generator from the ground up. Starting from classical statistical descriptions of the solar butterfly diagram (sunspot latitude-time emergence patterns), students progressively develop reverse diffusion / score-based generative models capable of producing physically plausible synthetic solar cycles.

Primary environment: Google Colab Pro
Stack: Python · NumPy · Pandas · Matplotlib · SciPy · PyTorch · PyTorch Lightning

Dependency source: Colab notebooks install dependencies via requirements.txt (pip). environment.yml is provided for local conda setups but is not used by Colab.

---

Repository Structure

butterflai/
├── infrastructure/         # Shared, reusable code provided to students
│   ├── data/               # Data loading, preprocessing, solar cycle utilities
│   ├── models/             # Base classes and reusable model components
│   ├── utils.py              # Training helpers, metrics, Colab setup utilities
│
├── weeks/                  # Weekly Jupyter notebooks (released gradually)
│   ├── week_01/            # Orientation + Solar Data Exploration
│   ├── week_02/            # Statistical Descriptions of the Butterfly Diagram
│   ├── week_03/            # ...
│   └── ...
│
├── .github/
│   └── workflows/          # CI: notebook smoke tests, import checks
│
├── CLAUDE.md               # Context file for Claude Code (AI assistant)
├── pyproject.toml          # Project metadata and dependencies
├── requirements.txt        # Colab-compatible pinned dependencies
└── README.md               # This file