EPWForge Documentation

Tool surface

Four tools, consolidated from a former 10-tool surface in v0.2.0. Operations like batch generation, ensemble synthesis, and design-day generation are now parameters on the four core tools (e.g. ensemble=true, scenarios=[...], format="ddy") rather than separate tools.

find_station

Search the GuzzStations catalog (~17,000 weather stations worldwide). Returns matching stations with EPW URLs ready to pass to analyze_weather or chart_weather. No authentication required.

Parameters:

• query — case-insensitive partial city/state match (e.g. "Boston")
• lat, lon — when set, results sort by proximity
• country — ISO 3-letter code filter (e.g. "USA", "GBR")
• max_results — default 10, max 50
• include_amy_extremes — also return hottest/coldest/most-humid years on record (per ERA5). Adds a hosted-MCP round trip.
• include_climate_deltas — also return monthly CMIP6 delta-T for the picked SSP/year
• ssp, year, percentile — only used with include_climate_deltas
• compact — return only the single newest TMYx file per station (epw_url + ddy_url) plus identifiers. Use in chained agent workflows; 6–10× smaller responses.

find_station(query="Denver")
find_station(lat=40.7, lon=-74.0, max_results=5, compact=True)
find_station(country="JPN", query="Tokyo")
find_station(lat=40.7, lon=-74.0, include_amy_extremes=True)
find_station(lat=40.7, lon=-74.0, include_climate_deltas=True, ssp="ssp245", year=2050)

analyze_weather

Statistical summary of an EPW file or synthesized scenario. Three modes:

• URL mode — pass url= to analyze a single EPW (typically from find_station)
• Comparison mode — pass urls=[...] (2–10 EPWs) to get side-by-side cards
• Config mode — pass config={lat, lon, ssp, year, percentile, uhi, events, intensity, ...} to synthesize a morphed scenario at a custom lat/lon. No authentication needed; returns stats only (no EPW content).

Optional enrichments (config mode):

• include_full_ashrae — all percentile bins (0.4 / 1 / 2 cooling, 99.6 / 99 heating, plus WB / DP / Enth variants)
• include_improbability — stress-test score (1–10) with named factors so agents can flag genuinely extreme synthesized scenarios
• include_idf — ready-to-paste EnergyPlus SizingPeriod:DesignDay objects

analyze_weather(url="https://...USA_NY_New.York-JFK.AP.744860_TMYx.epw")
analyze_weather(urls=["https://...A.epw", "https://...B.epw"])
analyze_weather(config={
  "lat": 42.3, "lon": -71.1,
  "ssp": "ssp245", "year": 2050, "percentile": 75,
  "uhi": "urban",
  "events": "heatwave",
  "intensity": "heatwave:6",
  "event_duration": 14,
}, include_full_ashrae=True, include_improbability=True)

chart_weather

Returns an SVG chart for a single EPW or comparison of multiple EPWs. Pure inline SVG; no external image hosting. Single-site chart types:

• diurnal — 24-hour profile by season
• temp_carpet — hour-by-month heatmap of dry-bulb temperature
• wind_rose — wind speed + direction radial
• monthly_boxplot — monthly distribution of dry-bulb
• utci_carpet — Universal Thermal Climate Index hour-by-month
• economizer_carpet — hours when ambient air can offset cooling load
• pv_tilt_azimuth — optimal PV orientation heatmap by location
• solar_under_events — solar shortfall during smoke / cloud events

Multi-site chart type:

• comparison — design-condition bars across 2–10 EPWs

chart_weather(url="https://...A.epw", chart_type="temp_carpet")
chart_weather(url="https://...A.epw", chart_type="diurnal", units="imperial")
chart_weather(urls=["https://...A.epw", "https://...B.epw"], chart_type="comparison")

generate_weather_file

Generates and returns a downloadable weather file with the full morph stack applied. Requires a bearer token from your account page and consumes credits. Tool charges 1 credit per single-file output, 2 credits per 4-file bundle (AMY, All-SSP), 10 credits per CMIP6 ensemble.

Parameters:

• lat, lon — required
• format — "epw", "ddy", "csv", "zip" (bundle), "pvsyst"
• ssp, year, percentile — CMIP6 morph
• uhi — Stewart & Oke 2012 LCZ preset
• events, intensity, event_duration — extreme-event injection
• smoke_enabled, smoke_intensity — wildfire smoke overlay
• amy_year — actual meteorological year mode
• tmy_period — TMYx vintage (2011-2025, 2009-2023, etc.)
• ensemble — return all SSPs at once

Authentication

Three of the four tools (find_station, analyze_weather, chart_weather) work without authentication. Only generate_weather_file requires a bearer token. Free tier gets 5 lifetime credits; paid plans add monthly credits. Out-of-credits returns HTTP 402 with hints pointing at top-up packs and subscription upgrades.

Methodology references

• Belcher 2005 — TMY morphing mean-shift methodology
• UKCP18 / NOAA Atlas 14 — diurnal anomaly templates (Item 2 of morphing-v2)
• CMIP6 SSP scenarios — SSP1-2.6, SSP2-4.5, SSP3-7.0, plus SSP5-8.5 as an opt-in extreme stress test
• IPCC AR6 — extreme-event scaling for heatwave / coldsnap / hothumid / coldwindy / wildfire smoke
• ISO 15927-4 — Finkelstein-Schafer for TMYx synthesis
• ASHRAE Fundamentals 2025 Ch. 14 — Climatic Design Information
• ERA5 reanalysis (Copernicus) and ERA5-Land — historical + AMY source
• Stewart & Oke 2012 — Local Climate Zone framework for Urban Heat Island presets
• Stull 2011 — wet-bulb approximation (used in IDF DesignDay output)
• Coen 2026 — published return-period changes embedding both thermodynamic (S) and synoptic (W) effects

Validation

Per-station bias correction validated against 16,906 OneBuilding ASHRAE Handbook reference stations:

• Cooling 0.4% dry-bulb median bias reduced ~50% (from −0.80 °C to −0.34 °C)
• Heating 99.6% dry-bulb mean bias reduced ~45% (from +0.47 °C to +0.20 °C)
• Residual standard deviation reduced 6–11% across heating and cooling DC values
• 60–68% of stations show improvement; 31–37% small degradation; 2–3% unchanged

Generated EPW and DDY files runtime-tested in EnergyPlus 25.2. See /transparency for full details.

Errors

• 402 — insufficient credits. Hint includes top-up + upgrade links.
• 403 — invalid API key, or URL points at a private/local address (SSRF guard).
• 429 — rate limited. Retry-After header present.
• 4xx — invalid parameters; error message includes the specific failed field.