jordanvajen

Overview

This module implements a domestic hot water (DHW) demand generation method based on Jordan & Vajen (2005): “DHWcalc: PROGRAM TO GENERATE DOMESTIC HOT WATER PROFILES WITH STATISTICAL MEANS FOR USER DEFINED CONDITIONS”. The implementation follows the Method pattern established in the project architecture.

The module provides functionality to:

• Process input parameters for DHW demand calculation

• Generate daily demand values based on dwelling size

• Calculate DHW demand time series based on activity profiles

• Compute summary statistics for the generated time series

The main class, JordanVajen, inherits from the Method base class and implements the required interface for integration with the EnTiSe framework.

Source: Jordan, U., & Vajen, K. (2005). DHWcalc: PROGRAM TO GENERATE DOMESTIC HOT WATER PROFILES WITH STATISTICAL MEANS FOR USER DEFINED CONDITIONS. Universität Marburg. URL: https://www.researchgate.net/publication/237651871_DHWcalc_PROGRAM_TO_GENERATE_DOMESTIC_HOT_WATER_PROFILES_WITH_STATISTICAL_MEANS_FOR_USER_DEFINED_CONDITIONS

Key facts

• Method key: jordanvajen

• Supported types:

  • dhw

Requirements

Required keys (specify in objects)

• datetimes

• dwelling_size[m2]

Optional keys (specify in objects)

• dhw_activity

• dhw_demand_per_size[m2]

• holidays_location

• cold_water_temperature[C]

• hot_water_temperature[C]

• seasonal_variation

• seasonal_peak_day

• seed

Required data (specify in data)

• datetimes

Optional data (specify in data)

• dhw_activity

• dhw_demand_per_size[m2]

• cold_water_temperature[C]

• hot_water_temperature[C]

Outputs

Summary metrics

Key	Description
dhw_volume_total	total hot water demand in liters
dhw_volume_avg	average hot water demand in liters
dhw_volume_peak	peak hot water demand in liters
dhw_energy_total	total energy demand for hot water in Wh
dhw_energy_avg	average energy demand for hot water in Wh
dhw_energy_peak	peak energy demand for hot water in Wh
dhw_power_avg	average power for hot water in W
dhw_power_max	maximum power for hot water in W
dhw_power_min	minimum power for hot water in W

Timeseries columns

Column	Description
dhw_volume	hot water demand in liters
dhw_energy	energy demand for hot water in Wh
dhw_power	power demand for hot water in W
dhw_power_sma	smoothed power demand using simple moving average
dhw_power_ewma	smoothed power demand using exponential weighted moving average
dhw_power_gaussian	smoothed power demand using gaussian smoothing
dhw_cold_water_temperature[C]	cold water temperature in degrees Celsius
dhw_hot_water_temperature[C]	hot water temperature in degrees Celsius

Public methods

• generate

    def generate(
      self,
      obj: dict = None,
      data: dict = None,
      results: dict | None = None,
      ts_type: str = Types.DHW,
      *,
      datetimes: pd.DataFrame = None,
      dwelling_size: float = None,
      dhw_activity: pd.DataFrame = None,
      dhw_demand_per_size: pd.DataFrame = None,
      holidays_location: str = None,
      temp_water_cold: float = None,
      temp_water_hot: float = None,
      seasonal_variation: float = None,
      seasonal_peak_day: int = None,
      seed: int = None,
  ):
      """Generate DHW demand time series based on input parameters.
  
      This method implements the abstract generate method from the Method base class.
      It processes the input parameters, calculates the DHW demand time series,
      and returns both the time series and summary statistics.
  
      Args:
          obj (dict, optional): Dictionary containing DHW system parameters. Defaults to None.
          data (dict, optional): Dictionary containing input data. Defaults to None.
          results (dict, optional): Dictionary with results from previously generated time series
          ts_type (str, optional): Time series type to generate. Defaults to Types.DHW.
          datetimes (pd.DataFrame, required): DataFrame with datetime information. Defaults to None.
          dwelling_size (float, required): Size of the dwelling in square meters. Defaults to None.
          dhw_activity (pd.DataFrame, optional): Activity profiles for DHW demand. Defaults to None.
          dhw_demand_per_size (pd.DataFrame, optional): Demand data per dwelling size. Defaults to None.
          holidays_location (str, optional): Location for holiday calendar. Defaults to None.
          temp_water_cold (float, optional): Cold water temperature in degrees Celsius. Defaults to None.
          temp_water_hot (float, optional): Hot water temperature in degrees Celsius. Defaults to None.
          seasonal_variation (float, optional): Seasonal variation factor. Defaults to None.
          seasonal_peak_day (int, optional): Day of year with peak demand. Defaults to None.
          seed (int, optional): Random seed for reproducibility. Defaults to None.
  
      Returns:
          dict: Dictionary containing:
              - "summary" (dict): Summary statistics including total demand,
                average demand, and peak demand.
              - "timeseries" (pd.DataFrame): Time series of DHW demand
                with timestamps as index.
  
      Raises:
          Exception: If required data is missing or invalid.
  
      Example:
          >>> jordanvajen = JordanVajen()
          >>> # Using explicit parameters
          >>> result = jordanvajen.generate(datetimes=datetimes_df, dwelling_size=100)
          >>> # Or using dictionaries
          >>> obj = {"datetimes": "datetimes", "dwelling_size": 100}
          >>> data = {"datetimes": datetimes_df}
          >>> result = jordanvajen.generate(obj=obj, data=data)
          >>> summary = result["summary"]
          >>> timeseries = result["timeseries"]
      """
      # Process keyword arguments
      processed_obj, processed_data = self._process_kwargs(
          obj,
          data,
          datetimes=datetimes,
          dwelling_size=dwelling_size,
          dhw_activity=dhw_activity,
          dhw_demand_per_size=dhw_demand_per_size,
          holidays_location=holidays_location,
          temp_water_cold=temp_water_cold,
          temp_water_hot=temp_water_hot,
          seasonal_variation=seasonal_variation,
          seasonal_peak_day=seasonal_peak_day,
          seed=seed,
      )
  
      processed_obj, processed_data = get_input_data(processed_obj, processed_data, ts_type)
  
      ts_volume, ts_energy, ts_power, water_temp = calculate_timeseries(processed_obj, processed_data)
  
      logger.debug(f"[DHW jordanvajen]: Generating {ts_type} data")
  
      return _format_output(processed_data, ts_volume, ts_energy, ts_power, water_temp)