Command Line Interface 

How to use:

To use the command line interface, you need to install heatpro with cli option:

pip install heatpro[cli]

You can get help on how to use cli by using:

heatpro cold -h

Usage: heatpro cold [OPTIONS] WEATHER_CSV OUTPUT_CSV YEAR_ENERGY_REFERENCE

Options:
--set-temperature FLOAT         Default set temperature
--loss FLOAT                    Cold energy loss
-fws, --full-week-share FLOAT   Share of cold energy consummed following a
                                full week activity profile
-fwts, --full-week-temperature-sensitivity FLOAT
                                Share of cold energy within consumption
                                associated to full week profile consummed in
                                a temperature sensitive manner
-wets, --week-end-temperature-sensitivity FLOAT
                                Share of cold energy within consumption
                                associated to low activity on weekend
                                profile consummed in a temperature sensitive
                                manner
-start, --date-start TEXT       date start
-end, --date-end TEXT           date end
-v, --verbose                   Enable debug logging
-s, --show                      Show graphs of the result
-h, --help                      Show this message and exit.

Base example will be:

heatpro cold ./input/weather.csv ./output/results.csv H2

where ./input/weather.csv is a CSV file that look like this:

"timestamp_utc_num";"temperature";
978307200;5,1
978310800;5,1
978314400;5

Results will be written in output/results.csv.

Note

YEAR_ENERGY_REFERENCE can be a numeric value (energy expressed in kWh) but it can also be ‘H1’,’H2’ or ‘H3’. It will then used numeric values for ReferenceCold (see Helpers)

To filter calculation on a smaller sample, you can use -start and -end to filter on a smaller period. For instance, if my CSV weather file contains years from 2000 to 2199, using

heatpro cold ./input/weather.csv ./output/results.csv H2 -start 2005 -end 2010

Will calculate demand from beginning of 2005 to ending of 2009. It is usefull to launch short testing calculation.

you can use it with -s flag to display graphs of the calculation.

Cold 

Cold module for calculating cold-related energy consumption.

This module provides functionality to calculate cold-related energy consumption based on weather data and configuration parameters. It includes functions for importing weather data, calculating year average power, and applying cold configuration to generate consumption data.

The module uses pandas for data manipulation and analysis, and includes functions for calculating felt temperature and applying week profiles to the data.

class heatpro.cli.cold.ColdConfig(set_temperature: float = 22, loss: float = 0.2, profile: Repartition = <factory>, temperature_sensitivity: Repartition = <factory>)[source]

Bases: object

Configuration class for cold calculations.

set_temperature

Set temperature for cold calculation.

Type:: float

loss

Loss factor. Defaults to 0.2.

Type:: float

profile

Repartition profile. Defaults to Repartition().

Type:: Repartition

temperature_sensitivity

Temperature sensitivity profile. Defaults to Repartition().

Type:: Repartition

Raises:

ValueError – If the sum of profile values is not 1.0.
ValueError – If temperature_sensitivity values are not between 0 and 1.

loss: float = 0.2

profile: Repartition

set_temperature: float = 22

temperature_sensitivity: Repartition

class heatpro.cli.cold.Repartition(full_week: float = 0.5, working_day: float = 0.5)[source]

Bases: object

Class representing the repartition of values.

full_week

Value for full week. Defaults to 0.5.

Type:: float

working_day

Value for working fay. Defaults to 0.5.

Type:: float

full_week: float = 0.5

working_day: float = 0.5

heatpro.cli.cold.calculate_year_average_power(weather: Series, year_energy_reference: float, set_temperature: float) → Series[source]

Calculate the year average power based on weather data and a year energy reference.

Year energy reference will be the average year consumption over the all weather period given (it can be multiple years).

Mathematically, we define \(\mathcal{T}\) datetime index from weather.index, \(T_{ext}^t\) outdoor temperature from weather, \(E_{ref}\) year energy reference from year_energy_reference, \(T_{set}\) cooling set temperature in buildings from set_temperature,

We defined for a year math:y in mathcal{T} the average delta temperature during summer:

\[\Delta^{(y)} = \frac{1}{|\text{summer of }y|}\sum_{t\in \text{summer of }y} ( T_{ext}^{(t)}-T_{set} ) _+\]

