Metadata-Version: 2.5
Name: solar-flare-utac
Version: 1.0.1
Summary: Solar flare magnetic avalanche threshold — GenesisAeon Package 21
Project-URL: Homepage, https://github.com/genesisaeon/solar-flare-utac
Project-URL: Repository, https://github.com/genesisaeon/solar-flare-utac
Project-URL: Zenodo, https://doi.org/10.5281/zenodo.20843133
Author: Johann Römer / MOR Research Collective
License: GPL-3.0-or-later AND CC-BY-4.0
License-File: LICENSE
License-File: LICENSE-CODE
License-File: LICENSE-DOCS
Keywords: crep,magnetic-reconnection,phase-transition,self-organized-criticality,solar-flare,space-weather,utac
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.9
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: scipy>=1.13
Requires-Dist: typer>=0.12.0
Provides-Extra: astropy
Requires-Dist: astropy>=6.0; extra == 'astropy'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Description-Content-Type: text/markdown

# solar-flare-utac

> GenesisAeon Package 22 — Solar Flare Magnetic Avalanches as UTAC System

<p align="center">
  <a href="https://doi.org/10.5281/zenodo.19645351"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19645351.svg" alt="DOI (GenesisAeon Whitepaper)"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="GPLv3 License"/></a>
  <a href="https://creativecommons.org/licenses/by/4.0/"><img src="https://img.shields.io/badge/docs-CC%20BY%204.0-lightblue.svg" alt="CC BY 4.0"/></a>
  <a href="https://github.com/GenesisAeon/genesis-os"><img src="https://img.shields.io/badge/part%20of-genesis--os-blueviolet" alt="Part of genesis-os"/></a>
  <img src="https://img.shields.io/badge/UTAC-package%2022-orange" alt="Package 22"/>
