WindProfileClusteringModel

The WindProfileClusteringModel is the standard AWESPA implementation of the wind module. It wraps the wind-profile-clustering package and provides three functionalities:

  1. Clustering — identify representative wind profile shapes from reanalysis or measurement data using K-means on PCA-reduced profiles.

  2. Fitting — fit a logarithmic or power-law profile to measured wind data.

  3. Prescribing — build an analytical wind profile without measured data, using a prescribed profile shape and Weibull wind speed distribution.

All three functionalities write a wind resource file in awesIO YAML format, which is the shared input for the power module and the AEP pipeline.

Supported data sources

For these data sources there are already built-in readers, so users can simply point to the raw data files and the wrapper will handle the rest:

  • era5 — ERA5 reanalysis data (NetCDF files from Copernicus)

    The convention is to organise the ERA5 files in a directory structure like data/wind_data/era5/<year>/ml_<YYYY>_<MM>.netcdf. For the surface files the convention is similar but with sfc_<YYYY>_<MM>.netcdf. The wrapper will automatically find and read all files in the specified year range.

  • fgw_lidar — FGW lidar measurement files

  • dowa — Dutch Offshore Wind Atlas data

For DOWA data, download the time series files from 2008-2017 at 10-600 meter height for your desired grid location.

For ERA5 data, take a look at the following repo that explains how to download ERA5 data using the CDS API: https://github.com/awegroup/awe-era5. It also mentions a pre-downloaded ERA5 dataset from 2011-2017 covering Europe.

The wrapper automatically selects the correct data reader based on the data_source.type setting in the configuration file.

Wrapper

class awespa.wind.clustering.WindProfileClusteringModel[source]

Bases: WindProfileModel

Wrapper for the wind-profile-clustering repository.

This wrapper adapts the vendored wind profile clustering functionality to the AWESPA modular architecture, handling data paths redirection and YAML-based configuration.

__init__()[source]

Initialize the wind profile clustering model.

load_configuration(configPath: Path, validate: bool = True) → None[source]

Load configuration parameters from a YAML file.

Parameters:

  • configPath (Path) – Path to the YAML configuration file.

  • validate (bool) – If True, validate configuration files using the awesIO validator. Defaults to True.

cluster(dataPath: Path, outputPath: Path, verbose: bool = False, showplot: bool = False, saveplot: bool = False, validate: bool = True) → None[source]

Perform wind profile clustering on the input data.

Parameters:

  • dataPath (Path) – Path to the wind data directory.

  • outputPath (Path) – Path where output YAML file will be written.

  • verbose (bool) – If True, print progress and diagnostic information. Defaults to False.

  • showplot (bool) – If True, display plots after clustering. Defaults to False.

  • saveplot (bool) – If True, save plots to disk. Defaults to False.

  • validate (bool) – If True, validate the output YAML file using the awesIO validator. Defaults to True.

fit_profile(dataPath: Path, outputPath: Path, verbose: bool = False, showplot: bool = False, saveplot: bool = False, validate: bool = True) → Dict[str, Any][source]

Fit a logarithmic or power law profile to wind data and export to YAML.

Parameters:

  • dataPath (Path) – Path to the wind data directory.

  • outputPath (Path) – Path where output YAML file will be written.

  • verbose (bool) – If True, print progress and diagnostic information. Defaults to False.

  • showplot (bool) – If True, display plots after fitting. Defaults to False.

  • saveplot (bool) – If True, save plots to disk. Defaults to False.

  • validate (bool) – If True, validate the output YAML file using the awesIO validator. Defaults to True.

Returns:

Dictionary containing the fit results with keys

’fitResults’ and ‘fitParams’.

Return type:

Dict[str, Any]

prescribe_profile(outputPath: Path, verbose: bool = False, showplot: bool = False, saveplot: bool = False, validate: bool = True) → Dict[str, Any][source]

Build a prescribed analytical wind profile and export to YAML.

No measured wind data is required. The wind speed probability distribution is a Weibull distribution defined by a mean wind speed and shape factor k, with a single omnidirectional wind-direction bin.

