Release Notes

Changelog

All major changes are listed here.

1.0.0 (2025-06-20) docs

PyWAsP 1.0.0 is a major release that introduces a significant number of new features, improvements, and breaking changes aimed at improving the user experience, consistency, and performance. The API has been cleaned up, and many functions have been renamed for clarity. This version also introduces a new configuration system and enhanced energy yield calculation capabilities.

Dependency updates for 1.0

• Supports Python 3.11 to 3.13

• Supports numpy 1.26 to 2.2 (1.0 will be last version to support numpy 1)

• Supports PyWake 2.6

• Supports windkit 1.0

Code restructuring and API cleanup

• Updated user config: The user configuration has migrated from pywasp.cfg to a pydantic-based settings system. Users must create a pywasp_config.toml file or a .env file, or define environment variables. See the User Configuration documentation for details. A helper function pywasp.user_config.create_config_interactively() can be used to create a new configuration file interactively.

• API Renaming and Cleanup:

  • The pywasp.config module is renamed to pywasp.user_config.

  • pywasp.wasp.bwc_from_timeseries is renamed to pywasp.wasp.bwc_from_tswc.

  • pywasp.io.rastermap_to_vectormap is renamed to pywasp.io.raster_to_vector.

  • pywasp.io.vectormap_to_rastermap is renamed to pywasp.io.vector_to_raster.

• Argument Renaming for Consistency:

  • The return_site_factors argument is renamed to return_site_effects in all downscale, predict, and generalize functions.

  • Arguments for the number of wind speed bins (e.g., nwsbins, n_bins) are standardized to n_wsbins.

  • Arguments for the number of sectors (e.g., nsec, nwd) are standardized to n_sectors.

  • The ws_bin_width argument is renamed to wsbin_width.

  • In pywasp.wasp.gross_aep, interpolate is renamed to air_density_correction, and air_density is renamed to reference_air_density.

  • In pywasp.io.vector_to_raster, arguments xmin, ymin, xmax, ymax are replaced by a single bounds tuple.

• Removed Functionality:

  • The following functions and classes have been removed from the public API: pywasp.io.rastermap_to_waspformat, pywasp.io.vectormap_to_waspformat, pywasp.wasp.wtg_to_pywake, pywasp.lincom.grid_from_wasp_rastermap, pywasp.io.WaspVectorMap, and pywasp.io.WaspRasterMap.

• Air density correction:

  • In pywasp.wasp.gross_aep, pywasp.wasp.potential_aep, a new air_density_correction argument was added, which defaults to "infer", which tries to infer the best air density correction method based on the WTG’s control system.

  • pywasp.io.raster_to_vector now returns polygons instead of change lines for roughness or landcover maps.

  • Landcover tables are no longer required for pywasp.io.raster_to_vector and pywasp.io.vector_to_raster.

• Metadata Changes:

  • The _AEP suffix in metadata attributes from AEP functions is now lowercase (_aep).

  • The metadata variable aep_deficit is renamed to potential_aep_deficit.

New features

New energy yield calculation functions

• New function pywasp.wasp.net_aep to calculate the Net Annual Energy Production (AEP) by applying losses from a loss table.

• New function pywasp.wasp.estimate_sensitivity_factor to estimate the sensitivity factor of a wind effect to AEP.

• New function pywasp.wasp.px_aep to calculate the AEP level reached with a given probability.

Landcover and I/O

• New function pywasp.landcover.convert_to_classes that adds new classes to a landcover raster map using tree heights and leaf area indices.

• New function pywasp.io.polygons_to_lines that converts polygons to lines, approximately 100x faster than the windkit equivalent.

• pywasp.wasp.TopographyMap now accepts GeoDataFrames with Polygons.

Full list of changes

• New function pywasp.landcover.convert_to_classes that adds new classes to a landcover raster map using tree heights and leaf area indices raster maps.

• New keyword arugment offset in bwc_resample_sectors that allows rotating a histogram with a specified number of degrees

• Bug fix in interpolate_gwc: variables “m1”, “m3”, “fgtm” were not always removed. They are private variables that should never be visible to the user.