</p>
[![CI](https://github.com/genesisaeon/solar-flare-utac/actions/workflows/ci.yml/badge.svg)](https://github.com/genesisaeon/solar-flare-utac/actions/workflows/ci.yml)
[![Reference](https://img.shields.io/badge/Ref-A%26A%202026-red)](https://doi.org/10.1051/0004-6361/202449012)

**Solar flares modelled as magnetic UTAC avalanches** — calibrated against Solar Orbiter (2026), GOES X-ray data (1975–2026), and Velasco Herrera et al. (2026, JGR Space Physics).

**Key result**: Γ_solar ≈ 0.014 (ultra-low CREP) → most hair-trigger system in the atlas.

---

## Central Result

> **Γ_solar = arctanh(0.03) / 2.2 ≈ 0.014**

Solar active regions occupy the **ultra-sensitive** (ultra-low CREP) end of the
GenesisAeon cross-domain criticality spectrum — the lowest Γ of any system in the
atlas.  Tiny CREP fluctuations produce giant energy releases, explaining why
deterministic solar flare prediction is so notoriously difficult.

### CREP Criticality Spectrum

| Domain | Package | Γ | η | Character |
|---|---|---|---|---|
| **Solar Flare** | **P21** | **0.014** | **1%** | **Ultra-sensitive** |
| Cygnus X-1 Jet | P17 | 0.046 | 5% | Hair-trigger |
| Amazon Rainforest | P19 | 0.116 | 12% | Fragile |
| AMOC Ocean | P18 | 0.251 | 50% | Homeostatic |
| Neural Criticality | P20 | 0.251 | 50% | Homeostatic (!) |
| BTW Sandpile | P22 | 0.296 | 58% | Robust SOC |
| Manna Sandpile | P22 | 0.376 | 72% | Dense SOC |
| ERA5 Arctic | P01 | 0.920 | 99% | Near-saturated |

---

## Physical Mapping to UTAC

| UTAC symbol | Solar quantity |
|---|---|
| H(t) | Normalised magnetic free energy ∈ [0, 1] |
| K | E_max ≈ 10³² J (active region energy ceiling) |
| H* | Quiescent fixed point ≈ 0.10 K |
| r | Flux-emergence buildup rate ≈ 0.06 hr⁻¹ |
| σ | CREP coupling = 2.2 |
| Γ(t) | CREP tensor (C, R, E, P) → Γ_solar ≈ 0.014 |

**Flare trigger:** when H > H_threshold = 0.60 AND Γ > θ_PT ≈ 0.014, the
magnetic current sheet becomes unstable → reconnection cascade → "magnetic
avalanche" (Solar Orbiter A&A 2026).

---

## Installation

```bash
pip install solar-flare-utac
# or
uv add solar-flare-utac
# development
pip install -e ".[dev]"
```

## Quickstart

```python
from solar_flare_utac import SolarFlareUTAC

model = SolarFlareUTAC(seed=42)
state  = model.run_cycle(duration_hours=72)

print(state['crep_state'])    # {C, R, E, P, Gamma}
print(state['utac_state'])    # {H, dH_dt, H_star, K_eff}
print(state['flare_count'])   # flares in this cycle

window = model.predict_flare_window(horizon_days=3)
record = model.to_zenodo_record()
```

## CLI

```bash
# Run a 72-hour simulation cycle
solar-utac run --duration 72 --active-region AR3000

# Flare probability window forecast
solar-utac flare-window --horizon 7

# Print the full CREP Criticality Spectrum
solar-utac gamma-crep-spectrum

# Validate against benchmark targets
solar-utac benchmark

# Export Zenodo metadata record
solar-utac zenodo-export
```

## Integration in genesis-os

```python
from genesis_os import GenesisOS
os = GenesisOS()
solar = os.load_package(21)
results = solar.run_cycle(duration_hours=72)
print(f"Γ_solar = {results['crep_state']['Gamma']:.4f}")
```

## Diamond-Template Contract

All GenesisAeon packages implement the same five-method interface:

```python
model.run_cycle(duration_hours=72)  → dict
model.get_crep_state()              → {C, R, E, P, Gamma}
model.get_utac_state()              → {H, dH_dt, H_star, K_eff}
model.get_phase_events()            → list[dict]   # each flare = one event
model.to_zenodo_record()            → dict
```

## Repository Structure

```
solar-flare-utac/
├── src/solar_flare_utac/
│   ├── system.py          # SolarFlareUTAC — Diamond interface + Ethics Gate
│   ├── active_region.py   # Magnetic free energy ODE (UTAC)
│   ├── reconnection.py    # Reconnection instability threshold (Syrovatsky)
│   ├── crep_solar.py      # Solar CREP tensor (C, R, E, P → Γ)
│   ├── goes_loader.py     # GOES X-ray flux loader + synthetic generator
│   ├── superflare.py      # Power-law flare statistics (SOC)
│   ├── geomagnetic.py     # Dst storm impact model
│   ├── benchmark.py       # Validation vs. GOES catalog + Orbiter
│   ├── cli.py             # Typer CLI
│   └── constants.py       # All physical and model constants
├── data/
│   ├── goes_xray_annual_stats.yaml
│   └── flare_catalog_summary.yaml
├── notebooks/
│   ├── 01_solar_utac_overview.ipynb
│   ├── 02_goes_crep_analysis.ipynb
│   ├── 03_flare_cascade.ipynb
│   └── 04_gamma_solar_calibration.ipynb
└── tests/
    ├── test_diamond_interface.py
    ├── test_active_region.py
    ├── test_reconnection.py
    └── test_superflare.py
```

## Benchmark

Target values below are informed by the cited literature, but most
checks compare the model against itself rather than independent data at
runtime -- see `benchmark.py`'s module docstring for the honest
breakdown of which checks are self-consistency tests. The reconnection
timescale check currently fails by ~20x at its test point; this is a
known, unresolved calibration gap (see `FOLLOWUP_TICKETS.md`), not
silently hidden.

| Target | Value | Tolerance |
|---|---|---|
| Γ_solar | 0.014 | ±0.005 |
| X-class energy [J] | 10³² | log ±0.5 |
| Power-law index α | 1.8 | ±0.1 |
| Reconnection timescale | 10 min | ±30% |
| X-class flares/cycle | 150 | ±20% |

## Falsifiable Prediction

Next X5+ flare window in **2026 Q3** (southern hemisphere active region peak, per
Velasco Herrera 2026). Γ_solar will exceed θ_PT during this period. Testable
against GOES real-time monitoring at [SWPC](https://swpc.noaa.gov).

## References

- Solar Orbiter / A&A 2026 — magnetic avalanche mechanism
- Velasco Herrera et al. 2026, JGR Space Physics — 47-year superflare dataset
- Thoen Faber et al. 2025 — SST/CHROMIS high-resolution flare ribbons (140–200 km)
- ESA CryoSat + Swarm 2026 — X-class geomagnetic storm measurements

## Citation

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20843133.svg)](https://doi.org/10.5281/zenodo.20843133)

---

Part of the **GenesisAeon** cross-domain CREP criticality atlas.
Code: GPLv3-or-later · Docs & Data: CC BY 4.0 · seed=42 · numpy/scipy/matplotlib