When parameters are None they fall back to values loaded from the configuration file via load_configuration.

Parameters:

  • outputPath (Path) – Path where output YAML file will be written.

  • verbose (bool) – If True, print progress and diagnostic information. Defaults to False.

  • showplot (bool) – If True, display plots after prescribing. Defaults to False.

  • saveplot (bool) – If True, save plots to disk. Defaults to False.

  • validate (bool) – If True, validate the output YAML file using the awesIO validator. Defaults to True.

Returns:

Dictionary containing ‘profileParams’,

’weibullParams’, and the full result dict from prescribe_wind_profile.

Return type:

Dict[str, Any]

Configuration file

All settings are provided in a single YAML file. The file is divided into sections for general settings, data source, clustering, fitting, and prescribing. An annotated example is shown below (see config/example/wind_clustering_settings.yml):

# ============================================================================
# GENERAL SETTINGS
# ============================================================================
# Reference height used for wind speed normalisation across all functionalities
ref_height: 200.0               # Reference height [m]

# ============================================================================
# DATA SOURCE CONFIGURATION
# ============================================================================
data_source:
  type: "era5"                  # 'era5' | 'fgw_lidar' | 'dowa'
  location:
    latitude: 54.13
    longitude: -9.78
  altitude_range: [10, 500]     # [m]
  years: [2011, 2011]           # inclusive

# ============================================================================
# CLUSTERING PARAMETERS
# ============================================================================
clustering:
  n_clusters: 8                 # Number of K-means clusters
  n_pcs: 5                      # Principal components retained
  n_wind_speed_bins: 50         # Bins for wind speed probability distribution

  # Metadata for the output file
  name: "Wind Profile Clustering"
  description: "Wind profile clustering results"

# ============================================================================
# FITTING PARAMETERS
# ============================================================================
fitting:
  profile_type: "logarithmic"   # 'logarithmic' or 'power_law'

  # Metadata for the output file
  name: "Wind Profile Fit"
  description: "Wind profile obtained by fitting an analytical profile to data"

# ============================================================================
# PRESCRIBING PARAMETERS
# ============================================================================
prescribing:
  profile_type: "logarithmic"   # 'logarithmic' or 'power_law'
  altitude_range: [10, 500]     # Altitudes to evaluate [m]

  # Weibull wind speed distribution
  mean_wind_speed: 10.0         # Mean wind speed at ref_height [m/s]
  weibull_k: 2.0                # Weibull shape factor k [-]
  n_samples: 100000             # Synthetic samples for distribution

  # Logarithmic profile parameters
  friction_velocity: 0.4        # u* [m/s]
  roughness_length: 0.03        # z0 [m]

  # Power law profile parameters
  alpha: 0.14                   # Power law exponent [-]

  # Metadata for the output file
  name: "Prescribed Wind Profile"
  description: "Wind resource file with a prescribed analytical wind profile"

Usage examples

Using the ready-made script:

python scripts/run_wind_clustering.py

Clustering

from pathlib import Path
from awespa.wind.clustering import WindProfileClusteringModel

model = WindProfileClusteringModel()
model.load_configuration(Path("config/example/wind_clustering_settings.yml"))

model.cluster(
    dataPath=Path("data/wind_data/era5"),
    outputPath=Path("results/example/wind_resource.yml"),
    verbose=True,
    showplot=False,
    saveplot=True,
)

Fitting a profile

model = WindProfileClusteringModel()
model.load_configuration(Path("config/example/wind_clustering_settings.yml"))

model.fit_profile(
    dataPath=Path("data/wind_data/era5"),
    outputPath=Path("results/example/wind_resource_fit.yml"),
    verbose=True,
    showplot=False,
    saveplot=True,
)

Prescribing a profile

model = WindProfileClusteringModel()
model.load_configuration(Path("config/example/wind_clustering_settings.yml"))

model.prescribe_profile(
    outputPath=Path("results/example/wind_resource_prescribed.yml"),
    verbose=True,
    showplot=False,
    saveplot=True,
)