Metadata-Version: 2.4
Name: penumbra-toolkit
Version: 0.1.0
Summary: Probabilistic space-weather driver forecasting: F10.7 and Kp forecasts with walk-forward-calibrated uncertainty bands, plus orbital-drag translation — pure Python.
Author-email: Ashutosh <siddhashutosh@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/siddhashutosh/penumbra
Project-URL: Documentation, https://github.com/siddhashutosh/penumbra/tree/main/documents
Project-URL: Issues, https://github.com/siddhashutosh/penumbra/issues
Keywords: space-weather,forecasting,uncertainty-quantification,f10.7,solar-flux,kp-index,geomagnetic,calibration,orbital-drag,SSA
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: python-dateutil>=2.9

# penumbra-toolkit

Probabilistic space-weather driver forecasting for Python: forecast the F10.7 solar radio
flux and the Kp geomagnetic index with **calibrated uncertainty bands**, verify that
calibration with a leakage-free walk-forward backtest, and translate the uncertainty into
orbital-drag risk.

Extracted from [PENUMBRA](https://github.com/siddhashutosh/penumbra), where the same code powers
a live dashboard over the public NOAA feeds. The phase-2 companion to
[kessler-toolkit](https://pypi.org/project/kessler-toolkit/).

```bash
pip install penumbra-toolkit
```

## What's inside

| Module | Purpose |
|---|---|
| `series` | Parse NOAA F10.7 / Kp, aggregate Kp→daily Ap, align and gap-fill daily series |
| `f107_forecast` | Persistence + mean-reversion point forecast with empirical quantile bands |
| `kp_forecast` | Recency-weighted geomagnetic storm-category probabilities + Ap band |
| `calibration` | Leakage-free walk-forward backtest, coverage, pinball loss, skill, reliability |
| `drag` | F10.7 band → thermospheric density → in-track orbit-decay uncertainty |

## Quick start

```python
import numpy as np
from penumbra_toolkit import (
    DailySeries, walk_forward_errors, forecast, coverage, skill_vs_reference,
)

# a daily F10.7 history (dates + values)
history = DailySeries(dates, values)

# learn the out-of-sample error distribution, then forecast with calibrated bands
bt = walk_forward_errors(history, lead_days=45, min_train=400)
fc = forecast(history, 45, bt.error_quantiles)

print(fc.point[6], fc.bands[5][6], fc.bands[95][6])   # 7-day point + 90% band
print(coverage(bt)[0])                                # empirical vs target coverage
print(skill_vs_reference(bt)[0])                      # skill vs persistence baseline
```

Every uncertainty band is **learned from real out-of-sample forecast errors** — calibrated by
construction if the backtest is leakage-free, which is enforced by test. Drag translation is a
reduced, order-of-magnitude model (not a high-fidelity propagation).

Apache-2.0. Space-weather data used with PENUMBRA courtesy of NOAA SWPC and GFZ Potsdam.
