hd_time_series_generator module

hd_time_series_generator.assign_temp(ar_states: ndarray, T_setpoint=22.0, T_setback=18.0) → ndarray[source]

Assigns the setpoint temperature to the states based on the occupancy time series.

This function takes the occupancy time series and assigns the setpoint temperature to the states. The setpoint temperature is assigned to the states where the occupancy is 1 (occupied) and the setback temperature is assigned to the states where the occupancy is 0 (unoccupied). The function returns the states with the assigned temperatures.

Parameters:

  • ar_states (np.ndarray) -- A numpy array with the occupancy time series for one year in hourly resolution.

  • T_setpoint (float, optional) -- Setpoint temperature in °C, defaults to 22.0

  • T_setback (float, optional) -- Setback temperature in °C, defaults to 18.0

Returns:

A numpy array with the setpoint temperature.

Return type:

np.ndarray

hd_time_series_generator.calc_WD_WE_sequence(df_temperature: DataFrame) → ndarray[source]

Calculates a seqeunce of business days and weekends based on the date of the dataset.

Parameters:

df_temperature (pd.DataFrame) -- pandas dataframe with the temperature data and the date

Returns:

numpy array with the sequence of business days and weekends

Return type:

np.ndarray

hd_time_series_generator.calc_yearly_occupancy(ar_WDWE: ndarray, ar_transition_matrix_WD: ndarray, ar_transition_matrix_WE: ndarray) → ndarray[source]

Calculates the yearly occupancy time series for a given sequence of business days and weekends by Markov Chain Monte Carlo (MCMC) simulation.

Parameters:

  • ar_WDWE (np.ndarray) -- A numpy array with the sequence of business days and weekends.

  • ar_transition_matrix_WD (np.ndarray) -- A numpy array with the transition matrix for weekdays.

  • ar_transition_matrix_WE (np.ndarray) -- A numpy array with the transition matrix for weekends.

Returns:

A numpy array with the yearly occupancy time series in hourly resolution.

Return type:

np.ndarray

hd_time_series_generator.check_yearly_demand_deviation(gdf_buildings: GeoDataFrame, df_heat_demand: DataFrame)[source]

Check deviation of the yearly demand of the buildings from the sum of the heating demand time series.

Parameters:

  • gdf_buildings (gpd.GeoDataFrame) -- geodataframe with the building data

  • df_heat_demand (pd.DataFrame) -- dataframe with the heating demand time series

hd_time_series_generator.convert_buildings_to_dwellings(gdf_buildings: GeoDataFrame) → tuple[source]

Convert the building data to dwelling data and split the data into individual arrays.

This function takes the building data and splits it into individual arrays for each dwelling. The arrays are then used to generate the heating demand time series.

Parameters:

gdf_buildings (gpd.GeoDataFrame) -- geodataframe with the building data

Returns:

individual arrays for the different building properties

Return type:

tuple

hd_time_series_generator.convert_dwelling_TS_to_building_TS(dwelling_HD_TS: ndarray, ar_building_id: ndarray) → DataFrame[source]

Sum up the heating demand time series for all dwellings in a building and convert the data to a pandas dataframe.

This function takes the heating demand time series for all dwellings and sums them up for each building. The resulting data is then converted to a pandas dataframe.

Parameters:

  • dwelling_HD_TS (np.ndarray) -- numpy array with the heating demand time series for all dwellings

  • ar_building_id (np.ndarray) -- numpy array with the building id for each dwelling

Returns:

pandas dataframe with the heating demand time series for all buildings

Return type:

pd.DataFrame

hd_time_series_generator.fast_TS_generator(case_study_name: str, save_to_disk=False) → DataFrame[source]

Performs a complete run of the time series generator for a given case study.

This function loads the necessary data, processes it, and generates time series data for buildings. Steps:

  1. Load the configuration file.

  2. Load the transition matrices for weekdays (WD) and weekends (WE).

  3. Load and process temperature data.

  4. Initialize arrays for internal and solar gains.

  5. Load building data as a GeoDataFrame.

  6. Convert building data to dwelling-specific arrays.

  7. Generate time series for each dwelling using thermal properties and external conditions.

  8. Aggregate dwelling-level time series into building-level time series.

  9. Save the resulting time series to disk as a CSV file.

Parameters:

  • case_study_name (str) -- name of the case study

  • save_to_disk (bool, optional) -- set to true if you want to write the results into a csv. file, defaults to False

Returns:

a pandas dataframe with the generated time series data in hourly resolution for all buildings

Return type:

pd.DataFrame

hd_time_series_generator.fast_calculate_hd_ts(ar_Tout: ndarray, ar_Tset: ndarray, ar_internal_gain: ndarray, ar_solar_gain: ndarray, max_heat_power=15.0, thermal_coductance=0.12, thermal_storage_capacity=7.0, scalor_solar_gain=0.0, scalor_internal_gain=0.0) → tuple[source]

Fast calculation of the heating demand time series for a single dwelling.

This function gets precompiled to speed up the calculations. All parameters and time series in the input are for a single dwelling.

