AixWeather 0.2.0
A weather data generation tool for building energy system simulations.Pull, Transform, Export.
License: BSD 3-Clause
Keywords: weather, BES, converter, simulation, building, energy

![E.ON EBC RWTH Aachen University](https://raw.githubusercontent.com/RWTH-EBC/AixWeather/main/docs/source/_static/EBC_Logo.png)

[![DOI](https://joss.theoj.org/papers/10.21105/joss.07344/status.svg)](https://doi.org/10.21105/joss.07344)
[![documentation](https://rwth-ebc.github.io/AixWeather//main//docs/doc.svg)](https://rwth-ebc.github.io/AixWeather//main//docs/index.html)
[![pylint](https://rwth-ebc.github.io/AixWeather//main//pylint/pylint.svg )](https://rwth-ebc.github.io/AixWeather//main//pylint/pylint.html)
[![coverage](https://rwth-ebc.github.io/AixWeather/main/coverage/badge.svg)](https://rwth-ebc.github.io/AixWeather/main/coverage)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

<div align="center">
  <img src="https://raw.githubusercontent.com/RWTH-EBC/AixWeather/main/docs/aixweather_logo/AixWeather_Logo.png" alt="AixWeather Logo" width="50%">
</div>

# 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](https://pypi.org/project/AixWeather/).

## WebApp

For fast access without setup, use the [AixWeather-WebApp](https://aixweather.eonerc.rwth-aachen.de/).
The [AixWeather-WebApp-Repository](https://github.com/RWTH-EBC/AixWeather-WebApp) 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](https://rwth-ebc.github.io/AixWeather//main//docs/examples/e1_pull_DWD_historical_to_all_output_formats.html) 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](https://rwth-ebc.github.io/AixWeather//main//docs/code/aixweather.transformation_functions.html), e.g. the [unit conversions](https://rwth-ebc.github.io/AixWeather//main//docs/code/aixweather.transformation_functions.html#module-aixweather.transformation_functions.unit_conversions) or the functions to calculate missing values: [variable transformation](https://rwth-ebc.github.io/AixWeather//main//docs/code/aixweather.transformation_functions.html#module-aixweather.transformation_functions.variable_transformations).
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.
![Weather Data Tool Diagram](https://raw.githubusercontent.com/RWTH-EBC/AixWeather/main/docs/Overview_WeatherTool.png)

**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](https://www.dwd.de/DE/leistungen/klimadatendeutschland/stationsliste.html). Only german stations available. Aachen would be 15000.

The DWD MOSMIX station IDs for the DWD forecast are listed [here](https://www.dwd.de/DE/leistungen/met_verfahren_mosmix/mosmix_stationskatalog.cfg?view=nasPublication&nn=16102) or located on a map [here](https://wettwarn.de/mosmix/mosmix.html). Worldwide station available. Aachen would be 10505.

You may use the imported package [Wetterdienst](https://github.com/earthobservations/wetterdienst) to search for stations automatically, as described [here](https://bookdown.org/brry/rdwd/station-selection.html).


# Sources of information for corresponding data formats

## Input

**Test Reference Years (TRY)**: 

[Handbuch](https://www.bbsr.bund.de/BBSR/DE/forschung/programme/zb/Auftragsforschung/5EnergieKlimaBauen/2013/testreferenzjahre/try-handbuch.pdf). 

TRY data can be downloaded from the DWD (sign up required but for free) [TRY data sets](https://www.bbsr.bund.de/BBSR/DE/forschung/programme/zb/Auftragsforschung/5EnergieKlimaBauen/2013/testreferenzjahre/01-start.html;jsessionid=5D9912D230EB887C1F831671303A8A0F.live21304?nn=2544408&pos=2). 

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](https://opendata.dwd.de/climate_environment/CDC/observations_germany/climate/)

**DWD forecasts (MOSMIX i.e. KML files)**: [open data website](https://opendata.dwd.de/weather/local_forecasts/) 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](https://designbuilder.co.uk/cahelp/Content/EnergyPlusWeatherFileFormat.htm)

**Modelica ReaderTMY3:**

TMY3 reader from the [IBPSA](https://github.com/ibpsa/modelica-ibpsa) library used in the [AixLib](https://github.com/RWTH-EBC/AixLib) library. Model info at [OpenModelica](https://build.openmodelica.org/Documentation/Buildings.BoundaryConditions.WeatherData.ReaderTMY3.html).
It claims to use mainly [TMY3 data](https://www.nrel.gov/docs/fy08osti/43156.pdf), 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](docs/source/Contribution.md).



# How to cite

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

```
@article{Rätz2025,
   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 Rätz and Fabian Wüllhorst and Rita Streblow and Dirk Müller}, 
   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](LICENSE).