uesgraphs.DHW_estimation package

This package contains the script that stores all function of the DHWcalc package as well as a utils package.

Subpackages

Submodules

uesgraphs.DHW_estimation.OpenDHW module

uesgraphs.DHW_estimation.OpenDHW.load_steps_and_ps(mode, building, building_type=None, s_step=None)[source]

Load the step durations and probabilities from a JSON file.

Parameters:

  • mode (str) – Mode of operation (“work-day” or “off-day”).

  • building (str) – Type of building (“residential” or “non-residential”).

  • building_type (str) – Specific type of building (e.g., “OB”, “SC”, “GS”, “RE”).

  • s_step (int) – Step size in seconds, required only for residential buildings.

Returns:

List of tuples containing step durations and probabilities.

Return type:

list

uesgraphs.DHW_estimation.OpenDHW.import_from_dhwcalc(s_step, daylight_saving, categories, occupancy, mean_drawoff_vol_per_day, max_flowrate=1200)[source]

DHWcalc yields Volume Flow TimeSeries (in Liters per hour).

Parameters:

  • s_step – int: resolution of file in seconds

  • categories – int: either ‘1’ or ‘4’

  • mean_drawoff_vol_per_day – int: daily water demand in Liters

  • daylight_saving – Bool: apply daylight saving or not

  • max_flowrate – int: maximum water flowrate in L/h

Return timeseries_df:

df: dataframe that holds the data

uesgraphs.DHW_estimation.OpenDHW.generate_dhw_profile(s_step, categories, mean_drawoff_vol_per_day, occupancy, holidays, building_type, weekend_weekday_factor, initial_day=0)[source]

Generates a DHW profile. The generation is split up in different functions and generally follows the methodology described in the DHWcalc paper from Uni Kassel.

  1. Load some data for the drawoff categories (cats_df).

  2. Generate a yearly probability profile

  3. Generate Drawoffs and distribute them randomly into the probability profile p_norm_integral.

  4. Add some additionally stats to the dataframe.

Parameters:

  • s_step – int: timestep width in seconds.

  • categories – int: 1 or 4 (see DHWcalc)

  • weekend_weekday_factor – int: taken from DHWcalc

  • mean_drawoff_vol_per_day – int: daily water demand in Liters

  • initial_day – int: 0:Mon - 1:Tues … 6:Sun

Returns:

timeseries_df df: dataframe with all timeseries

uesgraphs.DHW_estimation.OpenDHW.get_data_drawoff_categories(s_step, categories, mean_drawoff_vol_per_day, building_type)[source]

Get some data for each drawoff category. If only one category is chosen, a simplified datafarme is returned.

Parameters:

  • s_step – int: seconds in a timestep. f.e 900

  • categories – int: 1 or 4, 1: short laod (washing hands, etc.), 2: medium load (dish-washer, etc.), 3: bath, 4:shower (see DHWcalc)

  • mean_drawoff_vol_per_day – int: volume per day used in house

Returns:

cats_df: df: Categores Data

uesgraphs.DHW_estimation.OpenDHW.generate_daily_probability_step_function(mode, s_step, building_type, save_fig=False, test_concentrated_ps=False)[source]

Generates probabilities for a day with 6 periods. Corresponds to the mode “step function for working days and off days” in DHWcalc and uses the same standard values. Each Day starts at 0:00. Steps in hours. Sum of steps has to be 24. Sum of probabilities has to be 1.

Parameters:

  • test_concentrated_ps – bool: different probabilities, very concentrated in the morning

  • mode – string: working day or off day

  • s_step – int: seconds within a timestep

  • save_fig – Bool: plot the probability distribution

Returns:

p_day list: distribution for one day.

uesgraphs.DHW_estimation.OpenDHW.generate_yearly_probability_profile(s_step, weekend_weekday_factor, building_type, holidays, initial_day=0)[source]

generate a summed yearly probability profile. The whole function is deterministic. The same inputs always produce the same outputs.

  1. Probabilities for working days and off days are loaded (p_we, p_wd).

  2. Probability of off days is increased relative to working days (shift).

  3. Based on an initial day, the yearly probability distribution (p_final) is generated. The seasonal influence is modelled by a sine-function.

  4. p_final is normalized and integrated. The sum over the year is thus equal to 1 (p_norm_integral).

Parameters:

  • s_step – int: seconds in a timestep

  • weekend_weekday_factor – float: shift probabilities towards weekend

  • initial_day – int: Mon: 0 … Sun: 6

Returns:

timeseries_df: df: df that holds the yearly profile

uesgraphs.DHW_estimation.OpenDHW.shift_weekend_weekday(p_work_day, p_off_day, factor)[source]

