Demand & weather

Outdoor-air temperature utilities and domestic hot water demand profiles consumed by the dynamic simulation entry points.

Weather

Weather data processing and irradiance calculations.

tmhp.weather.decompose_ghi_to_poa(ghi, latitude, longitude, tilt, azimuth, altitude=0, tz='Asia/Seoul', decomposition='erbs', transposition='perez')[source]

Decompose GHI to POA (Plane of Array) total irradiance.

Parameters:

  • ghi (np.ndarray or pd.Series) – Global horizontal irradiance timeseries [W/m2]. Must have DatetimeIndex.

  • latitude (float) – Location latitude.

  • longitude (float) – Location longitude.

  • tilt (float) – Surface tilt angle [deg].

  • azimuth (float) – Surface azimuth [deg]. 180 is South.

  • altitude (float, optional) – Location altitude [m]. Default is 0.

  • tz (str, optional) – Timezone. Default is ‘Asia/Seoul’.

  • decomposition (str, optional) – DNI/DHI decomposition model (‘erbs’, ‘dirint’, etc). Default is ‘erbs’.

  • transposition (str, optional) – POA transposition model (‘perez’, ‘isotropic’, etc). Default is ‘perez’.

Returns:

DataFrame with ‘poa_global’, ‘poa_direct’, ‘poa_diffuse’.

Return type:

pd.DataFrame

tmhp.weather.load_kma_T0_sol_hourly_csv(csv_path, encoding='euc-kr')[source]

Load KMA hourly temperature and solar irradiance CSV.

Parameters:

  • csv_path (str) – Path to CSV file.

  • encoding (str, optional) – File encoding. Default is ‘euc-kr’.

Returns:

DataFrame with datetime index, ‘T0_K’, and ‘ghi’ columns.

Return type:

pd.DataFrame

tmhp.weather.load_kma_solar_csv(csv_path, encoding='euc-kr')[source]

Load a Korea Meteorological Administration (KMA, 기상청) 1-minute cumulative solar irradiance CSV.

Parameters:

  • csv_path (str) – Path to CSV file.

  • encoding (str, optional) – File encoding. Default is ‘euc-kr’.

Returns:

DataFrame with datetime index and ‘ghi’ column [W/m2].

Return type:

pd.DataFrame

Domestic hot water demand

Domestic Hot Water (DHW) load modeling.

tmhp.dhw.build_dhw_usage_ratio(entries, t_array)[source]

Build schedule ratio array from schedule entries for each timestep.

Parameters:

  • entries (list[tuple[str, str, float]]) – Schedule entry list. Each item is (start_str, end_str, frac) format.

  • t_array (np.ndarray) – Array of time seconds from start of day.

Returns:

Array of fractions corresponding to t_array.

Return type:

np.ndarray

tmhp.dhw.calc_cold_water_temp(df, target_date_str)[source]

Calculate mains water temperature using EnergyPlus algorithm.

Uses monthly average outdoor air temperature to estimate the water mains temperature based on the algorithm from Hendron et al. (2004).

References

Hendron, R., Anderson, R., Judkoff, R., Christensen, C., Eastment, M., & Norton, P. (2004). Building America Performance Analysis Procedures for Energy-Efficient Residential Buildings. National Renewable Energy Laboratory (NREL). https://doi.org/10.2172/15011400

Parameters:

  • df (pd.DataFrame) – DataFrame with monthly average temperatures. Must have ‘month’ and ‘T_avg’ columns.

  • target_date_str (str) – Target date string in ‘YYYY-MM-DD’ format.

Returns:

Calculated cold water temperature [degC].

Return type:

float

tmhp.dhw.calc_total_water_use_from_schedule(schedule, peak_load_m3s, info=True, info_unit='L')[source]

Calculate total daily water use from a schedule.

Parameters:

  • schedule (list[tuple[str, str, float]]) – Schedule list. Each item is (start_str, end_str, ratio) format.

  • peak_load_m3s (float) – Peak load water flow rate [m3/s].

  • info (bool, optional) – Flag to print info. Default is True.

  • info_unit (str, optional) – Unit to print info. Default is ‘L’.

Returns:

Total daily water usage [m3].

Return type:

float

tmhp.dhw.make_dhw_schedule_from_Annex_42_profile(flow_rate_array, df_time_step, simulation_time_step)[source]

Generate DHW schedule list from flow profile data.

This function implements the logic to convert a flow profile (L/min) into a schedule list with specified time step.

Parameters:

  • flow_rate_array (np.ndarray) – Array of flow rates [L/min]. Data should represent 24 hours.

  • df_time_step (int) – Time step of the input flow_rate_array [min].

  • simulation_time_step (int) – Target time step for the simulation schedule [s].

Returns:

List of tuples (start_time, end_time, fraction).

Return type:

list[tuple[str, str, float]]