WAsP File Formats#

windkit provides low-level readers and writers for various WAsP file formats. These functions return dictionaries with numpy arrays, giving you direct access to the data without xarray overhead.

Low-Level vs High-Level APIs#

windkit provides two ways to work with WAsP files:

High-level APIs (e.g., read_bwc(), read_gwc()) return xarray.Dataset objects with full metadata and coordinate handling. Use these for standard workflows.

Low-level APIs in windkit.io.wasp return dictionaries with numpy arrays. Use these when:

  • You need minimal dependencies or overhead

  • You want direct array access for custom processing

  • You’re building pipelines that don’t need xarray

Example comparison:

# High-level: returns xarray.Dataset with validation and metadata
import windkit as wk
bwc = wk.read_bwc("wind_climate.tab")
print(type(bwc))  # <class 'xarray.core.dataset.Dataset'>

# Low-level: returns dict with numpy arrays
from windkit.io.wasp import read_tab
data = read_tab("wind_climate.tab")
print(type(data))           # <class 'dict'>
print(data["wsfreq"].shape) # (n_wsbins, n_sectors) - raw numpy array
print(data["coords"])       # {'south_north': ..., 'west_east': ..., 'height': ...}

Quick Start#

from windkit.io.wasp import read_tab, read_owc, read_lib, read_gwc, read_wtg

# Read binned wind climate (.tab)
tab_data = read_tab("wind_data.tab")
print(tab_data["wsfreq"].shape)

# Read observed wind climate (.owc / .omwc)
owc_data = read_owc("observed.omwc")
print(owc_data["wsfreq"].shape)

# Read generalized wind climate (.lib)
lib_data = read_lib("climate.lib")
print(lib_data["A"].shape)  # (n_sectors, n_heights, n_roughnesses)

# Read generalized wind climate (.gwc)
gwc_data = read_gwc("climate.gwc")
print(gwc_data["wdfreq"].shape)  # (n_sectors, n_heights, n_roughnesses)

# Read wind turbine generator (.wtg)
wtg_data = read_wtg("turbine.wtg")
print(len(wtg_data["modes"]))  # one entry per performance table

# Read vector map (.map)
from windkit.io.wasp import read_map
map_data = read_map("site.map")
print(len(map_data["points"]))  # one (n_pts, 2) array per line

# Read resource grid (.rsf / .wrg)
from windkit.io.wasp import read_rsf
rsf_data = read_rsf("resource.wrg")
print(rsf_data["A"].shape)  # (n_points, n_sectors)

# Read a whole WAsP session, inputs and results (.wwh)
from windkit.io.wasp import read_wwh
workspace = read_wwh("site.wwh")
print(workspace["members"])  # one entry per object in the workspace

Return Value Structure#

All read functions return dictionaries holding format-specific data as numpy arrays.

Formats that describe a location — .tab, .lib, .gwc, .owc / .omwc — additionally return:

  • coords: dict with south_north, west_east, height (wind climate formats)

  • metadata: dict with format-specific metadata (e.g., description)

Formats that describe many sites at once — .rsf / .wrg — return the same coords dict with one array entry per site instead of scalars.

A .wwh workspace holds many objects of different kinds, so read_wwh() returns a members list instead, one dict per object, each with its own coords where the object has a position. See Workspace Format (.wwh).

Formats that describe something else do not. A .wtg file, for example, describes a turbine rather than a place, so read_wtg() returns the turbine’s fields at the top level and a modes list of its performance tables. read_map likewise returns a header dict instead of coords and metadata, since a vector map has no single location. See Topography Formats.

The dicts mirror the file. Values are converted out of the units the format happens to store them in (.tab frequencies, for instance, are returned as fractions rather than per-mille), but nothing is interpolated, merged, or derived — that is the job of the high-level readers.

Encoding Detection#

Text formats support automatic encoding detection:

data = read_tab("file.tab")                    # Auto-detect encoding
data = read_tab("file.tab", encoding="utf-8")  # Explicit encoding

Documentation Contents#

See Also#