Shifts the probabilities between the weekday list and the weekend list by a defined factor. If the factor is bigger than 1, the probability on the weekend is increased. If its smaller than 1, the probability on the weekend is decreased.

Parameters:

  • p_work_day – list: probabilities for 1 work day of the week [0…1]

  • p_off_day – list: probabilities for 1 off day of the week [0…1]

  • factor – float: factor to shift the probabilities between weekdays and weekend-days

Returns:

uesgraphs.DHW_estimation.OpenDHW.generate_yearly_probabilities(initial_day, p_off_day, p_work_day, s_step, holidays, building_type, plot_p_yearly=False)[source]

Takes the probabilities of a working days and a off days and generates a list of yearly probabilities by adding a seasonal probability factor. The seasonal factor is a sine-function, like in DHWcalc.

Parameters:

  • initial_day – int: 0: Mon, 1: Tue, 2: Wed, 3: Thur, 4: Fri, 5 : Sat, 6 : Sun

  • p_off_day – list: probabilities of an off day

  • p_work_day – list: probabilities of a working day

  • s_step – int: seconds within a timestep

  • plot_p_yearly – bool: plot the yearly probabilities

Returns:

p_final: list: probabilities of a full year

uesgraphs.DHW_estimation.OpenDHW.normalize_and_sum_list(lst, save_fig=False)[source]

takes a list and normalizes it based on the sum of all list elements. then generates a new list based on the current sum of each list entry.

Parameters:

  • lst – list: input list

  • save_fig – bool: plot the output list

Returns:

lst_norm_integral: list output list

uesgraphs.DHW_estimation.OpenDHW.generate_and_distribute_drawoffs(timeseries_df, cats_series)[source]

generate and distribute drawoffs

Parameters:

  • timeseries_df – df: holds the timeseries

  • cats_series – series: constants for a category

uesgraphs.DHW_estimation.OpenDHW.generate_single_drawoff_inside_boundaries(cats_series, s_step)[source]

From the data of one category, generate a drawoff inside the defined boundaries, similar to DHWcalc.

Parameters:

  • cats_series – df: pandas series that holds the drawoff data

  • s_step – int: seconds in a timestep

Returns:

drawoff: int: drawoff eevnt in L/h

uesgraphs.DHW_estimation.OpenDHW.compute_heat(timeseries_df, temp_dT=35)[source]

Add heat columns to the timeseries

Parameters:

  • timeseries_df – df: Pandas Dataframe with all the timeseries

  • temp_dT – int: temperature difference between freshwater and average DHW outlet temperature.

Returns:

timeseries_df: df: Dataframe with added ‘Heat’ Column

uesgraphs.DHW_estimation.OpenDHW.draw_lineplot(timeseries_df, plot_var='water', start_plot='2019-02-01', end_plot='2019-02-05', save_fig=False)[source]

Plots the timeseries for a given timedelta in a year.

Parameters:

  • timeseries_df – df: Dataframe that holds the timeseries.

  • plot_var – str: choose to plot Water or Heat series.

  • start_plot – str: start date of the plot. F.e. 2019-01-01

  • end_plot – str: end date of the plot. F.e. 2019-01-07

  • save_fig – bool: decide to save plots as pdf

uesgraphs.DHW_estimation.OpenDHW.draw_histplot(timeseries_df, extra_kde=False, save_fig=False)[source]

Takes a DHW profile and plots a histogram with some stats in the title

Parameters:

  • save_fig – bool: save the figure

  • timeseries_df – df: Dataframe that holds the water timeseries

  • extra_kde – bool: plot a detailed kde plot behind the main histogram.

uesgraphs.DHW_estimation.OpenDHW.draw_detailed_histplot(timeseries_df)[source]

https://towardsdatascience.com/advanced-histogram-using-python-bceae288e715 plot to further analyse timeseries with 1 drawoff category.

uesgraphs.DHW_estimation.OpenDHW.add_additional_runs(timeseries_df, holidays, occupancy, building_type, total_runs=5, dir_output=None)[source]

method to add more runs to a timeseries dataframe with the same input parameters as the original timeseries.

Parameters:

  • timeseries_df –

  • total_runs –

  • dir_output –

Returns:

uesgraphs.DHW_estimation.OpenDHW.get_drawoffs(timeseries_df, remove_cats=True)[source]

get sorted drawoff events from a timeseries Dataframe.

uesgraphs.DHW_estimation.OpenDHW.plot_multiple_runs(timeseries_df, plot_demands_overlay=True, start_plot='2019-02-01', end_plot='2019-02-02', plot_hist=True, plot_kde=True)[source]

This function should only be used when the ‘add_additional_runs’ function has been used before.

