External Factors

class heatpro.external_factors.external_factors.ExternalFactors(data_external_factors: DataFrame)[source]

Bases: object

check_required_features(dataframe: DataFrame) → bool[source]

Check if a DataFrame contains all the required features specified in REQUIRED_FEATURES.

Parameters:

dataframe (pd.DataFrame) – External factors data.

Returns:

True if all required features are present, False otherwise.

Return type:

bool

property data: DataFrame

Get the external factors data.

Returns:

External factors data.

Return type:

pd.DataFrame

plot() → Axes[source]

Plots the external factors profile data.

Returns:

The matplotlib Axes object for the plot.

Return type:

Axes

Heating Season

heatpro.external_factors.process.heating_season.non_heating_season_basic(external_temperature: Series, temperature_threshold: float, hot_day_min_share: float) → tuple[Timestamp, Timestamp][source]

Determines the beginning and end dates of the non-heating season for a district heating network.

The non-heating season is defined as the longest period during which the average hourly temperature remains above a certain threshold, with a minimum share of hot days (days with average temperature above the threshold) within that period.

Parameters:

  • external_temperature (pd.Series) – A pandas Series containing the hourly average external temperature.

  • temperature_threshold (float) – The temperature threshold above which a day is considered a hot day.

  • hot_day_min_share (float) – The minimum share of hot days required for a period to be considered part of the non-heating season.

Returns:

A tuple containing the beginning and end dates of the non-heating season as pandas Timestamps.

Return type:

tuple[pd.Timestamp,pd.Timestamp]

Overview

We define :

  • \((\bar{T}_{n})_{n\in\{1,\dots,365\}}\) : the daily average outside temperature series (input is hourly time serie)

  • \(T_{threshold}\) : the hot day temperature threshold, for \(n\in\{1,\dots,365\}\) if \(\bar{T}_{n} > T_{threshold}\) then day \(n\) is a hot day, else it is a cold day

  • \(\sigma\) : the minimal share of hot days the non-heating season must contain

The function return \(n_{start},n_{end}\in\{1,\dots,365\}\) defined as follow:

\[n_{end} - n_{start}\]

subject to :

\[n_{end} > n_{start}\]
\[\sum_{n\in\{n_{start},\dots,n_{end}\}} \mathbb{1}_{\bar{T}_{n}>T_{threshold}} \geq \sigma \cdot ( n_{end} - n_{start})\]

\(n_{start},n_{end}\) are found by testing all the combinations given that days \(n_{start} and :math:`n_{end}\) are hot days next to cold days.

Cold Water Temperature

heatpro.external_factors.process.temperature_cold_water.burch_cold_water(external_factors: ExternalFactors) → DataFrame[source]

Calculate the cold water temperature based on external factors using (Burch et al., 2007) approach.

Parameters:

external_factors (ExternalFactors) – External factors data containing temperatures.

Returns:

DataFrame containing the calculated cold water temperatures.

Return type:

pd.DataFrame

Overview

\[\begin{split}T^{(\text{Cold water})}_t = (\bar{T}^{(\text{External})} + 3) + ( 0.4 + 0.01 \cdot (0.01 \cdot(\bar{T}^{(\text{External})}-44)))\cdot\\ \frac{\Delta_{day}T^{(\text{External})}}{2} \cdot \sin(0.01745 \cdot (0.986(t.day - t_{\text{coldest day of year}} + 79 - \bar{T}^{(\text{External})})))\end{split}\]

where :

\(\underset{day}{\max} (\underset{t \in day}{\max}T^{(\text{External})} - \underset{t \in day}{\min}T^{(\text{External})})\) : Maximal amplitude in a day of the dataset.

\(\bar{T}^{(\text{External})}\) : Average external temperature over the dataset.

Departure Temperature

heatpro.external_factors.process.temperature_departure.basic_temperature_departure(external_factor: ExternalFactors, T_max_HS: float, T_max_NHS: float, T_min_HS: float, T_min_NHS: float, T_ext_mid: float, T_ext_min: float) → DataFrame[source]

Calculate basic temperature departure based on external factors.

Parameters:

  • external_factor (ExternalFactors) – External factors data.

  • T_max_HS (float) – Maximum temperature during the heating season.

  • T_max_NHS (float) – Maximum temperature during the non-heating season.

  • T_min_HS (float) – Minimum temperature during the heating season.

  • T_min_NHS (float) – Minimum temperature during the non-heating season.

  • T_ext_mid (float) – Intermediate external temperature threshold.

  • T_ext_min (float) – Minimum external temperature threshold.

Returns:

DataFrame containing the calculated basic temperature departure.

Return type:

pd.DataFrame

Overview

\[\begin{split}T^{(departure)}_t = \mathbb{1}_{T^{(ext)}_t<T^{(ext)}_{mid}} \frac{T^{(ext)}_t - T^{(ext)}_{mid}}{T^{(ext)}_{min} - T^{(ext)}_{mid}} \cdot (\mathbb{1}_{t \in HS}\cdot (T^{(departure)}_{HS,max} - T^{(departure)}_{HS,min}) + \\ \mathbb{1}_{t \in NHS}\cdot (T^{(departure)}_{NHS,max} - T^{(departure)}_{NHS,min})) + \mathbb{1}_{t \in HS}\cdot T^{(departure)}_{HS,min} + \mathbb{1}_{t \in NHS}\cdot T^{(departure)}_{NHS,min}\end{split}\]

Return Temperature

heatpro.external_factors.process.temperature_return.basic_temperature_return(external_factor: ExternalFactors, T_HS: float, T_NHS: float) → DataFrame[source]

Calculate basic return temperature based on external factors.

Parameters:

  • external_factor (ExternalFactors) – External factors data.

  • T_HS (float) – Return temperature during the heating season.

  • T_NHS (float) – Return temperature during the non-heating season.

Returns:

DataFrame containing the calculated basic return temperature.

Return type:

pd.DataFrame

Overview

\[T^{(return)}_t = \mathbb{1}_{t \in HS}\cdot T^{(return)}_{HS} + \mathbb{1}_{t \in NHS}\cdot T^{(return)}_{NHS}\]

Soil Temperature

heatpro.external_factors.process.temperature_soil.kasuda_soil_temperature(external_factor: ExternalFactors, d: float, alpha: float) → DataFrame[source]

Calculate Kasuda soil temperature based on external factors using (Kusada et al., 1965) approach.

Parameters:

  • external_factor (ExternalFactors) – External factors data.

  • d (float) – Depth of pipes (meter).

  • alpha (float) – thermal diffusivity of the soil (meter²/day)

Returns:

DataFrame containing the calculated Kasuda soil temperature.

Return type:

pd.DataFrame

Overview

\[\begin{split}T^{(\text{soil})}_t = \bar{T}^{(\text{External})} - \Delta_{month}T^{(\text{External})} \cdot \exp (-d\cdot \sqrt{\frac{\pi}{365 \cdot \alpha}}) \cdot \\ \cos(\frac{2\pi}{365}\cdot (t.day - t_{\text{coldest day of year}} - \frac{d}{2}\cdot \sqrt{\frac{\pi}{365 \cdot \alpha}}))\end{split}\]

where \(\Delta_{month}T^{(\text{External})}\) is the average monthly amplitude over the years.