AixWeather

A weather data generation tool for building energy system simulations. Pull, Transform, Export.

AixWeather is a streamlined tool which will help you to generate weather data for building energy system simulations. The user can choose a data source and an output format, and the tool will take care of the rest. Read below to find out what input sources and output formats are currently supported. This tool is not designed as a library but as a standalone tool for generating weather data files.

It is being developed at RWTH Aachen University, E.ON Energy Research Center, Institute for Energy Efficient Buildings and Indoor Climate (EBC) in Aachen, Germany.

As the library is developed at RWTH Aachen University's EBC, the library's name AixWeather is derived from the city's French name Aix-la-Chapelle, which the people of Aachen are very fond of and use a lot. With the name AixWeather we follow this local tradition.

If you have any questions regarding AixWeather, feel free to contact us at ebc-tools@eonerc.rwth-aachen.de.

Available at PyPI as AixWeather.

WebApp

For fast access without setup, use the AixWeather-WebApp. The AixWeather-WebApp-Repository contains the corresponding WebApp for AixWeather. This repository here contains the functionalities useful for, e.g., automation of tasks.

How to use AixWeather locally

Simply install via:

pip install AixWeather

Or, by cloning the repository:

git clone https://github.com/RWTH-EBC/AixWeather.git AixWeather cd AixWeather pip install -e .

Then go to the example and follow the descriptions. This example contains the streamlined process exemplary shown for pulling DWD historical data and exporting it to all available output formats. Use generic functions to execute the streamlined process to create the desired output file. You may then either run this example file as a standalone and just transfer the output files to your simulation environment or if the weather data shall be generated by means of your own script, just copy the same executive functions to your script. For each data origin, a class is defined. Choose the class according to the desired weather data origin. For background knowledge, check the below tool structure and overview.

Tool structure and overview

AixWeather is a tool for generating weather data for building energy system simulations. It retrieves, formats, enriches, and ultimately exports weather data in various file formats.

This tool consists of three layers that are executed as a pipeline for each run:

1. Import raw weather data from several sources

2. Transform the weather data to a defined core format with consideration of:

   2.1. Time zone

   2.2. Time of measurement (whether a value at a certain time stamp is for the indicated time or, e.g., the average of the preceding hour)

   2.3. Avoidance of smoothing through interpolation (pass through variables without interpolation if possible)

   2.4. Units

   2.5. Calculate missing variables from available ones, e.g., horizontal direct radiation from diffuse and global radiation

   2.6. Missing data.

3. Transform the core-format data to your desired output format

Which transformations are executed, i.e. required, will always depend on the input data and the desired output format. The current set of implemented transformation functions can be found in aixweather/transformation_functions, e.g. the unit conversions or the functions to calculate missing values: variable transformation. Though, these function do not need be called explicitly, as they are called by the tool automatically based on the input data and the desired output format. Only if you plan to extend AixWeather by adding a new input or output format, you will need to specify which transformations are required specifically for your new format. The community will be happy to have such developments contributed back to the main repository.

Overview

The below diagram shows the tool's structure and the data flow from the import to the output format. It also shows what kind of input and output formats are currently supported. Every input is first transformed to the core format, which is then transformed to the desired output format. This allows for a clear separation of concerns and a modular structure that is easy to extend.

Known limitations:

• only hourly data

Chances:

• generic code base that allows for fast and easy extensions to both other import formats and output formats

DWD station IDs and DWD MOSMIX station IDs

The station IDs for the DWD weather stations to pull historical data from are listed here. Only german stations available. Aachen would be 15000.

The DWD MOSMIX station IDs for the DWD forecast are listed here or located on a map here. Worldwide station available. Aachen would be 10505.

You may use the imported package Wetterdienst to search for stations automatically, as described here.

Sources of information for corresponding data formats

Input

Test Reference Years (TRY):

Handbuch.

TRY data can be downloaded from the DWD (sign up required but for free) TRY data sets.

Additional information on the suitability of TRY data (last update: 2019): There are typical TRY datasets grouped by the year of publication: - 2004 datasets: (DWD; some errors in solar radiation; dataset should be avoided). - 2010 datasets: suitable for EnEV and GEG, not for solar thermal simulations. - 2015 datasets: not suitable for EnEV and GEG, but for solar thermal simulations - Overall: Reliable quantities in TRYs are only the air temperature and the global radiation!

DWD historical: open data website

DWD forecasts (MOSMIX i.e. KML files): open data website go to content.log.bz2.

EnergyPlus (EPW):

For format information, see the corresponding output format description.

Online sources for EPW data: https://climate.onebuilding.org/default.html and https://www.ladybug.tools/epwmap/

ERC data:

This data is from the weather station of the Institute for Energy Efficient Buildings and Indoor Climate (RWTH). Access requires user credentials. Such credentials are pre-defined if you use the WebApp.

Output formats

EnergyPlus (EPW):

3rd party format description

Modelica ReaderTMY3:

TMY3 reader from the IBPSA library used in the AixLib library. Model info at OpenModelica. It claims to use mainly TMY3 data, though we found that the pressure is used in mbar instead of Pa. Further deviations possible.

Additional information for AixLib users.

Weather data usage in the low order model (LOM):

Used in LOM: - TDryBul - RelHum - TBlaSky (calculated via HInfHor, TDryBul, TDewPoi, and OpaSkyCov) - HGloHor - HDifHor - HDirNor

Not used in the LOM: - total sky cover - ceiling height - wind direction - wind speed - atmospheric pressure

Unconverted to x

exports the core data without conversion to .csv, .json, or .pickle files.

How to contribute to the development

You are invited to contribute to the development of this weather tool. Issues can be reported using this site's Issues section. Furthermore, you are welcome to contribute via Pull Requests. More info on how to contribute can be found here.

How to cite

If you are using weather files created by AixWeather in your research, please cite the corresponding JOSS paper:

@article{Rtz2025, doi = {10.21105/joss.07344}, url = {https://doi.org/10.21105/joss.07344}, year = {2025}, publisher = {The Open Journal}, volume = {10}, number = {107}, pages = {7344}, author = {Martin Rtz and Fabian Wllhorst and Rita Streblow and Dirk Mller}, title = {AixWeather: A Weather Data Generation Tool for Building Energy System Simulations. Pull, Transform, Export.}, journal = {Journal of Open Source Software} } }

License

The weather tool is released by RWTH Aachen University, E.ON Energy Research Center, Institute for Energy Efficient Buildings and Indoor Climate and is available under a 3-clause BSD license. See license.