The higher this value, the higher will be the cold energy demand.

We calculate the average over ther year of the average delta temperature during summer:

\[\Delta_{ref} = \frac{1}{\#\text{years in }\mathcal{T}}\sum_{y\in\mathcal{T}} \Delta^{(y)}\]

We can now estimate annual energy demand \(E^{(y)}\) for each year \(y\) using cross product:

\[E^{(y)} = \frac{E_{ref}}{\Delta_{ref}} \cdot \Delta^{(y)}\]

On average yearly demand will be \(E_{ref}\).

Eventually, average yearly power is calculated and return:

\[P^{(y)} = \frac{E^{(y)}}{|y|}\]

Parameters:

weather (pd.Series) – A pandas Series containing temperature data.
year_energy_reference (float) – Reference energy value for the year.
set_temperature (float) – Set temperature for cold calculation.

Returns:

A pandas Series containing the calculated year average power.

Return type:

pd.Series

Example

>>> year_avg_power = calculate_year_average_power(weather_data, 1000.0, 18.0)

heatpro.cli.cold.cold_pipeline(weather: Series, year_energy_reference: float, config: ColdConfig) → DataFrame[source]

Calculate cold-related energy consumption based on weather data and configuration.

Parameters:

weather (pd.Series) – A pandas Series containing temperature data.
year_energy_reference (float) – Reference energy value for the year.
config (ColdConfig) – Configuration object for cold calculations.

Returns:

A pandas DataFrame containing the calculated cold-related consumption.

Return type:

pd.DataFrame

Example

>>> config = ColdConfig(set_temperature=18.0)
>>> consumption_data = cold_cli(weather_data, 1000.0, config)

heatpro.cli.cold.import_weather(weather_csv: Path) → Series[source]

Import weather data from a CSV file.

CSV should look like this (more columns are allow but will be ignored):

"timestamp_utc_num";"temperature";
978307200;5,1
978310800;5,1
978314400;5

Parameters:: weather_csv (Path) – Path to the CSV file containing weather data.
Returns:: A pandas Series containing temperature (°C) at hourly frequency data indexed by timestamp.
Return type:: pd.Series

Example

>>> weather_data = import_weather(Path("./data/weather_data.csv"))

Helpers 

class heatpro.cli.helpers.ReferenceCold(*values)[source]

Bases: Enum

Yearly cold energy consumption in kWh for different French cities.

The values are categorized into three climate zones, with corresponding example cities and typical temperature ranges during the cooling season. These estimates are based on a total surface area of 144 hectares of tertiary buildings, evenly split between offices (50%) and commercial spaces (50%). The cooling temperature (TNC) is set to 22°C.

H1: Strasbourg (43,920,000 kWh) - Typical temperatures: 7-14°C
H2: Bordeaux (60,480,000 kWh) - Typical temperatures: 7-14°C
H3: Montpellier (102,240,000 kWh) - Typical temperatures: 7-14°C

These climate zones represent different levels of cold energy demand based on geographical location and climate characteristics in France.

H1

Yearly cold energy consumption for climate zone 1 (example: Strasbourg, typical temperatures 7-14°C)

Type:: int

H2

Yearly cold energy consumption for climate zone 2 (example: Bordeaux, typical temperatures 7-14°C)

Type:: int

H3

Yearly cold energy consumption for climate zone 3 (example: Montpellier, typical temperatures 7-14°C)

Type:: int

H1 = 43920000

H2 = 60480000

H3 = 102240000

Plotting 

heatpro.cli.plotting.cold_results(weather: Series, result: DataFrame) → Figure[source]

Create a Plotly figure showing cold consumption and outdoor temperature.

This function generates an interactive Plotly figure that displays the total cold consumption and daily outdoor temperature over time. The figure uses two y-axes to show both metrics on the same plot.

Parameters:

weather (pd.Series) – A pandas Series containing temperature data indexed by timestamp.
result (pd.DataFrame) – A pandas DataFrame containing cold consumption data with a ‘total_consumption_power’ column.

Returns:

A Plotly Figure object containing the visualization of cold consumption: and outdoor temperature.

Return type:

go.Figure

Command Line Interface

How to use:

Cold

Helpers

Plotting

Command Line Interface 

Cold 

Helpers 

Plotting 