1R0C

Overview

Implements the 1R0C model for HVAC demand and indoor temperature simulation.

The 1R0C model calculates time-series data for indoor temperature and energy demand for heating and cooling based on provided inputs such as weather data, and the resistance property of buildings. It also summarizes total heating and cooling demands over the simulation period. This model is typically used for building energy performance analysis and HVAC load calculations.

Attributes: types (list): A list of applicable types for the method. In this case, it includes only Types.HVAC. name (str): The name of the model. required_keys (list): Keys required in the input data for the model to execute, such as resistance, and weather data. optional_keys (list): Additional keys that are not mandatory but may be included in the input data, such as power heating, power cooling, or ventilation settings. required_timeseries (list): Time-series data required to compute the outputs, such as weather data. optional_timeseries (list): Optional time-series data inputs, such as internal and solar gains. output_summary (dict): Summary of the output results, providing keys with their descriptions, such as total heating and cooling demands. output_timeseries (dict): Time-series output data generated by the model, including indoor temperature, heating load, and cooling load.

Key facts

• Method key: 1R0C

• Supported types:

  • hvac

Requirements

Required keys (specify in objects)

• resistance[K W-1]

• weather

Optional keys (specify in objects)

• power_heating[W]

• power_cooling[W]

• active_heating

• active_cooling

• init_temperature[C]

• min_temperature[C]

• max_temperature[C]

• gains_internal[W]

• gains_internal_column

• ventilation[W K-1]

• ventilation_column

• gains_solar[W]

• windows

Required data (specify in data)

• None

Optional data (specify in data)

• None

Outputs

Summary metrics

Key	Description
heating:demand[Wh]	total heating demand
heating:load_max[W]	maximum heating load
cooling:demand[Wh]	total cooling demand
cooling:load_max[W]	maximum cooling load

Timeseries columns

Column	Description
indoor_temperature[C]	indoor air temperature
heating:load[W]	heating load
cooling:load[W]	cooling load

Public methods

• generate

    def generate(
      self,
      obj: dict = None,
      data: dict = None,
      results: dict | None = None,
      ts_type: str = Types.HVAC,
      *,
      resistance: float = None,
      weather: pd.DataFrame = None,
      power_heating: float = None,
      power_cooling: float = None,
      active_heating: bool = None,
      active_cooling: bool = None,
      ventilation: float = None,
      temp_init: float = None,
      temp_min: float = None,
      temp_max: float = None,
      gains_internal: pd.DataFrame = None,
      gains_solar: pd.DataFrame = None,
  ):
      """Generate HVAC time series based on input parameters and weather data.
  
      This method implements the abstract generate method from the Method base class.
      It processes the input parameters, calculates the indoor temperature and energy
      demand time series, and returns both the time series and summary statistics.
  
      Args:
          obj (dict, optional): Dictionary containing building parameters. Defaults to None.
          data (dict, optional): Dictionary containing input data. Defaults to None.
          ts_type (str, optional): Time series type to generate. Defaults to Types.HVAC.
          resistance (float, optional): Thermal resistance in K/W. Defaults to None.
          weather (pd.DataFrame, optional): Weather data with outdoor temperature. Defaults to None.
          power_heating (float, optional): Maximum heating power in W. Defaults to None.
          power_cooling (float, optional): Maximum cooling power in W. Defaults to None.
          active_heating (bool, optional): Whether heating is active. Defaults to None.
          active_cooling (bool, optional): Whether cooling is active. Defaults to None.
          ventilation (float, optional): Ventilation rate in W/K. Defaults to None.
          temp_init (float, optional): Initial indoor temperature in °C. Defaults to None.
          temp_min (float, optional): Minimum indoor temperature in °C. Defaults to None.
          temp_max (float, optional): Maximum indoor temperature in °C. Defaults to None.
          gains_internal (pd.DataFrame, optional): Internal heat gains in W. Defaults to None.
          gains_solar (pd.DataFrame, optional): Solar heat gains in W. Defaults to None.
  
      Returns:
          dict: Dictionary containing:
              - "summary" (dict): Summary statistics including total heating and
                cooling demand, and maximum heating and cooling loads.
              - "timeseries" (pd.DataFrame): Time series of indoor temperature,
                heating load, and cooling load with timestamps as index.
  
      Raises:
          Exception: If required data is missing or invalid.
      """
      obj, data = self._process_kwargs(
          obj,
          data,
          resistance=resistance,
          weather=weather,
          power_heating=power_heating,
          power_cooling=power_cooling,
          active_heating=active_heating,
          active_cooling=active_cooling,
          ventilation=ventilation,
          temp_init=temp_init,
          temp_min=temp_min,
          temp_max=temp_max,
          gains_internal=gains_internal,
          gains_solar=gains_solar,
      )
      obj, data = self._get_input_data(obj, data, ts_type)
  
      # Timestep in seconds. Only the delta matters — casting the whole
      # DATETIME column costs ~20 ms/object on a timezone-aware index
      # because pandas materializes object dtype first.
      dt_col = data[O.WEATHER][C.DATETIME]
      timestep = np.float32((dt_col.iloc[1] - dt_col.iloc[0]).total_seconds())
  
      # Precompute auxiliary data
      data[O.GAINS_INTERNAL] = InternalGains().generate(obj, data)
      data[O.GAINS_SOLAR] = SolarGains().generate(obj, data)
      data[O.VENTILATION] = Ventilation().generate(obj, data)
  
      # Compute temperature and energy demand
      temp_in, p_heat, p_cool = calculate_timeseries_1r0c(obj, data, timestep)
  
      logger.debug(f"[HVAC R1C0] {ts_type}: max heating {p_heat.max()}, cooling {p_cool.max()}")
  
      return self._format_output(temp_in, p_heat, p_cool, data, timestep)