# 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 "No input data for your study area? (New in Version 2)"
    The `build_inputs()` function can download and build the required rasters (Building DSM, DEM, Trees, Landuse) and meteorological data for any location from near-globally available urban datasets, using Google Earth Engine. See the [Quick Start Guide](quickstart.md#example-0-optional-download-input-data-automatically) and [API Reference](api_reference.md#build_inputs).

!!! 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](configuration.md#base_path).

## 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](https://umep-docs.readthedocs.io/en/latest/pre-processor/Urban%20Land%20Cover%20Land%20Cover%20Reclassifier.html)).

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%20Data%20MetPreprocessor.html>.

!!! note "Wind direction for directional wind coefficients"
    If you use directional wind-extension coefficients (`ERA_5_z0_find=True` or a `windcoeff_folder`), the meteorological file must contain a wind direction (`Wd`) value for each time step (meteorological wind-from direction: 0=N, 90=E, 180=S, 270=W).

### 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² |
| fsr | Forecast surface roughness (required only if `ERA_5_z0_find=True`, for directional wind coefficients) | 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](https://doi.org/10.5281/zenodo.21081622)

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).