Recent Releases of SUEWS

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

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

Climate Change - Earth and Climate Modeling - Python
Published by github-actions[bot] 3 months ago

SUEWS - SUEWS v2026.4.3: Rust FFI Backend, RSL Dynamics & T2 Attribution

Installation

pip install --upgrade supy

What's New

Version 2026.4.3 (released on 3 April 2026)

This release delivers a major backend migration to Rust FFI, RSL physics refinements, a new temperature attribution module, DTS enhancements, seasonal albedo adjustments, comprehensive validation improvements, and extensive bug fixes.

Highlights

Rust FFI Bridge

Replaced f90wrap with a Rust FFI bridge as the sole simulation backend (#1209)
Unified CLI interface with automatic PATH installation (#1215)
Validated Rust output layout against Fortran metadata (#1226)

RSL Physics

Dynamic computation of c2m/c2h from Harman & Finnigan (2007, 2008) RSL theory (#1116)
Refined parameterisation with explicit R = beta * hd / elm (#1232)
Fixed interpolation bounds and division-by-zero pitfalls in RSL profiles (#1228, #1229)

T2 Attribution Module

Diagnose near-surface temperature, humidity, and wind speed changes by physical process contributions, with diurnal cycle and heatmap visualisation (#918)

Seasonal Albedo

Seasonal adjustment of surface albedo (alb_id) for vegetated surfaces (#1211)
Auto-initialise vegetation albedo from phenology state (#1133)

DTS Enhancements

chunk_day parameter for long simulations (#1172)
run_dts_multi for multi-grid simulation support (#1173)
Hardened parallel multi-grid execution (#1176)
Fixed Pydantic model serialisation across multiprocessing spawn boundaries (#1197)

Validation

Draft rules registry for structured validator rule management (#1246)
Conditional validation via Pydantic v2 model_fields_set (#1247)
Upper limit on nlayer to prevent run crashes (#1206)
SUEWSOutput index property (#1178)

Bug Fixes

Guarded SPARTACUS LW solver against NaN from matrix singularity (#1212)
Fixed SUEWS output packing overflow with fail-fast behaviour (#1198)
Fixed Pydantic dict format handling in YAML numeric parser (#1236)
Pinned pydantic>=2.12 to prevent OSGeo4W version conflict (#1213)
Fixed STEBBS WWR extreme cases (WWR = 0 or 1) (#1261)
Fixed biogenic CO2 to use local climate instead of global average (#1117)
Fixed missing STEBBS parameters in sample_config.yml (#1111)
Auto-repair stale refs in fetch_origin conductor (#1239)

CI and Security

Hardened dependency supply chain after LiteLLM incident with startup hook auditing (#1264)
Rust change detection and Cargo build caching across all platforms (#1217, #1219)
Gated tag-triggered deployments on master ancestry (#1162)
Pre-built documentation served from rtd branch (#1167)
Deprecated env.yml and conda/mamba build pathway (#1163)

Other Improvements

Discourse-to-GitHub issue bridge with webhook sync (#1138)
Status tags for changelog entries (governance) (#1181)
Revised README as science-first landing page (#1265)
Anthropogenic emission defaults and parameter guidance (#1231)
User workflow guide for getting started (#1014)
Executable documentation examples using sphinx-gallery (#1057)

Breaking Changes

f90wrap is no longer supported; the Rust FFI bridge is the sole backend (#1209)
Deprecated env.yml and conda/mamba build pathway (#1163)

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

Climate Change - Earth and Climate Modeling - Python
Published by github-actions[bot] 5 months ago

SUEWS - SUEWS v2026.1.28: QGIS Stability Improvements

Installation

pip install --upgrade supy

What's New

Version 2026.1.28 (released on 28 January 2026)

This release focuses on stability improvements for QGIS/UMEP users, physics corrections, and executable documentation.

Notable Changes

QGIS Crash Fix

Resolved crash issue where SUEWS caused QGIS to fail mid-run
Removed stdout writes (PRINT *, WRITE(*,*)) that conflicted with QGIS output handling
Replaced problematic code with structured warnings
Improved thread safety for parallel simulations
Related PRs: #1086, #1083

QGIS/UMEP Test Suite

Added comprehensive compatibility tests to catch QGIS integration issues before release (#905)

Executable Documentation

Tutorial examples now run during documentation builds via sphinx-gallery
Ensures code examples remain current (#1057)

Physics Fixes

Biogenic CO2: Fixed FcRespi calculation to use local climate instead of global average temperature (#1117)
NumCapita Initialisation: Fixed uninitialised NumCapita causing NaN values in CO2 flux calculations (#1053)
Error Flag Management: Reset error flag before kernel calls to prevent stale errors across runs (#1109)

Other Improvements

Pandas 3.0 forward compatibility (#1106)
Improved validation ranges for albedo and emissivity (#978, #979)
Structured error handling with detailed validation reports (#1070)
Vendored f90wrap runtime to eliminate pip dependency conflicts (#963)

Breaking Changes

None. Full backward compatibility maintained with version 2025.11.20.

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

Climate Change - Earth and Climate Modeling - Python
Published by github-actions[bot] 7 months ago

SUEWS - SUEWS v2025.11.20: Enhanced Validation & Legacy Data Support

This release focuses on enhanced validation capabilities, modern OOP interface improvements, and comprehensive support for legacy data formats.

Major Features

Modern OOP Interface: New SUEWSSimulation.from_sample_data() factory method with method chaining, state properties, and validation helpers
Enhanced Validation Framework:
- Physics-specific forcing data validation
- Irrigation parameter validation with hemisphere awareness
- Daylight saving time validation
- STEBBS building model parameter constraints (50+ parameters)
- Human activity parameter validation
Legacy Data Support: Comprehensive fixes for YAML converter handling 2017 URBANFLUXES data formats
ERA5 Download Simplification: Streamlined implementation with reduced dependencies (removed earthkit.data, made xarray optional)
Documentation Modernisation: All tutorials updated to showcase OOP interface exclusively

Changelog

20 Nov 2025

[doc] Updated tutorials and API documentation to use modern OOP interface (#881)
- Updated impact-studies.ipynb, quick-start.ipynb, setup-own-site.ipynb to use SUEWSSimulation.from_sample_data()
- Updated data-structures.rst code examples
- Completed modernisation started in #779

19 Nov 2025

[bugfix] Fixed last layer of validation for DLS startdls and endls parameters (#877)
- Instead of hemisphere pattern check (NH/SH typical ranges), now phase C provide NO ACTION NEEDED info to user with calculated DLS startdls and endls (to compare against user values)
- Useful when Phase C runs standalone or via SUEWSConfig.from_yaml() (Phase B auto-corrects values in full pipeline)

18 Nov 2025

[change] BREAKING: Simplified ERA5 download implementation and renamed data_source parameter values (#874)
- Removed earthkit.data dependency - both download methods now use cdsapi directly
- data_source parameter values renamed for clarity:
  - "timeseries" (new default, was "earthkit"): Fast ERA5 timeseries dataset for point locations
  - "gridded" (was "cdsapi"): Traditional gridded ERA5 with model levels and spatial grids
- Timeseries downloads CSV directly and loads in-memory (zero extra dependencies)
- Gridded path requires optional h5netcdf for netCDF4 reading (install separately: pip install h5netcdf)
- Same fast performance for timeseries (~26s for 30 years) with minimal dependencies
[change] Made xarray optional dependency (only needed for gridded ERA5) (#874)
- CSV timeseries path now uses pure pandas (no xarray conversion)
- Significantly faster for timeseries: 1.2s vs 10-15s for test case
- ~10x speed improvement by eliminating pandas → xarray → pandas round-trip
[change] Removed dask dependency (was redundant with multiprocess) (#874)
- CLI now uses multiprocess.pool.ThreadPool for parallel batch simulations
- Same functionality, lighter dependencies

14 Nov 2025

[feature] Added SUEWSSimulation.from_sample_data() factory method and comprehensive OOP enhancements (#779)
- New factory method for cleaner OOP workflow: sim = SUEWSSimulation.from_sample_data()
- Added visual feedback with __repr__() showing simulation status (Not configured, Ready, Complete)
- Added state access properties: state_init and state_final
- Added validation methods: is_ready() and is_complete()
- Enabled method chaining for fluent interface (update_config(), update_forcing(), reset() return self)
- Added get_variable() helper for extracting specific variables from MultiIndex results
- Implemented deprecation infrastructure for functional API (maintains backward compatibility)
[feature] Added Phase C validation for daylight saving time parameters (#857)
- Four validation layers: (1) basic range [1, 366], (2) consistency (both set or both None), (3) leap year (DOY 366 only in leap years), (4) hemisphere pattern check (NH/SH typical ranges)
- First three layers raise ERROR; hemisphere check adds INFO to report "NO ACTION NEEDED" section

12 Nov 2025

[feature] Added irrigation year-wrapping pattern detection (#843)
- Warns for unusual patterns (NH: ie_start > ie_end; SH: ie_start < ie_end)
- Integrated into Phase B scientific validation pipeline

11 Nov 2025

[feature] Added irrigation parameter validation (#843)
- Validates ie_start and ie_end for DOY range, consistency, and hemisphere-aware seasonal appropriateness
- NH (lat ≥ 23.5°): warm season DOY 121-273; SH (lat ≤ -23.5°): DOY 305-90; Tropics (|lat| < 23.5°): year-round
[bugfix] Fixed YAML converter errors with legacy data (#846)
- Fixed logging errors when sys.stdout is None (e.g., in QGIS)
- Fixed missing NML file handling (SPARTACUS, ESTM) to return empty containers
- Added graceful handling of legacy profile file formats (2017 data)
- Added automatic placeholder generation for missing lookup codes
- Fixed column count mismatches in legacy table files
- Preserved BaseT_HC during 2021a→2023a table conversion
- Added comprehensive tests with real URBANFLUXES 2017 data

05 Nov 2025

[feature] Added physics-specific forcing data validation (#824)
- check_forcing() validates required forcing columns (qn, qf, qs, ldown, fcld, xsmd) based on physics configuration
- Integrated with Phase A validation pipeline; backwards compatible
- Added helpful error messages with documentation links

4 Nov 2025

[bugfix] Fixed land cover fraction validation to use floating-point tolerance (#820)
- Changed from exact equality check to tolerance-based check (abs(total_fraction - 1.0) > 1e-6)
- Uses same tolerance (1e-6) as Phase B fraction normalisation

31 Oct 2025

[bugfix] Fixed Phase B validator to not nullify lai_id when surface fraction is zero (#815)
- Preserves user-provided initial state values even when surface is not active
- Prevents crashes when users later change surface fraction from 0 to non-zero values
[bugfix] Added rcmethod to required physics options in validation system (#814)
- Updated validation pipelines: Phase A, Phase B, and orchestrator
- Controls method for splitting building envelope heat capacity in STEBBS

29 Oct 2025

[feature] Added validation constraints for human activity parameters (#798)
- faut: Fraction of irrigated area using automatic systems [0.0, 1.0]
- frfossilfuel_heat, frfossilfuel_nonheat: Fossil fuel fractions [0.0, 1.0]
- popdensnighttime: Population density must be ≥ 0.0 (persons/ha)
[bugfix] Fixed irrigation parameter units: ie_start and ie_end now correctly identified as Day of Year (DOY) instead of hours (#843)
[feature] Phase B validator now automatically populates OutdoorAirAnnualTemperature from CRU dataset (#808)
- Uses CRU TS4.06 1991-2020 climate normals

24 Oct 2025

[feature] Added physical range validation for 50+ STEBBS building model parameters (#746)
- Dimensionless parameters (emissivity, transmissivity, absorptivity, reflectivity, ratios) constrained to [0.0, 1.0]
- Physical properties (thickness, conductivity, density, heat capacity) constrained to positive values
[doc] Added comprehensive documentation for forcing data validation functions (#773)

22 Oct 2025

[feature] Forcing data validation integrated into Phase A validator (#767)
- Added automatic validation of meteorological forcing data in Phase A pipeline
- Validates all forcing files when multiple files are provided
- Line numbers in error messages match actual file line numbers for easy debugging

21 Oct 2025

[feature] Added get_mean_annual_air_temperature() for stable parameter initialisation using CRU TS4.06 climate normals (#762)
[bugfix] Fixed Phase B validation to update roofs/walls temperature fields from CRU climate data (#736)

20 Oct 2025

[bugfix] Fixed recursive nested config updates in SUEWSSimulation (#756)
- Resolved issue where updating nested configuration settings converted parameters to dictionaries
- Ensures df_state_init can be generated correctly after nested updates

17 Oct 2025

[bugfix] Fixed nlayer nested structures detection in validation system (#731)
- Enhanced validation for complex nested arrays in vertical layers configuration

16 Oct 2025

[bugfix] Fixed Sphinx configuration errors preventing ReadTheDocs builds

Installation

Standard (NumPy 2.x):

pip install --upgrade supy

UMEP/QGIS Compatible (NumPy 1.x):

pip install supy==2025.11.20rc1

Citation

This release is automatically archived on Zenodo and assigned a DOI for academic citation. The DOI will appear here once Zenodo processing is complete (usually within a few minutes).

Documentation

Climate Change - Earth and Climate Modeling - Python
Published by sunt05 10 months ago

SUEWS - SUEWS v2025.10.15: YAML Configuration System Release

This release introduces a modern YAML-based configuration system with comprehensive validation, marking a significant infrastructure upgrade for SUEWS.

Major Features

YAML Configuration System: Modern, human-readable configuration format with 697 documented parameters
Schema Versioning: Independent schema versions (1.0, 1.1, etc.) separate from model versions for cleaner configuration evolution
Three-Phase Validation Framework:
- Structure validation: YAML syntax and schema compliance
- Physics validation: Scientific parameter constraints with CRU TS4.06 climatological data
- Model validation: SPARTACUS multi-layer configurations, STEBBS constraints
JSON Schema Support: IDE integration enabling autocomplete and inline validation in VS Code, PyCharm, Vim and other editors
CLI Tools:
- suews-schema: Schema management (info, validate, migrate, export)
- suews-convert: Legacy table-to-YAML conversion
- suews-validate: Configuration validation
Build System Improvements: Automatic UMEP/QGIS compatible builds (rc1 variants) with NumPy 1.x for QGIS 3.40 LTR compatibility
Cross-Platform Enhancements: Python 3.13 support, Linux manylinux2014 compatibility, Windows Unicode fixes

Changelog

15 Oct 2025

[feature] Enhanced UMEP/QGIS build system with nightly builds and improved version handling (cdb4273, 8f540b9, 636c1b9, 35510bb, 4a972c7)
- Enabled UMEP nightly builds with .dev1 versioning strategy for continuous testing
- Explicitly excluded nightly builds from UMEP workflow to prevent conflicts
- Added UMEP builds to master/manual workflow runs
- Aligned UMEP builds with QGIS Python 3.12 requirements
[bugfix] Fixed sample output validation test to skip for NumPy 1.x builds (a4017cc)
[bugfix] Removed path filter from tag triggers to ensure all tagged builds are processed (1eb6667)
[maintenance] Performance improvement in Conductor setup by removing unnecessary build steps (ddedf96)

Installation

Standard (NumPy 2.x):

pip install suews==2025.10.15

UMEP/QGIS Compatible (NumPy 1.x):

pip install suews==2025.10.15rc1

Documentation

Climate Change - Earth and Climate Modeling - Python
Published by sunt05 11 months ago

SUEWS - CITATION-added

This release adds a CITATION file for proper citation of this repo.
Functionality-wise, the SUEWS model stays the same as last supy release (v2024.3.25.dev).

Climate Change - Earth and Climate Modeling - Python
Published by sunt05 over 2 years ago

SUEWS - 2020a Release

Improvement

A ponding water scheme is added in the automatic irrigation calculation; useful when a certain depth of ponding water to maintain in irrigation (e.g., flooding irrigation in rice
crop-field).
Irrigation fraction can be specified for all surfaces (previously only available for vegetated surfaces)
A U-shape approach for calculating HDD/CDD is introduced to account for a wide comfort zone between heating and cooling critical temperatures.

Changes

A new RoughLenHeatMethod option 5: adaptively choose option 1 for fully pervious surface or 2 otherwise (if any impervious surface exists).
A new column H_maintain is added in SUEWS_Irrigation.txt to set ponding water depth.
New columns to specify irrigation fractions for non-vegetated surfaces in SUEWS_SiteSelect.txt.
A new scheme option BaseTMethod in RunControl.nml to set calculation scheme for HDD/CDD.

Fix

NONE.

Known issues

Wind direction is not currently downscaled so non -999 values
will cause an error.

Climate Change - Earth and Climate Modeling - Python
Published by sunt05 almost 5 years ago