Appendix F: Site Weather Data
This appendix describes how R-THYM obtains climate data for the coordinates set in Data → Site Location.... It is for readers who want the sources, horizons, and fallbacks. Later sections of this appendix may cover related site services (regional costs, currency, and energy-rate defaults).
R-THYM does not run its own weather model. It requests public forecast and archive products, stores the result on the project, and interpolates those series onto the simulation clock.
1. What a fetch does
Fetch Site Data runs three requests in parallel:
- Climate (this appendix) — hourly forecast plus optional seasonal normals.
- Site region — reverse-geocoded country/state used for cost and currency defaults.
- Regional defaults — optional energy-rate, currency, and CapEx seeds for the Cost Estimator.
Only the climate payload is required for solar, wind, tank evaporation, and the weather HUD. Region and cost defaults can fail independently; climate can still succeed.
Nothing is written to the project until you click Save Changes.
2. Climate source (Open-Meteo)
R-THYM’s energy-site weather profile always uses Open-Meteo. The shared weather service can register other drivers; a California CIMIS driver exists in the codebase but is not implemented and is not used by R-THYM.
| Request | Endpoint | Purpose |
|---|---|---|
| Hourly + daily forecast | https://api.open-meteo.com/v1/forecast |
Operating climate for the next 14 days |
| Seasonal archive | https://archive-api.open-meteo.com/v1/archive |
Monthly solar and wind normals from the prior year |
Forecast parameters: timezone=auto, forecast_days=14, wind speed in m/s.
Hourly series stored on the project
- Air temperature at 2 m
- Precipitation
- Wind speed at 10 m
- Shortwave (global) radiation
- Cloud cover
- FAO-56 reference evapotranspiration (ET₀)
Daily series stored on the project
- Sunrise and sunset timestamps
- Daily ET₀ (fetched; hourly ET₀ is what the hydraulic run uses)
Open-Meteo’s own documentation describes the underlying NWP blends. R-THYM does not re-analyze or bias-correct those fields.
3. Seasonal normals (fallback after the forecast window)
The archive request covers roughly the previous year, ending seven days before today so incomplete recent days are skipped. Daily solar energy (shortwave_radiation_sum, MJ/m²/day) and mean 10 m wind speed are bucketed by calendar month, then converted to:
- monthly means
- a days-weighted annual mean
- monthly multipliers (month mean / annual mean)
Fallbacks
- If the archive request fails, the 14-day forecast is still stored. Seasonal climate is omitted (
null). - If every monthly bucket is empty or zero, seasonal climate is omitted.
- Inside the hourly forecast window, solar and wind use the forecast as-is.
- After the last forecast hour, solar and wind are scaled by that month’s archive multiplier so longer EPS runs do not stay stuck on the last forecast day.
4. How the simulation clock is mapped onto the forecast
Open-Meteo hourly arrays start at fetch time, not midnight. R-THYM maps simulation time of day onto those timestamps, then linearly interpolates between adjacent hours.
If timestamps are missing or unparseable, it falls back to wrapping the series by hour-of-day (hour mod series length). Missing arrays read as 0 (no solar, no wind, no ET₀, and so on).
Sunrise and sunset prefer Open-Meteo’s daily timestamps for the simulated day. If those strings are missing, R-THYM uses a closed-form solar geometry estimate from latitude, longitude, and day of year. If no forecast dates exist, day of year defaults to 172 (northern-hemisphere summer). If no site is set, coordinates default to 40.7608, −111.8910 (Salt Lake City).
5. Place lookup and reverse geocoding
These are not climate products, but they are how Site Location decides where to fetch.
| Step | Source | Fallback |
|---|---|---|
| City Lookup | Open-Meteo Geocoding API | Error: enter latitude and longitude yourself |
Long pasted labels (City, Region, Country) |
Reduced to City, Country before search |
— |
| Reverse geocode (country / state for costs) | OpenStreetMap Nominatim | Nearest CONUS NREL-region centroid; outside that box, US national average. The client repeats the same coordinate fallback if the server call fails. |
A failed reverse geocode does not block climate. You can still fetch Open-Meteo data for the typed coordinates.
6. Stale data and project files
If a saved project’s hourly series starts on a calendar day other than today (local), R-THYM refreshes climate in the background when the editor loads (skipped on read-only public links). You can also refetch from the weather HUD after a site is saved.
Standalone JSON downloads omit the bulky hourly/daily climate arrays on purpose. Latitude and longitude remain, so Fetch Site Data can rebuild climate.
[!NOTE] Weather products are provided by Open-Meteo. Place names for reverse geocoding use OpenStreetMap Nominatim. Re-fetch before a study if you need the latest forecast; R-THYM does not continuously stream weather during a run.