ETHOS.RESKit - Renewable Energy Simulation Toolkit

Broad-scale renewable energy simulation for energy system models — millions of individual units in minutes.

📖 Read the full documentation at ethos-reskit.readthedocs.io.

ETHOS.RESKit aids with the broad-scale simulation of renewable energy systems, primarily for the purpose of input generation to Energy System Design Models. Simulation tools currently exist for onshore and offshore wind turbines, as well as for solar photovoltaic (PV) systems and concentrated solar power (CSP), in addition to general weather-data manipulation tools. Simulations are performed in the context of singular units, however high computational performance is nevertheless maintained. As a result, this tool allows for the simulation of millions of individual turbines and PV/CSP systems in a matter of minutes depending on the hardware.

ETHOS.RESKit is part of the Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2. It builds on ETHOS.GeoKit for its geospatial operations, and the time series it simulates are a common input to energy system models such as ETHOS.FINE.

Features

• High performance unit-level wind turbine, PV module and CSP simulations
• Can generate synthetic wind turbine power curves
• Access to all PV modules in the most recent databases from Sandia and the California Energy Commission (CEC)
• Configurable to make use of different climate model datasets
• Allows correction to real national capacity factor averages
• Flexible & modular function designs

Installation

For Users (Application Only)

1 a) If you do not have an existing conda/mamba environment:

conda env create -c conda-forge reskit -n <ENVIRONMENT-NAME>

1 b) If you have an existing environment, install ETHOS.RESKit into it:

conda install -c conda-forge reskit -n <YOUR-ENVIRONMENT-NAME>

2 ) Activate the environment:

conda activate <YOUR-ENVIRONMENT-NAME>

3 a) Get the ETHOS.RESKit source code (including examples):

git clone https://github.com/FZJ-IEK3-VSA/reskit.git
cd reskit

3 b) If you do not have Git and just want to check the examples, download and extract the source code with this link:

https://github.com/FZJ-IEK3-VSA/RESKit/archive/refs/heads/dev.zip

For Developers

Please follow these steps for an editable installation:

1 ) Clone and checkout dev:

git clone https://github.com/FZJ-IEK3-VSA/reskit.git
cd reskit
git checkout dev

2 a) ETHOS.RESKit should be installable to a new environment with:

conda env create --file requirements.yml

2 b) (Alternative) Or into an existing environment with:

conda env update --file requirements.yml -n <ENVIRONMENT-NAME>

3 ) Install an editable version of reskit (when in the reskit folder) via

pip install -e .

Getting Started

You can use ERA5 Data from Zarr or netcdf4

Reading ERA5 from Zarr

ETHOS.RESKit workflows are driven by gridded weather data. ERA5 is read directly from regular latitude/longitude Zarr stores with the existing source_type="ERA5" workflow API. The current implementation is intended for stores such as the Earth Data Hub ERA5 single-level dataset:

Earth Data Hub requires authentication. Follow the credential instructions on the linked dataset page and save the generated credentials as ~/.netrc (not in a directory on PATH). On shared systems, restrict access with chmod 600 ~/.netrc. The HTTPS backend will use those credentials automatically.

from reskit.wind.workflows.wind_workflow_manager import WindWorkflowManager
wf = WindWorkflowManager(placements)
 
wf.read(
    variables=["surface_pressure", "surface_air_temperature", "elevated_wind_speed"],
    source_type="ERA5",
    source="https://data.earthdatahub.destine.eu/era5/reanalysis-era5-single-levels-v0.zarr",
    chunks={"valid_time": 48},
    time_slice=slice("2020-01-01", "2020-01-31 23:00:00"),
    set_time_index=True,
)

Current limitations:

• The implementation only supports regular (time|valid_time, latitude, longitude) Zarr layouts, not flattened values-based ERA5 archives.
• If the Zarr store does not ship ETHOS.RESKit's processed ssrd_t_adj and fdir_t_adj fields, global_horizontal_irradiance and direct_horizontal_irradiance fall back to processing the raw ssrd and fdir on the fly.

The example notebook 3_8_use_workflows_with_zarr.ipynb runs the ETHOS.RESKit.Wind workflow on the Earth Data Hub store.

Preparing netcdf4 Weather Data

ETHOS.RESKit workflows are driven by gridded weather data. ETHOS.RESKit ships a single high-level helper, rk.download_and_process, that downloads exactly the variables a given workflow needs from the relevant data provider, preprocesses them (e.g. wind speed from u/v components, solar unit and time-shift corrections), and optionally tiles them into the <zoom>/<x>/<y>/<year>/ directory structure expected by the weather sources.