Parameters:

  • timeseries_df – df: dataframe with timesieries

  • plot_demands_overlay – bool: plot lineplot

  • start_plot – str: start date

  • end_plot – str: end date

  • plot_hist – bool: plot histogram

  • plot_kde – bool: plot kde plot

uesgraphs.DHW_estimation.OpenDHW.plot_multiple_timeseries(timeseries_lst, col_part='Water_LperH', plot_demands_overlay=True, start_plot='2019-02-01', end_plot='2019-02-02', plot_hist=True, plot_kde=True)[source]

plots multiple timeseries given in a list. better than “plot multiple runs?”

Parameters:

  • timeseries_lst – list: list with timeseries dataframes

  • col_part – str: string that matches colum names which should be plotted

  • plot_demands_overlay – bool: plot lineplot of all dfs

  • start_plot – str: start of lineplot

  • end_plot – str: end of lineplot

  • plot_hist – bool: plot histogram

  • plot_kde – bool: plot kde plot

Returns:

uesgraphs.DHW_estimation.OpenDHW.compare_generators(timeseries_df_1, timeseries_df_2, start_plot='2019-03-01', end_plot='2019-03-08', plot_date_slice=True, plot_distribution=True, plot_detailed_distribution=True, save_fig=False)[source]

Compares two timeseries by plotting them next to each other with the same x and y axis limits.

Parameters:

  • timeseries_df_1 – df: first timeseries dataframe

  • timeseries_df_2 – df: second timeseries dataframe

  • start_plot – str: date, f.e. 2019-03-01

  • end_plot – str: date, f.e. 2019-03-08

  • plot_date_slice – bool: plot lineplots

  • plot_distribution – bool: plot histplots

  • plot_detailed_distribution – bool: plot detailed histplots

  • save_fig – bool: save the plot

uesgraphs.DHW_estimation.OpenDHW.plot_three_histplots(timeseries_df_1, timeseries_df_2, timeseries_df_3)[source]

Compares three timeseries by means of a triple subplot. :param timeseries_df_1: df: first time series :param timeseries_df_2: df: second time series :param timeseries_df_3: df: third time series

uesgraphs.DHW_estimation.OpenDHW.jensen_shannon_distance(p, q)[source]

method to compute the Jenson-Shannon Distance between two probability distributions. 0 indicates that the two distributions are the same, and 1 would indicate that they are nowhere similar.

From https://medium.com/@sourcedexter/how-to-find-the-similarity-between-two-probability-distributions-using-python-a7546e90a08d

uesgraphs.DHW_estimation.OpenDHW.get_s_step(timeseries_df)[source]

get the seconds within a timestep from a pandas dataframe. When loading Dataframes from a csv, the index loses its ‘freq’ attribute. This is thus just a workaround when loading Timeseries from csv.

uesgraphs.DHW_estimation.OpenDHW.make_title_str(timeseries_df)[source]

creates a title string based on the timeseries dataframe. The title string can then be used for a variety of plots.

uesgraphs.DHW_estimation.OpenDHW.resample_water_series(timeseries_df, s_step_output)[source]

Before resampling a dataframe, we have to choose which data has to be resampled in what way. some columns list constants, some list intensive properties (like L/h, kW) and some list extensive properties (Like Liters/kWh). Constants should stay the same, intensive properties should be averaged and extensive properties should be summed up.

Parameters:

  • timeseries_df – df: dataframe that holds the timeseries

  • s_step_output – int: desired output seconds in a timestep

Returns:

timeseries_df_re: df: resampled dataframe

uesgraphs.DHW_estimation.OpenDHW.reduce_no_drawoffs(timeseries_df)[source]

for some reason, DHWcalc still yields less yearly drawoffs than OpenDHW. In case the yearly water demand is higher in an OpenDHW timeseries than the expected one, this function removes some randomly selected drawoffs events with a small flowrate to reduce the yearly water demand until its just under the expected one and simultaneously decreasing the number of drawoffs.

Parameters:

timeseries_df – df: input dataframe

Returns:

timeseries_df_cleaned: df output dataframe

uesgraphs.DHW_estimation.OpenDHW.get_holidays(country_code: str, year: int, state: str = None)[source]

Get the Julian day (day of the year) for holidays in a specific country, year, and state.

Parameters:

  • country_code (str) – The country’s ISO 3166-1 alpha-2 code (e.g., ‘DE’ for Germany).

  • year (int) – The year for which to retrieve holidays.

  • state (str) – The state or region subdivision code (e.g., ‘NW’ for North Rhine-Westphalia in Germany).

Returns:

A list of tuples containing the Julian day of the holiday.

Return type:

list

uesgraphs.DHW_estimation.utilities module