• get_air_density can now deal with larger than RAM memory dataset as input. The custom dataset can also be in any projection, whereas before it assumed it was always in latlon

• Bug fix in get_climate, did not work when bbox crosses dateline”

• New function polygons_to_lines, that convert polygons to lines similar to the function windkit.poly_to_lines but approximately 100x times faster.

• In interpolate_gwc for interpolation of single point to many using keyword engine=”windkit”, could give wrong results when the output structure was not of the same spatial structure as the input spatial structure.

• PyWake is pinned to version 2.6.8 (commit 5562afda7f272ab029bf057617557c5de14416e5).

• New functionality available, potential_aep and wind_farm_flow_map functions can now correct for site-specific air density conditions.

• In gross_aep, potential_aep and wind_farm_flow_map, the argument air_density_correction is set to True by default.

• potential_aep can now take different types of WTGs within the same wind farm group. Following the same structure as gross_aep.

• TopographyMap now allows input of Polygon dataframes, two extra keyword arguments check_errors and external_roughness determine the behaviour when dealing with these maps. The external roughness length specifies the roughness outside the polygons in the provided map.

Breaking changes

• renamed pw.wasp.bwc_from_timeseries to pw.wasp.bwc_from_tswc

• renamed pw.rastermap_to_vectormap to pw.raster_to_vector

• renamed pw.vectormap_to_rastermap to pw.vector_to_raster.

• removed pw.rastermap_to_waspformat from public namespace

• removed pw.vectormap_to_waspformat from public namespace

• removed pw.WaspVectorMap from public namespace

• removed pw.WaspRasterMap from public namespace

• removed pw.lincom.grid_from_wasp_rastermap from public namespace

• Argument return_site_factors has been renamed to return_site_effects in the following functions:

  • downscale

  • downscale_from_site_effects

  • downscale_from_geostrophic_and_site_effects_to_bwc

  • downscale_from_geostrophic_and_site_effects_to_wwc

  • predict_bwc

  • predict_bwc_from_site_effects

  • predict_wwc

  • predict_wwc_from_site_effects

  • generalize_from_site_effects_to_geowc

  • generalize

• Argument nwsbins, nws, n_bins has been renamed to n_wsbins in the following functions:

  • bwc_from_tswc

  • stability_histogram

  • create_histogram_z0

• Argument nsec, nsecs, nwd, nbins has been renamed to n_sectors in the following functions:

  • bwc_from_tswc

  • stability_histogram

  • create_histogram_z0

  • get_elev_rose

  • get_rou_rose

  • get_site_effects

  • get_site_effects_cfd

  • weibull_fit

  • generalize

  • predict_wwc

  • predict_bwc

• Argument ws_bin_widthhas been renamed to wsbin_width in the following functions:

  • bwc_from_tswc

  • stability_histogram

  • create_histogram_z0

• Argument interpolate in gross_aep has been renamed to air-density_correction, air_density has been renamed to reference_air_density.

• _AEP suffix in attribute names of the metadata from pywasp.wasp.aep, pywasp.wasp.aep_losses.py, pywasp.wasp.aep_uncertainty.py have been changed to _aep

• Metadata variable name aep_deficit has been renamed to potential_aep_deficit

• No longer require landcover tables for raster_to_vector and vector_to_raster

• Replaced arguments xmin,ymin,xmax,ymax in vector_to_raster to bounds (tuple or BBox of same values)

• raster_to_vector now returns polygons instead of change lines when the input is a roughness or landcover map.

• Renamed pywasp.config to pywasp.user_config to avoid confusion with the pywasp.wasp.Config class.

• The “Roaming” AppData dir is now used on Windows. By default the config and app data files are stored in "C:\\Users\\<user_name>\\AppData\\Roaming\\DTU Wind Energy\\pywasp"

• Removed function pywasp.wasp.wtg_to_pywake (from public namespace)

