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.

4.4. SUEWS Format Converter

The suews-convert tool provides seamless conversion between different SUEWS input formats and versions. It supports:

• Version migration: Update older SUEWS input files to newer table formats

• Format conversion: Transform legacy table-based inputs to modern YAML format

Note

From v2025a onwards, SUEWS uses YAML format as the primary configuration method. The converter automatically determines the output format based on the target version.

Tip

Python API Available: For programmatic access (e.g., integrating with QGIS plugins or other tools), see the Configuration Converter API documentation for direct Python function usage.

4.4.1. Command-Line Usage

suews-convert -f FROM_VERSION -t TO_VERSION -i INPUT_PATH -o OUTPUT_PATH

The converter automatically determines the conversion type:

• Versions before 2025 (e.g., 2024a): Table-to-table conversion

• Version 2025a or later: Converts to YAML format

• Same version (e.g., 2016a to 2016a): Reformats files only (removes inline comments, fixes whitespace, standardises delimiters, organises into correct directory structure)

4.4.2. Parameters

4.4.2.1. Required Parameters:

• -i, --input: Input directory containing SUEWS files (must have RunControl.nml)

• -o, --output: Output path (directory for table conversion, file path for YAML)

4.4.2.2. Optional Parameters:

• -f, --from: Source version (e.g., ‘2020a’, ‘2024a’). If not specified, the converter will auto-detect the version

• -t, --to: Target version. Options include:

  • Specific version (e.g., ‘2024a’ for tables, ‘2025a’ for YAML)

  • latest (default): Converts to the current YAML format

• -d, --debug-dir: Directory to save intermediate conversion files for debugging

• --no-profile-validation: Disable automatic profile validation and creation of missing profiles

• --force-table: Force table output format even for 2025a (skip YAML conversion)

4.4.3. Examples

Auto-detect version and convert to latest YAML:

suews-convert -i your_suews_folder -o config.yml
# Auto-detects source version and converts to latest YAML format

Table-to-table conversion (pre-2025):

suews-convert -f 2018a -t 2024a -i your_2018a_folder -o your_2024a_folder

Table-to-YAML conversion (2025+):

suews-convert -f 2024a -t 2025a -i your_2024a_folder -o config.yml

Debug intermediate steps:

suews-convert -f 2016a -t latest -i old_data -o config.yml -d debug_output
# Saves intermediate conversion files in debug_output directory

Tip

The converter uses the RunControl.nml file in your input folder to determine the location of input tables. This ensures that custom paths specified in FileInputPath are correctly handled.

4.4.4. Version Detection

The converter can automatically detect the version of your input files by examining:

• File existence patterns (e.g., SUEWS_AnthropogenicEmission.txt vs SUEWS_AnthropogenicHeat.txt)

• Column presence/absence in specific tables

• Parameters in RunControl.nml (for 2024a+)

• Optional files like SUEWS_SPARTACUS.nml

If auto-detection fails, you can specify the source version explicitly with -f.

4.4.5. Path Handling

The converter respects path configurations in RunControl.nml:

• Absolute paths: Used directly as specified

• Relative paths: Resolved relative to the input directory

• Automatic fallback: If files aren’t found at the configured path, the converter checks:

  1. The root input directory

  2. The path specified in FileInputPath

  3. The Input/ subdirectory

This flexible approach ensures the converter works with various directory structures while respecting user-configured paths.