uesgraphs.DHW_estimation.utilities.set_up_file_logger(name: str, log_dir: str | None = None, level: int = 40) → Logger[source]

Set up a full file+console logger for major functions.

Parameters:

  • name – Logger name

  • log_dir – Directory for log files (default: temp directory)

  • level – Logging level (default: ERROR)

Returns:

Configured file+console logger

uesgraphs.DHW_estimation.utilities.set_up_logger(name, log_dir=None, level=40)[source]

Sets up a configured logger with file handler.

Creates a logger with specified name and logging level. Log files are stored in a directory with timestamp in filename. If no directory is specified, the system’s temporary directory is used.

Parameters:

  • name (str) – Name of the logger, also used for filename

  • log_dir (str, optional) – Directory for log files. Defaults to None (uses temp directory)

  • level (int, optional) – Logging level (e.g. logging.ERROR, logging.INFO). Defaults to logging.ERROR

Returns:

Configured logger object

Return type:

logging.Logger

Example

>>> logger = set_up_logger("my_app", "/var/log", logging.INFO)
>>> logger.info("Application started")

Notes

  • Log filename format: {name}_{YYYYMMDD_HHMMSS}.log

  • Log entry format: time - logger_name - [file:line] - level - message

uesgraphs.DHW_estimation.utilities.load_simulation_settings_from_excel(excel_path, logger=None)[source]

Load simulation settings from Excel ‘Simulation’ sheet.

Parameters:

  • excel_path (str or Path) – Path to Excel file containing simulation settings

  • logger (logging.Logger, optional) – Logger instance

Returns:

sim_params – Dictionary of simulation parameters

Return type:

dict

Raises:

ValueError – If required simulation parameters are missing

uesgraphs.DHW_estimation.utilities.load_component_parameters(excel_path, component_type)[source]

Load component parameters from an Excel file.

Reads a specific sheet from an Excel file and returns parameters as a dictionary. Expected Excel structure: - Column A: Parameter (parameter names) - Column B: Value (parameter values)

Parameters:

  • excel_path (str or Path) – Path to the Excel file containing component parameters

  • component_type (str) – Type of component, must be one of: ‘pipes’, ‘supply’, ‘demands’, ‘simulation’ This determines which sheet to read from the Excel file

Returns:

Dictionary with parameter names as keys and their values Returns empty dict if sheet not found

Return type:

dict

Raises:

  • FileNotFoundError – If the Excel file does not exist

  • ValueError – If the component_type is not valid or Excel structure is incorrect

Examples

>>> params = load_component_parameters('parameters.xlsx', 'pipes')
>>> print(params['dp_nominal'])
0.10
uesgraphs.DHW_estimation.utilities.create_profiles(info_path, timestep, mean_drawoff_vol_per_day, temp_dT_dhw, holidays=[1, 108, 111, 121, 149, 160, 276, 359, 360], logger=None)[source]

Create DHW profiles according to infos in geojson.

Parameters:

  • info_path (path) – Full path to json with building infos.

  • timestep (int) – Timestep in seconds for the generated time-series.

  • holidays (list of datetime.date, optional) – List of holiday dates to consider in the profile generation (default: German holidays for 2025).

  • mean_drawoff_vol_per_day (float) – Average drawoff volume per day in liters per occupant

  • logger (logging.Logger, optional) – Logger instance for logging progress and warnings (default: None, creates a new logger if not provided).

Returns:

DataFrame containing the generated DHW profiles for each building

Return type:

pd.DataFrame

uesgraphs.DHW_estimation.utilities.generate_DHW_profiles_from_geojson(buildings_info_path, save_path, timestep=3600, mean_drawoff_vol_per_day=40, temp_dT_dhw=35, sim_setup_path=None, logger=None, log_level=10)[source]

Run OpenDHW for demand estimation based on building information from a .geojson file.

Parameters:

buildings_info_pathstr

The path to the .geojson file containing building information for TEASER model creation.

save_pathstr or Path

Directory path where the resulting demand CSV files will be saved.

timestepint, optinal

Simulation timestep in seconds (default is 3600 for hourly data)

mean_drawoff_vol_per_dayfloat, optional

Average drawoff volume per day in liters per occupant (default is 40 L/day/occupant)

temp_dT_dhwfloat, optional

Temperature difference for Heat calculation from mass flows in K (default is 35 K)

sim_setup_pathstr or Path, optional

Path to the simulation setup for timestep and stop time. If not provided, default values will be used.

loggerlogging.Logger, optional

Logger instance. If None, creates a new file logger in temp directory

log_levelint, optional

Logging level (default is logging.DEBUG). Only used if logger is None

Returns:

tuple

Paths to the generated demand CSV files: (heating_demand_csv, cooling_demand_csv)