windkit.create_tswc#

windkit.create_tswc(output_locs, date_range=None, not_empty=True, seed=9876538, weibull_A=8.0, weibull_k=2.1, speed_tau=14400.0, direction_mean=240.0, direction_kappa=1.5, direction_tau=21600.0, spatial_correlation_length=10000.0, fields=None)[source]#

Create time series wind climate dataset.

When not_empty=True (default), the data variables are filled with temporally and spatially correlated synthetic wind data using an AR(1) process in Gaussian space transformed to a Weibull distribution for speed, and a circular AR(1) with von Mises innovations for direction.

Parameters:

  • output_locs (xarray.Dataset) – Output geospatial information.

  • date_range (pandas.DatetimeIndex or None) – Time range as a pandas DateTimeIndex. If None is passed, a default range of one year (2001) at 10 min resolution is created.

  • not_empty (bool) – If True, the empty dataset is filled with realistic synthetic wind data. Defaults to True.

  • seed (int) – Seed for the random data, defaults to 9876538.

  • weibull_A (float) – Weibull scale parameter [m/s]. Defaults to 8.0.

  • weibull_k (float) – Weibull shape parameter. Defaults to 2.1.

  • speed_tau (float) – Autocorrelation e-folding timescale for speed [s]. Defaults to 14400 (4 h).

  • direction_mean (float) – Prevailing wind direction [degrees]. Defaults to 240.

  • direction_kappa (float) – Von Mises concentration around prevailing direction. Defaults to 1.5.

  • direction_tau (float) – Autocorrelation timescale for direction [s]. Defaults to 21600 (6 h).

  • spatial_correlation_length (float) – Spatial e-folding length scale for inter-point correlation [same unit as coordinates]. Defaults to 10000.

  • fields (str, sequence of str or None) – Stability variables to add alongside the wind: "stability" or "all" for both temp_scale (\(T_*\)) and ustar_over_pblh (\(u_*/z_i\)), or a subset of those names. Defaults to None, which adds neither. The values are bounded by the 0.1st to 99.9th percentile of an onshore mesoscale reference and carry that reference’s correlations with each other and with the generated wind speed. Both are surface-layer scales, declared height_dim_policy: "forbidden", so they are drawn once per horizontal column - driven by the wind at its lowest height - and carry no height dimension, while the wind keeps its own. temp_scale follows the convention in which \(T_*\) has the sign of the surface heat flux, so positive is unstable and negative stable (https://doi.org/10.1007/s10546-023-00803-3).

Returns:

ds – Time series wind climate dataset.

Return type:

xarray.Dataset

Raises:

ValueError – If fields names something other than a stability variable, or if the time range spans 2 days or less, which is too short to generate correlated stability variables.

Notes

wind_speed and wind_direction are stored float32, C-contiguous, with time trailing the full spatial batch; the surface-layer scales are stored the same way over the horizontal batch. That is the reverse of the compiled core’s declared argument order, so PyWAsP’s compiled boundary can take a Fortran-ordered view instead of converting a copy (windkit#807). Coordinates stay float64: the core declares the location arguments of predict_*_points double precision, and float32 spacing at 5e5 m is 0.031 m. Neither the dtype nor the dimension order is a supported API contract: create_tswc is a test-data utility.

Examples

Create a single-point TSWC with default parameters:

>>> import pandas as pd
>>> from windkit.spatial import create_dataset
>>> import windkit as wk
>>> locs = create_dataset(10.0, 55.0, 100.0, 4326).drop_vars("output")
>>> dates = pd.date_range("2020-01-01", periods=8760, freq="h")
>>> tswc = wk.create_tswc(locs, date_range=dates)
>>> tswc
<xarray.Dataset> ...

Create a multi-point TSWC with custom Weibull parameters:

>>> import numpy as np
>>> locs = create_dataset(
...     [10.0, 10.1], [55.0, 55.1], [100.0, 100.0],
...     4326, struct="point",
... ).drop_vars("output")
>>> tswc = wk.create_tswc(locs, date_range=dates, weibull_A=9.5, weibull_k=2.3)

Create an empty TSWC (NaN-filled):

>>> tswc_empty = wk.create_tswc(locs, date_range=dates, not_empty=False)
>>> np.all(np.isnan(tswc_empty["wind_speed"].values))
True

Create a TSWC carrying the stability variables:

>>> tswc = wk.create_tswc(locs, date_range=dates, fields="stability")
>>> sorted(tswc.data_vars)
['temp_scale', 'ustar_over_pblh', 'wind_direction', 'wind_speed']
On this page