windIO: a community-focused data I/O format for wind energy systems#

windIO is a data format for inputs and outputs to wind energy system computational models. Historically, it has focused on systems engineering models, but it has been adopted in other topic areas of wind energy modeling, as well. The windIO data format is a community-focused effort to standardize the data format for wind energy system models, and we encourage collaboration. The github repository is at IEAWindSystems/windIO and the online documentation is at https://ieawindsystems.github.io/windIO.

This windIO repository including the following:

  • Schema defining windIO components describing wind turbines and wind plants

  • Python library for validating files relative to the schema and loading the data into a Python dictionary

  • windIO input files for test-case wind turbine and wind plant models

Reference wind turbines designed within the IEA Wind Systems Engineering Task are available at the following links:

If you use this model in your research or publications, please cite the DOI from Zenodo:

DOI: 10.5281/zenodo.15191297

Alternatively, you can cite this older IEA technical report:

@article{osti_1868328,

title = {System Modeling Frameworks for Wind Turbines and Plants: Review and Requirements Specifications}, author = {Bortolotti, Pietro and Bay, Christopher and Barter, Garrett and Gaertner, Evan and Dykes, Katherine and McWilliam, Michael and Friis-Moller, Mikkel and Molgaard Pedersen, Mads and Zahle, Frederik}, doi = {10.2172/1868328}, place = {United States}, year = {2022}, month = {5}}

Author: IEA Wind Task 37 and 55 Teams

Installation#

windIO is typically included as a dependency in software that uses the windIO data format, so users will normally not need to install it directly. However, it can be useful to install the windIO package to access version converters or during integration into a software package. In that case, windIO can be installed from PyPI with the following command:

pip install windIO

Supporting windIO in your software#

The windIO data format is defined by the schemas included in this repository. In order for a software to support windIO, it must support the data as described in the schemas and use the included functions to validate the data. windIO should be included as a dependency. It is distributed through PyPI and can be installed as a package with pip. The suggested method of incorporating windIO into your code is:

import windIO

# Other code here

windIO.validate(input="path/to/input.yaml", schema_type="plant/wind_energy_system <for example>")
windIO.load_yaml("path/to/input.yaml")

# Conversion to your software's data structures here

Software library reference#

windIO.load_yaml(filename: str | Path | PathLike, loader=None) → dict#

Opens filename and loads the content into a dictionary with the _get_YAML function from ruamel.yaml.YAML.

Parameters:

  • filename (str | Path | os.PathLike) – Path or file-handle to the local file to be loaded or string path to the file.

  • loader (ruamel.yaml.YAML, optional) – Defaults to SafeLoader.

Returns:

dict – Dictionary representation of the YAML file given in filename.

windIO.validate(input: dict | str | Path, schema_type: str, restrictive: bool = True, defaults: bool = False) → None#

Validates a given windIO input based on the selected schema type.

Parameters:

  • input (dict | str | Path) – Input data as a dictionary or a path to a YAML file containing the data to be validated.

  • schema_type (str) – Type of schema to be used for validation. This must correspond to one of the schema files available in the schemas/plant or schemas/turbine folders. Examples of valid schema types include ‘plant/wind_energy_system’ or ‘turbine/turbine_schema’.

  • restrictive (bool, optional) – If True, the schema will be modified to enforce that no additional properties are allowed. Defaults to True.

  • defaults (bool, optional) – If True, default values specified in the schema will be applied to the input data during validation. Defaults to False.

Raises:

  • FileNotFoundError – If the schema file corresponding to the schema type is not found.

  • TypeError – If the input type is not supported (must be dict, str, or Path-like).

  • jsonschema.exceptions.ValidationError – If the input data fails validation against the schema.

  • jsonschema.exceptions.SchemaError – If the schema itself is invalid.

Returns:

dict – The validated input data. If defaults is True, the returned data will include default values specified in the schema.

windIO.write_yaml(instance: dict, foutput: str) → None#

Writes a dictionary to a YAML file using the ruamel.yaml library.

Parameters:

  • instance (dict) – Dictionary to be written to the YAML file.

  • foutput (str) – Path to the output YAML file.

Returns:

None

Contents#