• Replaced the gwc interpolation function in pw.wasp.downscale and pw.wasp.downscale_from_site_effects with the new wk.spatial_interpolate_gwc function.

  • This replaces the legacy gwc interpolaters in pywasp

  • With the update only “point” targets are supported for “natural” interpolation, while “nearest”, “linear”, and “cuboid” still works for all spatial structures.

  • Changed the interp_method default to “nearest” instead of “given”.

• PyWAsP user configuration has migrated to using pydantic settings. This means that your pywasp.cfg will no longer work. You will need to either create a pywasp_config.toml file, a dotenv file, or define environment variables with your configuration settings for PyWAsP to import successfully. You can find the necessary information in the PyWAsP License and User Configuration documentation.

New energy yield calculation functions:

• New function pywasp.wasp.net_aep to calculates the Net Annual Energy Production (AEP) by applying the losses from a loss table.

• New function pywasp.wasp.estimate_sensitivity_factor to estimate the sensitivity factor of wind effect to AEP for a given predictive wind climate and wtg.

• New function pywasp.wasp.px_aep to calculate the Annual Energy Production (AEP) level reached with a given probability.

0.7.0 (2024-06-04) docs

PyWAsP 0.7.0 is a major release with new features, improvements, and bug fixes.

Dependency updates

• Following SPEC 0 this release supports python 3.10-3.12 and numpy 1.24-1.26.

• Windkit =0.8.0 is required

• PyWake is pinned to version 2.5.0 (commit 36da70b2335321e435194d277511c17d8f012571).

New features

New climate extrapolation functions

• New function pywasp.wasp.predict_wwc to predict a weibull wind climate from a binned wind climate without using a generalized wind climate lookup-table, thus reducing interpolation errors

• New function pywasp.wasp.predict_bwc, same as above but to predict a binned wind climate instead.

• New function pywasp.wasp.predict_wwc_from_site_effects, same as pywasp.wasp.predict_wwc but using the outputs of calls to pywasp.wasp.TopographyMap.get_site_effects instead of a mapfile.

• New function pywasp.wasp.predict_bwc_from_site_effects, same as pywasp.wasp.predict_bwc but using the outputs of calls to pywasp.wasp.get_site_effects instead of a mapfile.

• New function pywasp.wasp.generalize_from_site_effects, same as pywasp.wasp.generalize but using the output of a call to pywasp.wasp.TopographyMap.get_site_effects instead of a mapfile.

• New function pywasp.wasp.generalize_from_site_effects_to_geowc, generalize a binned geostrophic wind climate from a site effects dataset.

• New function pywasp.wasp.downscale_from_geostrophic_and_site_effects_to_bwc, downscale a binned geostrophic wind climate from a site effects dataset and geostrophic binned wind climate

BWC resampling functions added

• New function pywasp.wasp.bwc_resample_like, to resample a binned wind climate using a different sector or wind speed bin structure.

• New function pywasp.wasp.bwc_resample_sectors, to resample a binned wind climate using a different number of sectors.

• New function pywasp.wasp.bwc_resample_wsbins_like, to resample a binned wind climate using a different wind speed bin structure.

I/O added to TopographyMap and new CFD data-extraction method

• New methods .save and .load added to pywasp.wasp.TopographyMap to save and load the topography map to/from a ZipFile Archieve.

• pywasp.wasp.get_site_effects_cfd also accepts a list of xr.datasets (read by the read_cfdres function in windkit) as input. It will extract the site effects in the order specified in the list.

Support for custom root CA certificates

• In case of running pywasp under a proxy or another similar network setup, the filepath to a root CA certificate can be set on pywasp so it can connect to the licensing server.

Improvements

• For typical usage pywasp.wasp.TopographyMap.get_site_effects is 2-6 times faster

• For typical usage pywasp.io.rastermap_to_vectormap is 15-30 times faster

• For typical usage pywasp.io.vectormap_to_rastermap is 15-30 times faster

• For typical usage pywasp.io.vectormap_to_waspformat is 2-20 times faster

• For typical usage pywasp.io.waspformat_to_vectormap is 2-80 times faster

• For typical usage pywasp.wasp.TopographyMap is >1000 times faster

• Improved input error checking in pywasp.wasp.generalize()

