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.2. Version 2025.11.20 (released on 20 November 2025)

This release focuses on comprehensive validation improvements, legacy data compatibility, and API modernisation, making SUEWS more accessible and robust.

Major Features:

• Enhanced Validation System: Comprehensive physics-aware validation for irrigation parameters, daylight saving time (DLS), and STEBBS building model parameters (50+ parameters). The system now performs hemisphere-aware seasonal checks and provides detailed validation reports. See validation documentation for details.

• Legacy Data Support: Fixed YAML converter to handle legacy SUEWS configuration files from 2017+, including graceful handling of missing NML files, legacy profile formats, and column count mismatches. Enables seamless migration from historical datasets to modern YAML format. (#846)

• Modern OOP API: New SUEWSSimulation.from_sample_data() factory method provides a cleaner onboarding experience with visual feedback (__repr__), state properties (state_init, state_final), validation methods (is_ready(), is_complete()), method chaining, and variable extraction helper (get_variable()). The functional API remains fully supported with deprecation warnings. (#779)

• ERA5 Download Refactoring: Simplified implementation using new CDS API timeseries data source with zero extra dependencies for point locations. Removed earthkit.data dependency, made xarray and dask optional (only needed for gridded ERA5), achieving ~10x speed improvement for timeseries workflows. (#874)

API Enhancements:

• Quick Start Pattern: Get started with SUEWS in 3 lines:

  from supy import SUEWSSimulation
  sim = SUEWSSimulation.from_sample_data()
  sim.run()
  

• Variable Extraction: New get_variable() method simplifies working with MultiIndex results:

  qh = sim.get_variable('QH')  # Sensible heat flux
  qe = sim.get_variable('QE')  # Latent heat flux
  

• State Access: Access initial and final states for continuation workflows:

  initial = sim.state_init   # Initial state DataFrame
  final = sim.state_final    # Final state after simulation
  

Validation Improvements:

• Irrigation Parameters: Validates DOY ranges, consistency, and hemisphere-aware seasonal patterns (NH/SH/Tropics)

• Daylight Saving Time: Four-layer validation including leap year checks and hemisphere pattern detection

• STEBBS Parameters: Physical range constraints for 50+ building model parameters

• Forcing Data: Physics-specific validation for required meteorological variables

Breaking Changes:

• ERA5 downloads now use CDS API’s new timeseries data source by default (data_source="timeseries"): - Fast point location downloads with zero extra dependencies - ~10x speed improvement by using CSV directly (no xarray conversion) - Removed earthkit.data dependency - both download methods now use cdsapi directly

• For traditional gridded ERA5 with spatial grids and model levels, explicitly set data_source="gridded" and install optional dependencies: pip install xarray h5netcdf

Dependencies:

• Made xarray optional (only needed for gridded ERA5)

• Made dask optional (removed in favour of multiprocess for CLI)

• Removed earthkit.data dependency

Documentation Updates:

• Updated all tutorials to use modern OOP interface

• Added comprehensive OOP API documentation

• Updated workflow examples with from_sample_data() pattern

For complete details, see the CHANGELOG.