Skip to content

SUEWS v2026.6.5: YAML configuration schema 2026.5 and SUEWS Agent

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Jun 10:07
· 19 commits to master since this release
2026.6.5
f39fccb

Installation

pip install --upgrade supy

What's New

Version 2026.6.5 (released on 5 June 2026)

This release finalises the YAML configuration schema to 2026.5, collapsing the entire 2026.5.dev1..2026.5.dev14 development cycle into a single released label. The headline change is a comprehensive naming overhaul of the YAML surface: de-fused snake_case field names, readable physics selectors, a fully snake_case STEBBS surface, and a restructured model.control. Existing configurations upgrade automatically in one step. The release also takes the first steps towards driving SUEWS from AI coding agents. There is no change to model output: the schema changes are confined to the YAML surface and the Python data model.

SUEWS Agent (experimental)

The new SUEWS agent plugin bundles the SUEWS MCP server so an AI coding agent (for example Claude) can scaffold, inspect, validate, and run configurations through structured tools, with a self-bootstrapping uvx install so the plugin is the only onboarding step (#1496, #1384). suews inspect --format json exposes a structured physics block, and the sample configuration uses readable, nested physics groupings (with legacy flat input still accepted) so both agents and users see semantic axes rather than opaque method codes (#1484, #1483). This capability is deliberately experimental and under active development -- interfaces will change and it is not yet production-ready -- but we are excited about this direction.

Bug Fixes

  • Legacy table-to-YAML conversion no longer aborts on a missing stebbsmethod df_state column (defaults to 0, STEBBS disabled) (#1500)
  • Hardened legacy STEBBS df_state defaults so older state DataFrames load without the newer nested STEBBS columns (#1510)
  • Folded legacy flat STEBBS physics switches into the nested model.physics.stebbs object during validation (#1499)
  • Validator report no longer collapses to a lone schema_version line when that field is absent (#1466, #1458)
  • Made standalone Phase B/C validation rename-aware so legacy field spellings are normalised before rule checks (#1457)
  • SUEWSOutput.save() follows the configured output format instead of always forcing parquet (#1451)

Build System and CI

  • Narrowed the PyPI publish tag trigger to CalVer-only, so non-supy tags do not build a SuPy wheel (#1384)
  • Resolved the Python interpreter in the validate-tutorial hook (#1503)
  • Pinned the agent push-token checkout to silence the zizmor artipacked finding (#1504)

Maintenance

  • Removed leftover derived-type (dts) field-name suffixes and redundant Fortran declarations (#1511)

Documentation

  • Synced the schema-versioning and transition-guide docs to the finalised 2026.5 schema

Breaking Changes

The YAML schema is finalised to 2026.5 (the 2026.5.dev1..2026.5.dev14 cycle collapsed into one released label). The union of breaking, user-facing changes since 2026.4.3:

  • Fused field names rewritten to snake_case (#1256): for example netradiationmethod -> net_radiation_method, soildepth -> soil_depth, baset -> base_temperature, crwmax -> water_holding_capacity_max
  • ModelPhysics selector renames (#1321): _method / _model suffixes dropped and abbreviations expanded (net_radiation, storage_heat, emissions, stability, water_use, roughness_sublayer, frontal_area_index, surface_conductance)
  • STEBBS YAML surface fully snake_case (#1334, #1337, #1327): the PascalCase exception is retired (124 renames); the hot-water subsystem is unified under hot_water_* (dhw_* dropped)
  • Naming-convention reorder (#1392, #1394, #1452): quantity-first (wall_external_thickness -> thickness_wall_outer), the archetype_* namespace prefix, and building_type dropped
  • Config keys relocated (#1372): model.control.forcing_file -> forcing.file and output_file -> output (inner path -> dir; the legacy string output_file form removed)
  • Forcing file format (#1372, #1420): forcing-file header columns are now read and matched to the canonical column names (previously discarded). The baseline-10 columns (iy, id, it, imin, Tair, RH, U, pres, kdown, rain) are required; missing optional canonical columns are filled with -999; whitelisted per-land-cover columns are accepted (lai_{evetr,dectr,grass}, wuh_<surface>). For laimethod=0, observed LAI is no longer clipped to LAImin/LAImax. Check your forcing files' headers against the canonical names
  • STEBBS physics switches nested (#1456): the flat model.physics STEBBS switches fold under model.physics.stebbs (stebbs.enabled + stebbs.parameters; capacitance, setpoint, same_albedo_*, same_emissivity_* move at their leaf names)
  • frontal_area_index selector reduced (#1495): only observed / modelled are accepted; provided / use_provided / simple_scheme are retired

Upgrade existing YAMLs in one step with suews-schema migrate your_config.yml (the (2026.4 -> 2026.5) handler applies the full union and logs every rename and drop). See the transition guide. There is no model-output change: the schema changes are confined to the YAML surface and the Python data model.

Full Changelog

For complete details, see the CHANGELOG.

Citation

This release is archived on Zenodo with a DOI for academic citation. The DOI appears automatically once Zenodo processing completes (usually within minutes).

Documentation

Assets 2
Loading