YAML Configuration Format

4.1. YAML Configuration Format#

SUEWS uses YAML configuration files to define all model parameters in a single, human-readable format. This guide shows you how to create and validate your configuration.

4.1.1. Quick Start#

1. Start with the sample configuration:

# Copy the sample configuration
cp sample_config.yml my_config.yml

# Edit for your site
nano my_config.yml

2. Validate and fix your configuration:

# Automatically fix common issues
suews-validate my_config.yml

# Creates: updated_my_config.yml (ready to use)

3. Run your simulation:

import supy as sp

# Load your validated configuration
config = sp.SUEWSConfig.from_yaml('updated_my_config.yml')

# Run simulation
output = config.run()

4.1.2. Configuration Structure#

A SUEWS YAML file has two main sections:

name: "My Simulation"
description: "Urban climate simulation for my city"

model:          # Global simulation settings
  control:      # Time and file settings
  physics:      # Physics options
  output:       # Output control

sites:          # List of sites to simulate
  - name: "Site1"
    properties: # Site characteristics
    land_cover: # Surface fractions
    initial:    # Initial conditions

4.1.3. Essential Parameters#

4.1.3.1. Minimum Configuration Structure#

A valid SUEWS configuration requires many parameters beyond this minimal example. The validator will add missing required parameters with appropriate defaults:

model:
  control:
    tstep: 3600                    # Time step [s]
    forcing_file: "forcing.txt"    # Meteorological data
    start_time: "2020-01-01"       # Start date
    end_time: "2020-12-31"         # End date

sites:
  - name: "MySite"
    properties:
      lat: 51.5                    # Latitude
      lng: -0.1                    # Longitude
      alt: 10.0                    # Altitude [m]
      timezone: 0                  # UTC offset
      surfacearea: 1000000.0       # Area [m²]
    land_cover:
      fractions:
        paved: 0.4                 # Must sum to 1.0
        bldgs: 0.3
        grass: 0.2
        dectr: 0.1

Important

This is a minimal example showing the basic structure. A complete configuration requires many additional parameters for:

Physics options and methods
Initial conditions
Surface properties (albedo, emissivity, roughness)
Vegetation parameters (LAI, conductance)
Soil properties
Anthropogenic heat flux
Water use and irrigation
Building morphology

To explore all parameters:

Run suews-validate on your configuration to generate a complete file with all defaults
Review the generated updated_*.yml file to see all parameters
Consult the YAML Configuration Reference for comprehensive parameter documentation

4.1.4. Parameter Documentation#

Complete Parameter Reference:

The full documentation for all YAML parameters is available in the YAML Configuration Reference. This reference includes:

Detailed descriptions for every parameter
Units and valid ranges
Default values
Cross-references between related parameters

4.1.5. Internal-only parameters#

Some parameters exist in the YAML schema but are internal-only and are therefore intentionally omitted from sample_config.yml. The following parameters were removed from the sample configuration for clarity:

diagnose
dqndt
dqnsdt
dt_since_start
lenday_id
qn_av
qn_s_av
tair_av
tmax_id
tmin_id
tstep_prev
snowfallcum

4.1.6. Forcing Data#

Meteorological forcing data drives the SUEWS simulation. You specify the forcing file(s) in your configuration:

model:
  control:
    forcing_file: "forcing/met_data_2020.txt"
    # Or use multiple files:
    forcing_file:
      - "forcing/met_data_2020_Q1.txt"
      - "forcing/met_data_2020_Q2.txt"
      - "forcing/met_data_2020_Q3.txt"
      - "forcing/met_data_2020_Q4.txt"

Forcing File Format

The forcing file must be a text file with specific columns in the correct order. See Meteorological Forcing Data for the complete format specification.

Essential columns (tab or space separated):

Time columns: iy (year), id (day of year), it (hour), imin (minute)
Wind speed [m/s] - minimum 0.01 m/s
Relative humidity [%]
Air temperature [°C]
Pressure [kPa] - ideally 3, at least 2 decimal places
Rainfall [mm]
Incoming shortwave radiation [W/m²] - must be > 0
Incoming longwave radiation [W/m²] - optional, will be modeled if missing (use -999)

Important requirements:

Data must be continuous (no gaps)
Time stamps indicate the end of each period
Use local time (not UTC)
Use -999 for missing optional variables

For detailed format specifications, column order, and optional variables, see Meteorological Forcing Data.

4.1.7. Validation and Troubleshooting#

4.1.7.1. Using the Validation Tool#

The suews-validate command checks your configuration and fixes common issues:

# Basic validation with automatic fixes
suews-validate config.yml

# Check without making changes
suews-validate validate config.yml

# Get JSON output for scripts
suews-validate validate config.yml --format json

4.1.7.2. What Gets Fixed Automatically#

The validator automatically corrects these issues:

Missing parameters - Adds required fields with sensible defaults
Surface fractions - Normalizes to sum to exactly 1.0
Initial temperatures - Sets based on location and season using climate data
Physics options - Ensures compatible model settings
Parameter names - Corrects common typos and outdated names

For complete validation documentation, see Validation Tool Reference.

4.1.7.3. Common Issues and Solutions#

“Missing required parameter”: The validator will add it with a default value. Check the report to see what was added.
“Surface fractions don’t sum to 1.0”: Automatically normalized. Original values are proportionally adjusted.
“Invalid physics option combination”: The validator suggests compatible options. Manual selection may be needed.
“Unknown parameter name”: Check for typos. The validator will suggest the correct name.

4.1.8. Examples#

4.1.8.1. Urban Site Configuration#

name: "London Urban"
description: "Central London urban climate"

model:
  control:
    tstep: 3600
    forcing_file: "london_met_2020.txt"
    start_time: "2020-01-01"
    end_time: "2020-12-31"
  physics:
    netradiationmethod: 3
    emissionsmethod: 2
    storageheatmethod: 1

sites:
  - name: "CentralLondon"
    properties:
      lat: 51.5074
      lng: -0.1278
      alt: 10.0
      timezone: 0
      surfacearea: 1000000.0
      popdens: 5500.0
    land_cover:
      fractions:
        paved: 0.35
        bldgs: 0.40
        grass: 0.15
        dectr: 0.10
    land_cover_params:
      bldgs:
        bldgh: 20.0
        faibldg: 3.5
      dectr:
        lai_id: 4.5

4.1.9. Tips for Success#

Start with the sample: Always begin with sample_config.yml and modify it
Validate early: Run validation before long simulations
Check the report: Understand what the validator changed
Use meaningful names: Help yourself remember what each simulation is for
Keep originals: The validator creates new files, preserving your originals

4.1.10. Getting Help#

Validation issues: Check the report file (report_*.txt)
Parameter documentation: See the error messages from validation
Examples: Look in sample_data/ directory
Community support: SUEWS Community