SUEWS 2025.10.15 Released: Modern YAML Configuration System

[sunt05]

SUEWS 2025.10.15 Released: Modern YAML Configuration System

We're excited to announce SUEWS version 2025.10.15, now available on PyPI! This major release introduces a modern YAML-based configuration system that makes SUEWS more accessible, maintainable, and user-friendly.

🎯 What's New

Modern YAML Configuration

Say goodbye to complex table-based inputs! The new YAML configuration system provides:

• Human-readable format: Clear, structured configuration files that are easy to read and edit
• IDE integration: Autocomplete and inline validation in VS Code, PyCharm, Vim, and other editors
• Comprehensive documentation: 697 documented parameters with detailed descriptions and use-case guides
• Schema versioning: Independent schema versions (1.0, 1.1, etc.) that evolve separately from model versions

Example configuration structure:

version: "1.0"
site:
  location:
    lat: 51.5074
    lon: -0.1278
  surface:
    roughness_length: 0.5
    ...

Three-Phase Validation Framework

Never struggle with cryptic error messages again! The new validation system provides:

1. Structure validation: Checks YAML syntax and schema compliance
2. Physics validation: Validates scientific parameter constraints using CRU TS4.06 climatological data
3. Model validation: Ensures SPARTACUS multi-layer configurations and other model-specific constraints

Enhanced error reporting gives you:

• Clear, actionable feedback
• Specific field locations
• Automatic fixes for common issues
• Missing value detection

Easy Migration Tools

Don't worry about your existing configurations! We provide comprehensive migration tools:

# Convert legacy table format to YAML
suews-convert input_tables/ -o my_config.yml

# Validate your configuration
suews-validate my_config.yml

# Get schema information
suews-schema info

The old table-based format still works - you can migrate at your own pace.

🚀 Quick Start

Installation

pip install --upgrade supy

For UMEP/QGIS users, install the RC version:

pip install supy==2025.10.15rc1

New CLI Tools

This release includes three powerful command-line tools:

• suews-schema: Schema management (info, validate, migrate, export)
• suews-convert: Legacy table-to-YAML conversion
• suews-validate: Configuration validation with detailed error reporting

Getting Started with YAML

# Convert your existing configuration
suews-convert my_old_inputs/ -o config.yml

# Validate the new configuration
suews-validate config.yml

# Use it in your workflow
import supy
result = supy.run_suews(config_file='config.yml')

📚 Documentation

Full documentation is available in the SUEWS documentation:

• YAML Configuration Guide
• Migration Guide
• Validation Framework
• Schema Reference

🔧 Additional Improvements

This release also includes:

• Python 3.9-3.13 support: Full support across all currently maintained Python versions
• Cross-platform improvements: Better Windows Unicode handling, enhanced Linux compatibility
• Fortran code formatting: Consistent code style with fprettify
• Build system enhancements: Improved wheel building and UMEP/QGIS compatibility

💬 Questions or Issues?

If you encounter any issues or have questions about the new YAML system:

1. Check the documentation
2. Report issues on GitHub
3. Ask questions here in discussions

We're here to help make your transition to the new configuration system as smooth as possible!

🙏 Feedback Welcome

This is a major upgrade to SUEWS's configuration infrastructure. We welcome your feedback on:

• Migration experience
• Documentation clarity
• Validation error messages
• Feature requests for the YAML system

Happy modelling! 🌆

---

Full changelog: https://github.com/UMEP-dev/SUEWS/blob/master/CHANGELOG.md#15-oct-2025
Version documentation: https://suews.readthedocs.io/stable/version-history/v2025.10.15.html