A strict, source-transparent solar/UV forecast and calibration stack.
Live forecast · Getting started · Scores · Safety model · Contributing
SunStack estimates spectrally weighted delayed-pigmentation exposure from forecast atmospheric conditions, reports independent erythemal exposure, and separately evaluates outdoor usability. Strict mode fails loudly on missing/unverifiable inputs and labels its degraded Tier-C broadband backend explicitly; no gate-passing Tier-B emulator is wired yet. It fetches live Open-Meteo forecasts, full ensemble data, native HRRR sub-hourly radiation, CAMS air-quality data, direct Copernicus CAMS spectral/ozone forecasts, NASA POWER historical UVA/UVB, archived Open-Meteo forecasts, and previous runs for lead-time skill calibration.
| Contract | Value |
|---|---|
| Schema / temporal support | sunstack-output-v5 · interval-contract-v1 |
| Exposure endpoint / action spectrum | delayed-pigmentation-v2 · parrish-fda-3630-v1 |
| Spectral backend | Tier-C tierC-broadband-proxy-v2 in production (no gate-passing tierB-libradtran-emulator-v1 wired; strict publishes Tier-C labeled; tier A/B claims fail loudly) |
| Surface / fusion / confidence / ranking | uv-surface-v1 · calibrated-uvi-fusion-v2 · best-match-headline-v1 (UVI headline is the best match; the fusion is published beside it) · heuristic-reliability-v1 (handwritten expected-error heuristic; not an empirically calibrated interval) · fixed-duration-dose-v2 |
flowchart LR
A[Open-Meteo live + ensembles] --> D[Fetch + validate]
B[Direct CAMS spectral/ozone] --> D
C[NASA POWER + archives + skill] --> E[Calibrate]
D --> F[Deterministic consensus]
E --> G[UVA/UVB estimators]
F --> G
G --> H[Absolute vs local scoring]
H --> I[30-min windows + blocks]
I --> J[Static site + calendar]
Git history is the audit trail: every scheduled run commits its export, so any published number traces back to the exact inputs that produced it. Strict mode refuses to publish rather than score blind.
Every hour and 30-minute period exposes the components separately:
| Score | What it means |
|---|---|
tan_score_absolute_0_100 |
Globally anchored delayed-pigmentation intensity: 100 * E_mel / fixed global reference. Not graded on a South Bend curve |
local_tan_score_0_100 |
Percentile versus historical daylight around this location and season (serving-domain reference) |
geometry_conditioned_transmission_percentile_0_100 |
Geometry-conditioned transmission percentile (conditional comparison, not causal isolation; legacy alias atmospheric_quality_percentile_0_100) |
strong_sun_probability_0_100 |
Probability of useful sun (ensemble/DNI/GHI/cloud); product quantity, not confidence |
outdoor_feasibility_0_100 |
Practical outdoor usability only (with outdoor_feasibility_complete + missing-field reasons) |
overall_tan_opportunity_0_100 |
LEGACY composite (deprecated product heuristic); ranking uses fixed-duration delayed-pigmentation dose |
Doses are reported separately from intensity (never ranked as intensity):
| Dose | What it means |
|---|---|
tan_dose_*_j_m2 |
Model-defined melanogenic-effective cumulative exposure (NOT a standardized unit) |
sed_* |
Independent erythemal channel; never increases TanScore or Opportunity |
uva_dose_* / uvb_dose_* |
Diagnostic physical broadband doses, not biological endpoints |
The unblocked composite is a weighted geometric mean — 70% Absolute, 15% Local, 5% Atmosphere, 10% Confidence — capped at Absolute+20, so local rarity can never turn weak physical UV into a fake elite score. Then it is multiplied by outdoor feasibility. It remains for migration only; the primary ranking is maximum expected 30-minute delayed-pigmentation dose (fixed-duration-dose-v2), with strongest vs best-usable variants.
Absolute 44
Local 97
Atmosphere 94
Confidence 91
Overall ~60 before weather usability
That reads as excellent for South Bend but only moderate on an absolute terrestrial scale — both true at once.
Outdoor usability is deliberately separate from melanogenesis physics.
Default hard blocks (Overall = 0, Absolute untouched): active rain/drizzle/showers, active snow, thunderstorm, temperature < 50°F (configurable) or >= 110°F. Soft penalties: 50–68°F cold comfort, 100–110°F heat, precipitation probability, high wind, hot + humid.
A uv_input_disagree flag fires when broadband and UV inputs describe different skies (per-variable model stitching on convective days); it halves confidence and prints a visible note rather than hiding the disagreement. Thresholds in .env.example / environment variables.
Dashboard and CLI accept optional Fitzpatrick I–VI (uv run sunstack run --skin-type 2, or the UI selector). It is qualitative personal-response/risk context only — it never multiplies environmental TanScore, because measured MED/MMD overlaps substantially within Fitzpatrick groups.
For a measured or defensibly estimated personal MMD in melanogenic-effective J/m², uv run sunstack run --personal-mmd 12000 --personal-mmd-basis SUNSTACK_EFFECTIVE_DOSE_MEASURED adds personal_mmd_fraction (TanDose ÷ personal MMD) with its provenance label — still without touching environmental physics. The dashboard and CLI accept surface and skin-plane controls; /api/data, /api/refresh, and /api/calendar.ics accept surface, surface_extent, skin_tilt_deg, and skin_azimuth_deg (422 for a value outside the declared domain). CLI equivalents are --surface, --surface-extent, --skin-tilt-deg, and --skin-azimuth-deg. The shared calendar and persisted runs remain exposure_basis=environmental_horizontal; skin-plane fields are context.
- Python
3.13 - uv
- Git
git clone https://github.com/carterlasalle/openmeteo-sunstack-tanscore.git
cd openmeteo-sunstack-tanscore
uv syncCreate a free Copernicus Atmosphere Data Store account, accept the CAMS dataset terms, and configure standard cdsapi credentials (~/.cdsapirc). Then verify everything (--probe makes real live Open-Meteo requests):
uv run sunstack doctor --probeuv run sunstack setupFetches NASA POWER UVA/UVB (2001+), Open-Meteo historical forecasts, previous runs, CAMS EAC4; trains UVA/UVB estimators; builds the local reference distribution and model/lead-time skill; then makes a fresh live run. Strict is the default: a missing critical source exits non-zero instead of inventing values. Troubleshooting only: uv run sunstack run --allow-degraded.
uv run sunstack ui # dashboard at http://127.0.0.1:8765
uv run sunstack run # terminal run (live cache bypassed by default)src/sunstack/
cli.py run / setup / bootstrap / doctor / ui / export
fetch.py live Open-Meteo fan-out (deterministic, ensemble, HRRR-15min, air quality)
history.py NASA POWER, archives, previous runs, CAMS EAC4 + direct CAMS forecast
normalize.py per-source normalization
derive.py consensus, ensemble probabilities, solar diagnostics
tanscore.py UVA/UVB estimators, action-spectrum absolute scoring, UVI fusion
photobiology.py E_mel / TanDose / SED core, spectra validation, strict gates
spectral.py skin-plane spectral layer, tiers A-D, Tier-C broadband mapping
doses.py trapezoidal TanDose/SED/UVA/UVB integration with gap flags
tan_response.py future delayed-pigmentation response interface (not shipped)
opportunity.py 30-min forecast, outdoor feasibility, daily summaries, Fitzpatrick context
validation.py strict gates (sources, CAMS fields, photobiology, score ranges)
output.py static-site + calendar export
ui.py dashboard, data + refresh + calendar APIs
calibrate.py training + serving-domain local reference + skill
data/
latest/ current snapshot (summary, raw manifests, tables)
runs/ every run, timestamped
calibration/ models, reference distribution, skill
research/action_spectra/ versioned action spectra + provenance metadata
docs/ published static site (each run republishes)
SunStack intentionally makes silent degradation inconvenient:
- Every normal
runbypasses the live HTTP cache — forecasts represent real requests, not stale reads. (--cached-liveonly when deliberate.) - Strict mode validates Best Match, HRRR 15-min, air quality, minimum deterministic/ensemble counts, calibration artifacts, direct CAMS fields, and score ranges. Any critical failure exits 1 with the exact failure plus the path to
data/logs/sunstack.log. - Historical data is cached (immutable decades shouldn't be redownloaded);
--forcerefetches deliberately. uv run sunstack debugprints the latest run summary and raw source manifest.
Live (uncached by default): Best Match, HRRR, NBM, NAM, GFS/AI-GFS, ECMWF IFS/AIFS, ICON, GEM + HRDPS, UKMO, ACCESS, CMA GRAPES, full-member GEFS/AIGEFS/ECMWF ensembles, ensemble means, native HRRR 15-minute, CAMS air quality/AOD550, deep pressure profiles.
Direct CAMS/ADS (strict-required): AOD and absorption AOD at 340/355/380/400 nm, single-scattering albedo, asymmetry factor, total-column ozone and water vapour, cloud liquid/ice columns, forecast albedo, CAMS UV diagnostics. Group requests first, per-variable retry on rejection, exact failures in raw/cams_forecast/manifest.json.
Near-term periods use native HRRR radiation/weather at true sub-hourly timestamps; hourly UV is interpolated with a bounded HRRR broadband correction. Farther out, rows are labeled interpolated_hourly — calendar/UI usability, not fake independent forecasts.
TanScore is an environmental/pigmentation-potential model, not a safe exposure-time recommendation. Tanning and erythema are both consequences of UV exposure; no skin type makes a UV dose harmless. The UI keeps radiation intensity, local context, weather feasibility, and personal skin-response context separate rather than synthesizing exposure-time advice.
| Document | Purpose |
|---|---|
| CONTRIBUTING.md | Development workflow and pull-request standards |
| SECURITY.md | Supported versions and vulnerability reporting |
| AGENTS.md | Repository-specific instructions for coding agents |
| RESEARCH_NOTES.md | Dated calibration and incident evidence log |
| PHOTOBIOLOGY_MODEL.md | v5 delayed-pigmentation model, equations, interaction-term evidence |
| TANDOSE.md | TanDose definition (model-defined, not standardized) |
| ACTION_SPECTRA.md | Spectrum provenance, tiers, interpolation rules |
| SPECTRAL_MODEL.md | Spectral layer, tiers A-D, skin-plane physics |
| .env.example | Every tunable threshold |
Solo-owner mode with required checks; read CONTRIBUTING.md before making changes. Run uv run pytest tests/ -q and uv run ruff check src tests before opening a pull request.