• Improved input error checking in pywasp.wasp.generalize(), check that the gen_roughnesses and gen_heights have at least 2 entries, as required by the WAsP core.

• Improved input error checking in pywasp.wasp.TopographyMap: make sure that all your landcover lines have a corresponding entry in the landcover table.

• More accurate setting of generalized heights and roughness using the function pywasp.wasp.set_hgts and pywasp.wasp.set_z0s. Now a percentile mapping technique is used when the number of heights or roughnesses exceeds the maximum number of entries allowed in a gwc (5).

• More descriptive error codes when having problems reading a pywasp config file.

• TopographyMap now throws an error when the lctable has more than 100 entries. Before this condition was unhandled and could crash the fortran.

• pywasp.wasp.Config object now is read only and does not do any modifications of the fortran behaviour itself (before it was creating lookup tables and setting some parameters on each update of conf.terrain.)

Deprecations

• WaspVectorMap will be deprecated

• windkit.WindTurbines deprecated for AEP functions. Use a dict of WTG xr.Dataset’s and a wind_turbine xr.Dataset instead.

Changes

• pywasp.wasp.generalize now uses pywasp.wasp.generalize_from_site_effects instead of duplicating code

• pywasp.wasp.interpolate_gwc -> Can now also interpolate geostrophic wind climates. Code from windkit has been implemented in pywasp and can be used by using the argument engine="windkit".

• pywasp.wasp.TopographyMap.get_site_effects now reports an extra variable flow_sep_height, which can report the height where flow separation is expected based on slopes exceeding some given slope. The flow_sep_height is only active when using conf.terrain[64] == 1.

• In all the downscale and generalize function an additional variable flow_sep_height can be used. This is added to the displacement height that is used for transformation of the wind climate. If this data array is not present on the site_effects dataset, it is added automatically.

• Using a point dataset with multiple heights now gives a warning instead of a ValueError, because it is typically used in combination with pywasp.wasp.interpolate_gwc and interp_method=”given” where it is fine to have more than one height.

Breaking changes

• pywasp.wasp.get_wasp_down renamed to pywasp.wasp.downscale_from_site_effects

• Changed order of arguments in pywasp.wasp.generalize_and_downscale to bwc, topo_map, output_locs for consistency with generalize and downscale

• pywasp.wasp.set_hgts -> returns slightly more accurate generalized roughnesses when height_from and height_to are provided

• pywasp.wasp.set_z0s -> returns slightly more accurate generalized roughnesses when z0meso_from and z0meso_to are provided

• pywasp.wasp.calc_temp_scale the output of the dataset now returns the correct name ustar_over_pblh

• pywasp.wasp.stability_histogram now produces a dataset with the more correct names mean_pblh_scale_land and mean_pblh_scale_sea instead of mean_pblh_land and mean_pblh_sea. See for more details: https://link.springer.com/article/10.1007/s10546-023-00803-3

• genwc_interp argument in downscale and generalize has been renamed to interp_method

• pywasp.wasp.gross_aep, pywasp.wasp.potential_aep, and pywasp.wasp.wind_farm_flow_map now uses a dict {"wtg_key1": wtg1, "wtg_key2": wtg2} and a turbines xarray.Dataset instead of a windkit.WindTurbines object. WTGs are mapped to turbines via the wtg_keys present in both the dict and the turbines dataset.

0.6.0 (2023-11-30)

Dependency updates

• Following SPEC 0 this release supports python 3.10-3.12 and numpy 1.22-1.26. Due to build issues with numpy 1.26, neither it nor python 3.12 are supported on Windows.

• Windkit =0.7.0 is required

• PyWake is now pinned to version 2.5.0 (commit 36da70b2335321e435194d277511c17d8f012571).

New features

Support for WAsP CFD results

• New function pywasp.wasp.get_site_effects_cfd interpolates the speedups and turnings from a windkit CFD volume xarray.Dataset.

• pywasp.wasp.generalize, pywasp.wasp.downscale, and pywasp.wasp.generalize_and_downscale now have an extra cfd_volume argument, which can be used to pass in WAsP CFD results that will be used for the site effects.