Parameters:

  • ar_Tout (np.ndarray) -- A numpy array with the outside temperature for each time step in °C.

  • ar_Tset (np.ndarray) -- A numpy array with the setpoint temperature for each time step in °C.

  • ar_internal_gain (np.ndarray) -- A numpy array with the internal gain for each time step in kW.

  • ar_solar_gain (np.ndarray) -- A numpy array with the solar gain for each time step in kW.

  • max_heat_power (float, optional) -- Maximum heating power for that dwelling in kW, defaults to 15.0

  • thermal_coductance (float, optional) -- generalised thermal conductance in kW/K for the specific dwelling, defaults to 0.12

  • thermal_storage_capacity (float, optional) -- generalised thermal storage capacity in kWh/K for the specific dwelling, defaults to 7.0

  • scalor_solar_gain (float, optional) -- Scaling factor for the solar gain of the specific dwelling, defaults to 0.0

  • scalor_internal_gain (float, optional) -- Scaling factor for the internal gain for the specific dwelling, defaults to 0.0

Returns:

returns the heating demand time series and the indoor temperature time series for the dwelling

Return type:

tuple

hd_time_series_generator.fast_generate_building_ts(ar_building_id: ndarray, ar_GeneralisedThermCond: ndarray, ar_GeneralisedThermCap: ndarray, ar_MaxDemand: ndarray, ar_temp_setpoint: ndarray, ar_temp_setback: ndarray, ar_Tout: ndarray, ar_WDWE: ndarray, ar_transition_matrix_WD: ndarray, ar_transition_matrix_WE: ndarray, ar_solar_gain_profile: ndarray, scalor_solar_gain: ndarray, scalor_internal_gain: ndarray) → ndarray[source]

This function generates the heating demand time series for all dwellings.

This function provides a fast implementation of the heating demand time series generator. It uses vectorized operations to speed up the calculations. All input data has to be provided as numpy arrays. The function returns a numpy array with the heating demand time series for all dwellings.

Parameters:

  • ar_building_id (np.ndarray) -- A numpy array with the corresponding building id for each dwelling.

  • ar_GeneralisedThermCond (np.ndarray) -- A numpy array with the generalised thermal conductance for each dwelling.

  • ar_GeneralisedThermCap (np.ndarray) -- A numpy array with the generalised thermal capacity for each dwelling.

  • ar_MaxDemand (np.ndarray) -- A numpy array with the maximum heating demand for each dwelling.

  • ar_temp_setpoint (np.ndarray) -- A numpy array with the setpoint temperature for each dwelling.

  • ar_temp_setback (np.ndarray) -- A numpy array with the setback temperature for each dwelling.

  • ar_Tout (np.ndarray) -- A numpy array with the outside temperature for each time step.

  • ar_WDWE (np.ndarray) -- A numpy array with the sequence of business days and weekends.

  • ar_transition_matrix_WD (np.ndarray) -- A numpy array with the transition matrix for weekdays.

  • ar_transition_matrix_WE (np.ndarray) -- A numpy array with the transition matrix for weekends.

  • ar_solar_gain_profile (np.ndarray) -- A numpy array with the general solar gain (= solar irradiation) for each time step.

  • scalor_solar_gain (np.ndarray) -- A numpy array with the scaling factor for the solar gain for each dwelling.

  • scalor_internal_gain (np.ndarray) -- A numpy array with the scaling factor for the internal gain for each dwelling.

Returns:

A numpy array with the heating demand time series for all dwellings.

Return type:

np.ndarray

hd_time_series_generator.fast_generate_mcchain(ar_transition_matrix: ndarray, ini_prob=0.2, resample=True) → ndarray[source]

Generates a Markov Chain Monte Carlo (MCMC) chain based on the transition matrix for one day.

Parameters:

  • ar_transition_matrix (np.ndarray) -- A numpy array with the transition matrix for one day.

  • ini_prob (float, optional) -- probability for active for the first time step, defaults to 0.2

  • resample (bool, optional) -- boole flag: if True the 10-min profile is converted to hourly resolution, defaults to True

Returns:

a numpy array with the MCMC chain in hourly (or 10-min) resolution

Return type:

np.ndarray

hd_time_series_generator.prepare_temp_out(scenario: str, config: dict) → DataFrame[source]

Prepare the outside temperature data for the simulation.

Based on the datetime index, the function adds a column to indicate whether the day is a business day or not.

Parameters:

  • scenario (str) -- _description_

  • config (dict) -- configuration dictionary

Returns:

pandas dataframe with the outside temperature

Return type:

pd.DataFrame

hd_time_series_generator.write_hdts_to_disk(df_heating: DataFrame, casestudy: str, config: dict)[source]

Write the heating demand time series to disk.

This function checks if the directory exists and creates it if not. Then it saves the heating demand time series to a CSV file. For large datasets, this can take a while. Cosider other data formats if this becomes a problem.

Parameters:

  • df_heating (pd.DataFrame) -- pandas dataframe with the heating demand for buildings

  • casestudy (str) -- name of the case study

  • config (dict) -- configuration dictionary