districtheatingsim

Overview

Space heating demand using DistrictHeatingSim’s BDEW methodology.

Purpose and scope:

• Wraps the DistrictHeatingSim BDEW implementation to synthesize hourly heating energy profiles for a selected BDEW profile type (e.g., HEF03), scaled to an annual demand target and aligned to the requested timestep.

• Optionally splits the total load into space heating and DHW shares via the dhw_share parameter.

Notes:

• Provide weather with a datetime column and air temperature. The method derives wall‑clock timestamps and applies a power‑preserving alignment when your resolution differs from the hourly native resolution of the underlying model.

• The first three characters of profile_type define the building group, the last two its subtype, e.g., “HEF03”.

Reference:

• DistrictHeatingSim (BDEW heat requirement): https://github.com/rl-institut/DistrictHeatingSim

• BDEW guideline (German Association of Energy and Water Industries).

Key facts

• Method key: districtheatingsim

• Supported types:

  • heating

Requirements

Required keys (specify in objects)

• weather

Optional keys (specify in objects)

• demand[kWh]

• profile_type

• dhw_share

Required data (specify in data)

• weather

Optional data (specify in data)

• None

Outputs

Summary metrics

Key	Description
heating:demand[kWh]	total heating demand

Timeseries columns

Column	Description
heating:load[W]	total heating load per timestep
heating:load_space[W]	space heating load per timestep (derived via dhw_share)
heating:load_dhw[W]	DHW load per timestep (derived via dhw_share)

Public methods

• generate

    def generate(
      self,
      obj: dict = None,
      data: dict = None,
      results: dict = None,
      ts_type: str = Types.HEATING,
      *,
      annual_demand_kwh: float = None,
      weather: pd.DataFrame = None,
      profile_type: str = None,
      dhw_share: Optional[float] = None,
  ):
      """Generate a heating load timeseries using DistrictHeatingSim's BDEW heat model.
  
      This method prepares inputs (including optional overrides), computes the
      heating demand profile using DistrictHeatingSim’s BDEW implementation
      based on outdoor air temperature and profile parameters, and returns a
      summary and timeseries.
  
      Args:
          obj: Object dictionary with inputs like annual demand, profile type,
               DHW share, and weather key.
          data: Data dictionary containing the weather dataframe under O.WEATHER.
          results: Unused placeholder for interface compatibility.
          ts_type: Timeseries type, defaults to Types.HEATING.
          annual_demand_kwh: Optional annual heat demand in kWh.
          weather: Optional weather dataframe override with C.DATETIME and C.TEMP_AIR.
          profile_type: Optional BDEW profile type (e.g., "HEF03", "GBH01").
                        First three characters define building type, last two subtype.
          dhw_share: Optional domestic hot water share (0–1), passed to
                     DistrictHeatingSim as real_ww_share.
  
      Returns:
          dict: {"summary": {...}, "timeseries": DataFrame with columns:
            - "heating:load[W]" (total)
            - "heating:load_space[W]" (derived)
            - "heating:load_dhw[W]" (derived)
          indexed like the input weather datetimes.
      """
      processed_obj, processed_data = self._process_kwargs(
          obj,
          data,
          annual_demand_kwh=annual_demand_kwh,
          weather=weather,
          profile_type=profile_type,
          dhw_share=dhw_share,
      )
      processed_obj, processed_data = self._get_input_data(processed_obj, processed_data, ts_type)
  
      ts_total_w = calculate_timeseries(processed_obj, processed_data)
  
      logger.debug(f"[districtheatsim heat]: Generating {ts_type} data")
  
      return self._format_output(ts_total_w, processed_obj)