Version 2026.6.5 (released on 5 June 2026)

Tip

  1. Need help? Please let us know in the SUEWS Community.

  2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

  3. Please cite SUEWS with proper information from our Zenodo page.

11.1. 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), all migrated 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 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 no longer 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:

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 Transitioning to YAML-based Configuration. There is no model-output change: the schema changes are confined to the YAML surface and the Python data model.

For complete details, see the CHANGELOG.