windkit.create_surface_fields#

windkit.create_surface_fields(output_locs, date_range=None, not_empty=True, seed=9876538, ranges=None, elevation_range=(0.0, 200.0), fields=None, **tswc_kwargs)[source]#

Create synthetic mesoscale surface fields as a time series.

Produces the raw model output variables from which the surface-layer temperature scale is derived, using the WRF naming convention, alongside the wind time series from create_tswc().

Time-varying variables: PSFC, T2, UST, HFX, LH, PBLH, Q2, ZNT, wind_speed, wind_direction. Time-constant variables: LANDMASK, elevation.

The stability variables these fields feed, temp_scale and ustar_over_pblh, are not part of the mesoscale set. They can be added with the fields argument, which is resolved exactly as create_tswc() resolves its own; asking for them here generates them together with the surface fields, in one correlated draw, so that a point holds the reference correlations between the two groups as well - the temp_scale/HFX pair among them.

Every point is over land: the values are drawn from an onshore reference, so LANDMASK is 1 everywhere and the fields carry no offshore behaviour. Code that has to exercise a land/sea contrast should set LANDMASK and the surface fields of the sea points itself.

These are all surface variables: every one of them declares height_dim_policy: "forbidden", so none carries a height dimension in the returned dataset, whatever the structure of output_locs. Each is drawn once per (west_east, south_north) column, so no two columns hold the same values — a fixture that repeated them could not detect code which loses track of which location a value belongs to. A column is identified by exact equality of its two coordinates, which holds for every structure windkit builds. wind_speed and wind_direction come from create_tswc() and keep their height dimension. Within a point the fields carry the cross-correlations of the reference site, including with wind_speed.

Parameters:

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

  • date_range (pandas.DatetimeIndex or None) – Time range. If None, one month of 2001 at hourly resolution is used, which is small enough to stay a cheap fixture. It must span more than two days, whatever its resolution.

  • not_empty (bool) – If True, the surface fields are filled with synthetic data. If False, every variable is NaN, as create_tswc() does. Defaults to True.

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

  • ranges (dict or None) – Overrides for the (low, high) bounds of individual surface fields. Keys not given fall back to the module defaults, and keys outside the surface fields are rejected - the stability variables are bounded by fields instead. Each entry must have low < high; neither the ordering nor the width of a pair is checked, so a reversed pair flips the field about its mid-range and an equal pair makes it constant.

  • elevation_range (tuple of float) – Bounds of the terrain elevation [m], with low < high. Defaults to (0.0, 200.0).

  • fields (str, sequence of str or None) – Stability variables to generate alongside the surface fields, as in create_tswc(): None for none of them, "stability" or "all" for every one, or the names to generate. Unlike passing them to create_tswc() separately, these are drawn together with the surface fields, so the two groups are correlated with each other.

  • **tswc_kwargs – Further keyword arguments passed to create_tswc().

Returns:

ds – Time series of mesoscale surface fields.

Return type:

xarray.Dataset

Raises:

ValueError – If ranges holds a key that is not a surface field, if fields names something that is not a stability variable, or if date_range holds too few time steps or spans two days or less.

Notes

Every variable added here is a surface variable, so all of them are stored over the horizontal batch, never a separate height axis: float32, C-contiguous, with time trailing that batch, the reverse of the compiled core’s declared argument order (windkit#807). The wind comes from create_tswc() and is stored as that function documents. Coordinates stay float64. Neither the dtype nor the dimension order is a supported API contract: create_surface_fields is a test-data utility.

Examples

>>> import pandas as pd
>>> import windkit as wk
>>> locs = wk.spatial.create_dataset(
...     [10.0, 10.1], [55.0, 55.1], [100.0, 100.0], 4326, struct="point"
... ).drop_vars("output")
>>> ds = wk.create_surface_fields(locs)
>>> "PBLH" in ds and "LANDMASK" in ds
True
>>> ds.sizes["time"]
744