Breaking changes

• pywasp.wasp.wind_farm_flow_map now requires a wk.WindTurbines object, not separate wtg and locations arguments.

• pywasp.wasp.wind_farm_flow_map requires the new argument output_locs, which should be a “cuboid” xr.Dataset, which is where the flow map will be calculated. output_locs should be covered by the predicted wind climate object.

Changes

• Interpolation errors have been eliminated during the downscale step when using pywasp.wasp.generalize_and_downscale, by including the output heights in the generalize step.

• Update ERA5 mesoclimate netCDF file according to latest revision of Using Observed and Modelled Heat Fluxes for Improved Extrapolation of Wind Distributions.

• pywasp.wasp.gross_aep and pywasp.wasp.potential_aep can now accept a wk.WindTurbines object to the wtg argument. This allows for different WTGs to be used for different turbine locations.

• Added interp_method argument to pywasp.wasp.get_climate, “nearest” is used by default

Improvements

• Reduction of approximately 50% for calculations of wake-affected AEP.

Bug Fixes

• PyWAsP on windows now can use the license.windenergy.dtu.dk licensing server.

• Interpolation of mean_dgdz and mean_dgdz_dir are now carried out by interpolating the vector components, when a method other than "nearest" is used.

Deprecations

• Deprecated options “PARK2_onshore_with_blockage” and “PARK2_offshore_with_blockage” in pywasp.wasp.wind_farm_flow_map and pywasp.wasp.potential_aep. Use, custom PyWake wind_farm_models to build complex models instead.

0.5.2 (2023-06-21)

Changes

• Dependency updates: Python 3.8 & numpy 1.21 no longer supported following NEP 29. Windkit 0.6.3 is now required to support the regulation_type variable for wtg objects.

• pywasp.wasp.TopographyMap.get_rou_rose now allows to add displacements to the orographic grid, using the new elev_rose argument. If elev_rose is None, a dummy elevation rose is created.

• pywasp.wasp.interpolate_gwc now returns an interpolated generalized wind climate dataset with height coordinates.

• Setting download_prompt=False and download_global_nc_files in the pywasp.cfg file, will not prevent any text from showing when importing PyWAsP. Previously it would print a message about how to get the files on each import. If you need the files, you will be prompted to download at that time. See the User Configuration Documentation to see all options of the config file.

Improvements

• Update netCDF file with CFSR baroclinicity information. The data is the same but the data variable names are updated. It does not affect the behavior.

• pywasp.wasp.interpolate_gwc will issue a warning if it is used with datasets with geographical coordinates for “nearest” and “natural” methods.

Bug Fixes

• pywasp.io.rastermap_to_vectormap will only raises errors related with the parameter dz when the raster map type is elevation.

• pywasp.wasp.aep.gross_aep incorrectly assumed most wind turbines were stall regulated. This means that when using the interpolation=True option, that incorrect air density corrections were applied. This has been fixed by an update in WindKit that requires the control_system variable to be defined on a wind turbine generator. This value is now used to apply the correct air density correction to the power curves.

0.5.1 (2023-04-19)

New Features

• pywasp.wasp.get_climate_by_config takes a pywasp.wasp.Config object and returns an xarray.Dataset meso climate object compatible with the profile model set in the config.

Changes

• pywasp.wasp.get_climate arguments stab_source and baro_source now both allow for None to be set. This creates a dataset with 0-valued fields for the given source.

Improvements

• Update netCDF file with CFSR baroclinicity information to version 3. The data is the same, but the data variable names are updated. This does not affect the behavior.

Bug Fixes

• Fixed license check error for new version of DTU License server

• Corrected import of combine_bwcs in pywasp.wasp.cross_predict.

• pywasp.wasp.interpolate_gwc now returns an interpolated generalized wind climate dataset with height coordinates. This makes it more robust to different spatial structures of generalized wind climates and output_locs, when used for downscaling.

Deprecations

• getpar and setpar methods of pywasp.wasp.config.Config objects are deprecated. Use square brackets instead.