Input Data

SOLWEIG-GPU requires two main types of input data: geospatial rasters and meteorological forcing data. This guide provides detailed information on how to prepare and format your input data.

!!! tip “Outputs in a different folder.” If you want outputs written to a different directory, set base_path to that folder and pass complete paths for the Building DSM, DEM, Trees, and land cover (optional) rasters. See Configuration.

Geospatial Rasters

All input rasters must be in GeoTIFF format and share the same properties to ensure proper alignment and processing.

Requirements

!!! Critical Requirements: All input rasters must have the following

- Identical Coordinate Reference System (CRS)
- Same dimensions (width and height in pixels)
- Same pixel size (spatial resolution)
- Proper alignment (same geotransform)

The package includes validation checks that will raise errors if these requirements are not met.

Required Rasters

Building DSM

Filename: Building_DSM.tif (default)

A Digital Surface Model that includes the height of both buildings and terrain.

Units: Meters above a reference datum

!!! Tip “Creating Building DSM”: Building DSM can be created by combining:

- LiDAR point cloud data
- Photogrammetric 3D models
- Building footprints with height attributes merged with terrain elevation

Digital Elevation Model (DEM)

Filename: DEM.tif (default)

A Digital Elevation Model representing the bare-earth elevation.

Units: Meters above a reference datum

!!! Tip “DEM Sources”: High-quality DEMs can be obtained from:

- National elevation datasets (e.g., USGS 3DEP for USA)
- LiDAR-derived bare-earth models
- SRTM or ASTER GDEM for global coverage (lower resolution)

Tree DSM

Filename: Trees.tif (default)

A Digital Surface Model representing only the vegetation heights (The Tree DSM should represent the height of vegetation canopy above the ground surface, not above the reference datum.). Pixels with no tree coverage should be zero.

Units: Meters

Land Cover (Optional)

Filename: Landcover.tif (optional)

A raster representing land cover types. If not provided, the model will assume default land cover properties. The package accepts UMEP-style land cover (see Urban Land Cover Reclassifier).

The package uses the classification scheme defined in landcoverclasses_2016a.txt. Key classes include:

Code

Description

1

Paved surfaces

2

Buildings

3

Water

4

Vegetation

5

Bare soil

Meteorological Forcing Data

SOLWEIG-GPU supports three different types of meteorological data sources. You must choose one of these options for your simulation.

Option 1: Custom Text File (UMEP Format)

A text file with a specific format generated by the UMEP (Urban Multi-scale Environmental Predictor) tool: https://umep-docs.readthedocs.io/en/latest/pre-processor/Meteorological Data MetPreprocessor.html.

Option 2: ERA5 Reanalysis Data

NetCDF files from the Copernicus Climate Data Store containing ERA5 reanalysis data: https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels?tab=overview.

Required Files: Both instantaneous and accumulated data files

Required Variables:

Variable

Description

Units

t2m

2-meter air temperature

K

d2m

2-meter dew point temperature

K

sp

Surface pressure

Pa

u10

10-meter U wind component

m/s

v10

10-meter V wind component

m/s

ssrd

Surface solar radiation downwards (accumulated)

J/m²

strd

Surface thermal radiation downwards (accumulated)

J/m²

File Naming: ERA5 files should be named according to the standard ERA5 naming convention (do not rename the downloaded ERA-5 instantaneous and accumulated data).

Option 3: WRF Output Files

Output files from the Weather Research and Forecasting (WRF) model.

File Format: NetCDF (wrfout files)

Filename Pattern: Must follow one of these patterns:

  • wrfout_d0X_YYYY-MM-DD_HH_MM_SS (recommended, works across all operating systems)

  • wrfout_d0X_YYYY-MM-DD_HH:MM:SS

  • wrfout_d0X_YYYY-MM-DD_HH

Where X is the domain number (1-9).

Required Variables: The package automatically extracts the required meteorological variables from the WRF output files.

!!! warning “Time Specification.” When using WRF data, you must specify start_time and end_time in UTC. The package will automatically convert to local time.

Data Preparation Tips

Coordinate Reference System

Choose an appropriate projected coordinate system for your study area. UTM zones are commonly used for urban-scale studies.

Temporal Resolution

Currently, SOLWEIG-GPU is tested and optimized for hourly data. Sub-hourly or multi-hourly data may require modifications to the code.

Sample Data

A complete sample dataset is available for download to help you understand the expected data format and structure.

Download: Sample Data on Zenodo

The sample dataset includes:

  • Example input rasters for Austin, Texas

  • Meteorological forcing data in all three formats (custom text, ERA5, WRF)

!!! Tip: We recommend starting with the sample data to familiarize yourself with the package before processing your own data. For a quick test, download only ERA5 or ownmet data, since the entire forcing data set is too large (which includes high-resolution WRF data).