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

• User Guide
• YAML Configuration Guide
• Complete CHANGELOG
• GitHub Repository

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

• YAML Configuration Guide
• Full Documentation
• Complete CHANGELOG

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).

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.