ERA5 reanalysis from the Copernicus Climate Data Store (CDS) is currently the supported source; additional weather data sources are planned.

import reskit as rk

result = rk.download_and_process(
    workflows="wind_era5_PenaSanchezDunkelWinklerEtAl2025",
    start_date="2000-01-01",
    end_date="2000-12-31",
    boundary_box={"north": 55, "south": 47, "west": 6, "east": 15},  # Germany
    output_dir="/path/to/your/weather_data",
    tiling=True,
)
print(result["era5_path"])

To prepare data for several workflows in a single call, pass a list of workflow names as workflows; the union of their variable requirements is downloaded and processed at once, e.g. workflows=["openfield_pv_era5", "CSP_PTR_ERA5"]. A CDS account with a configured ~/.cdsapirc API key is required for ERA5 (see https://cds.climate.copernicus.eu/how-to-api).

Note that some workflows also rely on data whose automated download is not yet implemented — solar/CSP workflows on Global Solar Atlas rasters and wind workflows on Global Wind Atlas rasters. download_and_process prints a notice for these and you must supply the rasters manually.

Input data from the ETHOS.Data catalogue

RESKit names each workflow's input collection after the workflow in reskit/data/collections.yaml. Call reskit.data.paths() immediately before the workflow: it makes the inputs available locally and returns {handle: local path}. No shell command is required. test=True selects the small bundled test fixtures:

from reskit import data

inputs = data.paths("wind_era5_PenaSanchezDunkelWinklerEtAl2025", test=True)
result = rk.wind.wind_era5_PenaSanchezDunkelWinklerEtAl2025(
    placements=placements,
    era5_path=inputs["era5"],
    gwa_100m_path=inputs["gwa_100m"],
    height_scaling_data={50: inputs["gwa_50m"], 200: inputs["gwa_200m"]},
)

For optional shell access, reskit-data fetch wind_era5_PenaSanchezDunkelWinklerEtAl2025 --test --paths prints one handle<TAB>path line per input, reskit-data show lists every collection, and reskit-data --help every command.

Both variants use the same input handles. The full variant is selected when test=True is omitted, but no catalogue holds a full ERA5 dataset yet, so removing test=True alone raises UnknownDataset. A workflow whose full inputs are not catalogued at all has a test variant only.

The reskit-test-data fixtures ship with RESKit as a verified ETHOS.Data bundle in reskit/data/test_cache, so test=True, the examples and the test suite read them offline, without reading any catalogue. Set ETHOS_DATA_DOWNLOAD=1 to read them through the catalogue's store and the shared cache instead.

Install ETHOS.Data in the same environment. In a development checkout, reinstall RESKit with pip install -e . --no-deps to register its console script. reskit-data show prints the actual catalogue selection; RESKIT_DATA_CATALOG overrides it for RESKit, while shared ETHOS settings apply to all packages.

Use reskit-data staging add/list/remove for unpublished development inputs. The input-data guide covers catalogue selection, workflow arguments, staging and verification, with links to the shared configuration and bundle procedures. Cache and catalogue administration use ethos-data.

Simulating a shorter period

By default a workflow simulates every time step of its weather data. Pass time_slice to simulate only part of it; both bounds are inclusive, and only the selected time steps are read from the weather source, which saves reading and simulation time:

rk.wind.wind_era5_PenaSanchezDunkelWinklerEtAl2025(
    ...,
    time_slice=slice("2015-03-01", "2015-03-31 23:30"),
)

All workflows which read weather data accept time_slice, for every weather source (ERA5 as netCDF4 or Zarr, MERRA, SARAH and ICON-LAM). The bounds refer to the time index of the workflow result, e.g. ERA5 time steps lie at half past the hour.

Reading ERA5 from Zarr

ETHOS.RESKit can read ERA5 directly from regular latitude/longitude Zarr stores while keeping the existing source_type="ERA5" workflow API. The current implementation is intended for stores such as the Earth Data Hub ERA5 single-level dataset:

Earth Data Hub requires authentication. Follow the credential instructions on the linked dataset page and save the generated credentials as ~/.netrc (not in a directory on PATH). On shared systems, restrict access with chmod 600 ~/.netrc. The HTTPS backend will use those credentials automatically.

wf.read(
    variables=["surface_pressure", "surface_air_temperature", "elevated_wind_speed"],
    source_type="ERA5",
    source="https://data.earthdatahub.destine.eu/era5/reanalysis-era5-single-levels-v0.zarr",
    chunks={"valid_time": 48},
    time_slice=slice("2020-01-01", "2020-01-31 23:00:00"),
    set_time_index=True,
)

Current limitations:

• The implementation only supports regular (time|valid_time, latitude, longitude) Zarr layouts, not flattened values-based ERA5 archives.
• If the Zarr store does not ship ETHOS.RESKit's processed ssrd_t_adj and fdir_t_adj fields, global_horizontal_irradiance and direct_horizontal_irradiance fall back to processing the raw ssrd and fdir on the fly.

Provenance of results

Every result of a workflow records how it was made, in the dataset attributes, so it is kept in the netCDF file as well: the RESKit version and git commit, the workflow and its arguments, the versions of the main dependencies, the weather sources with variables and time span, and every input and correction file with size, modification time and SHA-256 (up to 64 MiB). Values netCDF cannot store as attributes are JSON strings; read_provenance decodes them:

from reskit.util.provenance import read_provenance

result = rk.wind.wind_era5_PenaSanchezDunkelWinklerEtAl2025(placements, **inputs)
provenance = read_provenance(result)
provenance["workflow"], provenance["git_commit"], provenance["input_files"]

Custom workflows get the same by decorating the function with reskit.util.provenance.record_provenance; files read outside WorkflowManager.read can be added with wf.record_input_file(role, path).

Example notebooks

End-to-end examples live in examples/1_load_input_data/:

• 1_1_3_prepare_era5_for_wind_workflow.ipynb
• 1_1_4_prepare_era5_for_solar_workflow.ipynb

For full manual control over the raw ERA5/CDS download (variables, area, and timeframe), see the lower-level example notebook 1_1_1_how_to_download_era5_data.ipynb.

Citation

If you decide to use ETHOS.RESKit anywhere in a published work related to wind energy, please kindly cite us using the following publications.

When using the ETHOS.RESKit.Wind workflow please cite:

@article{PenaSanchezDunkelWinklerEtAl2026,
  title = {Towards High Resolution, Validated and Open Global Wind Power Assessments},
  author = {{Pe{\~n}a-S{\'a}nchez}, E. U. and Dunkel, P. and Winkler, C. and Heinrichs, H. and Prinz, F. and Weinand, J. M. and Maier, R. and Dickler, S. and Chen, S. and Gruber, K. and Kl{\"u}tz, T. and Lin{\ss}en, J. and Stolten, D.},
  year = 2026,
  month = jan,
  journal = {Nature Communications},
  volume = {17},
  number = {1},
  pages = {539},
  issn = {2041-1723},
  doi = {10.1038/s41467-026-68337-z},
  url = {http://dx.doi.org/10.1038/s41467-026-68337-z},
}

When using anything else:

@article{RybergWind2019,
  author = {Ryberg, David Severin and Caglayan, Dilara Gulcin and Schmitt, Sabrina and Lin{\ss}en, Jochen and Stolten, Detlef and Robinius, Martin},
  doi = {10.1016/j.energy.2019.06.052},
  issn = {03605442},
  journal = {Energy},
  month = {sep},
  pages = {1222--1238},
  title = {{The future of European onshore wind energy potential: Detailed distribution and simulation of advanced turbine designs}},
  url = {https://linkinghub.elsevier.com/retrieve/pii/S0360544219311818},
  volume = {182},
  year = {2019}
}

Contributions and Support

All contributions are welcome:

• If you want to report a bug, please open an Issue. We will then take care of the issue as soon as possible.
• If you want to contribute with additional features or code improvements, open a Pull request.

License

The source code in this repository is licensed under: MIT License Copyright (c) 2019-2025 FZJ-ICE-2

The data files cf_correction_factors_PSDW2025.tif and ws_correction_factors_PSDW2025.yaml are licensed under CC-BY-4.0

You should have received a copy of the MIT License along with this program.
If not, see https://opensource.org/licenses/MIT

About Us

We are the Institute of Climate and Energy Systems – Jülich Systems Analysis (ICE-2) at the Forschungszentrum Jülich. Our work focuses on independent, interdisciplinary research in energy, bioeconomy, infrastructure, and sustainability. We support a just, greenhouse gas–neutral transformation through open models and policy-relevant science.

Code of Conduct

Please respect our code of conduct.

Acknowledgments

This work was initially supported by the Helmholtz Association under the Joint Initiative "Energy System 2050 A Contribution of the Research Field Energy".