UrbanHeatPro.Classes
UrbanHeatPro A. Molar-Cruz @ TUM ENS
Submodules
Package Contents
Classes
Initialize the Building object with the given parameters. |
|
City class. |
|
HotWaterDemand class constructor |
|
Initialize the UrbanHeatPro Simulation object. |
|
SpaceHeatingDemand.py |
- class UrbanHeatPro.Classes.Building(b, building_stock_stats, dt_vectors, resolution, number_of_typ_days, weights, Tamb, I, _space_heating, _hot_water, _energy_only, Tb0_str, dTset, dT_per_hour, eta, thermal_inertia, _active_population, _workday_weekend, sh_prob, _solar_gains, _internal_gains, _night_set_back, schedule_nsb, T_nsb, power_reduction, Tw, dhw_prob, hw_tank_limit, hw_flow, day_vector, seasonal_vector, min_vector, result_dir, plot, save, debug)[source]
Initialize the Building object with the given parameters.
- Parameters:
b – Building dataframe
building_stock_stats – Building stock statistics
dt_vectors – Vector of time steps as datetime objects
resolution – Temporal resolution in min
number_of_typ_days – Number of typical days
weights – Weights of typical days
Tamb – Ambient temperature vector in degC
I – Solar radiation vector in W/m2 [I_Gh, I_Dh, I_ex, hs]
_space_heating – Calculate space heating demand?
_hot_water – Calculate hot water demand?
_energy_only – Calculate only aggregated demand?
Tb0_str – Initial building temperature as string: ‘ambient’ or ‘Tset’
dTset – Delta temperature (for Tset_min, Tset_max)
dT_per_hour – Maximum dT allowed in building per hour [degC]
eta – Heating process efficiency
thermal_inertia – Thermal inertia of the heating system
_active_population – Consider active population for occupancy vector
_workday_weekend – Consider dif between workdays and weekends
sh_prob – Probability vector of using space heating
_solar_gains – Consider solar gains?
_internal_gains – Consider internal gains?
_night_set_back – Share of buildings with nsb
schedule_nsb – [start, end] of nsb in h
T_nsb – Night set-back temperature in degC
power_reduction – Percentage of power reduced (as decimal)
Tw – Hot water temperature in [degC]
dhw_prob – Probabilities for dhw-loads
hw_tank_limit – Hot water tank limit as perc (decimal)
hw_flow – Flow to refill hot water tank in L/min
day_vector – Vector of days in simulation time frame
seasonal_vector – Sinusoidal function for seasonal variations of DHW consumption
min_vector – Vector of simulation time steps in minutes
result_dir – Directory where results are stored
plot – Whether to plot the results or not
save – Whether to save the results or not
debug – Whether to print debug information or not
- calculate_space_heating_demand()[source]
Calculates building space heating demand as timeseries [W] and aggregated value [Wh]
- calculate_hot_water_demand(save_debug=False)[source]
Calculates building hot water demand as timeseries [W] and [m3] and aggregated value [Wh].
Only for residential buildings.
- Parameters:
save_debug (boolean) – Is debug file saved?
- Returns:
self.hot_water_m3 self.hot_water_power self.dhw_energy
- calculate_total_heat_demand()[source]
Agrregate the space heating and/or hot water demand time series. The total time series is delayed depending on the distance to the heat plant.
- calculate_delayed_timeseries(flow_vel=1.0)[source]
Delays vector of heat demand depending on the distance of the building centroid to the (geothermal) heat plant. A flow velocity of 1 m/s in the district heating network is considered.
- parametrize_building()[source]
Calculates missing building properties necessary for the heat demand calculation.
- update_building_refurbishment_level(ref_matrix_res, ref_matrix_nres)[source]
Updates building refurbishment level based on desired refurbishment level from scenario and max percentage of refurbished buildings in region (MAX_REF_RES and MAX_REF_NRES).
- Refurbishment levels according to TABULA typology:
1 National minimum requirement
2 Improved standard
3 Ambitious standard
- categorize_building_residential()[source]
Probabilistic categorization building according to TABULA typologies. Construction year class and building type are calculated by comparing the residential building gross floor area (footprint_area) with the FOOTPRINT of typical buildings (from TABULA). Values are adapted to fit building stock statistics.
- categorize_building_non_residential()[source]
Probabilistic categorization of non-residential buildings according to the building statistics and the following construction year classes:
int
construction year class
0
< 1918
1
1919 - 1976
2
1977 - 1983
3
1984 - 1994
4
> 1995
>> Source for building stock missing
- compute_current_refurbishment_level_residential()[source]
Computes the refurbishment level for the different building elements [roof, wall, floor, window] according to the current refurbishment statistics.
- Refurbishment levels according to TABULA typology:
1 National minimum requirement
2 Improved standard
3 Ambitious standard
- compute_current_refurbishment_level_non_residential()[source]
Computes the refurbishment level for the different building components [roof, wall, floor, window] according to the refurbishment statistics.
- Refurbishment levels according to TABULA typology:
1 National minimum requirement
2 Improved standard
3 Ambitious standard
>> Statistics on refurbishment in non-residential buildings missing
- compute_scenario_refurbishment_level_residential(ref_matrix_res)[source]
Computes the refurbishment level for the different building elements [roof, wall, floor, window] according to the scenario refurbishment level per typology and the maximum share of refurbished buildings (MAX_REF_RES).
- Refurbishment levels according to TABULA typology:
1 National minimum requirement
2 Improved standard
3 Ambitious standard
- compute_scenario_refurbishment_level_non_residential(ref_matrix_nres)[source]
Computes the refurbishment level for the different building elements [roof, wall, floor, window] according to the scenario refurbishment level per typology and the maximum share of refurbished buildings (MAX_REF_NRES).
- Refurbishment levels according to TABULA typology:
1 National minimum requirement
2 Improved standard
3 Ambitious standard
- calculate_areas_residential()[source]
Calculate storey area and heated/conditioned area based on definitions from VDI 3807.
- calculate_areas_non_residential()[source]
Calculate storey area and heated/conditioned area based on definitions from VDI 3807.
- calculate_number_of_floors_residential()[source]
Calculates number of floors based on the TABULA typology. The number of floors calculated from TABULA are referenced to the conditioned or heated area but the number of floors are calculated using the storey area.
- calculate_number_of_floors_non_residential(left=1, mode=2, right=3)[source]
Calculates number of floors as random sample number from the triangular distribution with lower limit left, peak at mode and upper limit right.
- >> Non-residential buildings are assumed to have two floors as mode and
a maximum of three floors Source missing
- calculate_number_of_dwellings()[source]
Calculates number of dwellings based on the building living area and mean dwelling size. It is assumed that SFH and TH have only 1 or 2 dwellings which is determined using the single-dwelling buildings statistics. For MFH and AB, the number of dweelings is calculated based on the average dwelling size.
- determine_dwelling_size_category()[source]
Determine dwelling size category based on statistics https://ergebnisse.zensus2011.de/#StaticContent:091840148148,GWZ_4_3_2,m,table
- calculate_number_of_occupants_residential()[source]
Calculates number of occupants based on household size and number of dwellings statistics.
- calculate_number_of_occupants_non_residential(capacity=0.1)[source]
Calculates random number of occupants in the building based on the recommended area per person for different building types from https://www.engineeringtoolbox.com/number-persons-buildings-d_118.html.
- get_building_thermal_properties_per_unit_area_residential()[source]
Gets building thermal properties from TABULA Web Tool data based on the building typology [year_class, btype]
- Sets the attributes:
list: u: [u_roof, u_wall, u_floor, u_window] in W/(K m2)
list: v: [v_usage, v_infiltration] in 1/h
list: c: [c_roof, c_wall, c_floor] in J/(K m2)
- get_building_thermal_properties_per_unit_area_non_residential()[source]
Gets building thermal properties based on: >> source missing
- Sets the following attributes:
u list: [u_roof, u_wall, u_floor, u_window] in W/(K m2)
v list: [v_usage, v_infiltration] in 1/h
c list: [c_roof, c_wall, c_floor] in J/(K m2)
- calculate_building_envelope_areas_residential()[source]
Calculates building envelope areas (wall, roof and window). Residential: areas are calculated according to building typologies in TABULA. Only the heated area is considered.
- calculate_building_envelope_areas_non_residential()[source]
Calculates building envelope areas (wall, roof and window).
Non-residential: number of floors and window-to-wall ratio are derived from statistics and used to calculate the building areas. Only the heated area is considered.
- calculate_building_window_areas()[source]
Calculate window areas in each direction to calculate solar gains.
- calculate_building_thermal_properties()[source]
Calculates equivalent U-value, thermal capacitance (C) and time constant (Tau) for the building. These properties are used in the first order thermal model.
- adjust_building_thermal_properties()[source]
Empirical adjustment of U-values to match TABULA results
- calculate_building_Tset()[source]
Derives a target temperature by choosing a random temperature from Tset_mean +/- dT. Values differ for different building types. From http://tc76.org/spc100/docs/IBP%2018599/18599-10.pdf
- calculate_building_active_hours()[source]
Assigns random start and end hours for building active hours. Values differ for different building types.
- Sets the following attributes:
self.active_hours list: [(start0, end0), (start1, end1)] in h
- calculate_daily_hot_water_demand()[source]
Returns the daily hot water demand by getting a random value from the cdf function based on the statistics from VDI 3807-3 (specific dhw demand in m3/m2 of living area)
- parametrize_hot_water_tank(X=1.5)[source]
Calculates size and initial state of hot water tank. Size is X times the calculated daily demand.
- calculate_building_activity_occupancy_vector()[source]
Calculate vector of activity in building, i.e. percentage of occupied dwellings (for space heating) Active_hours (scheduled), building occupancy and weekends are considered
- calculate_occupants_schedule()[source]
A schedule is assigned to every occupant based on studying/working schedule.
- Sets the following attributes:
occupant_vector: list = [dwelling, [occupant, [schedule]]] for occupant and dwelling in building
- calculate_annual_demand(data)[source]
Calculate the annual energy demand by weighting the heating demand of typical days
- plot_timeseries(space_heating=True, Tb=False, hot_water=True, total=True, xticks=('month', 3))[source]
Plots heat demand timeseries
- class UrbanHeatPro.Classes.City(NAME, SIMULATION, CITY, SPACE_HEATING, HOT_WATER, REPORTING)[source]
City class.
Note
This documentation might be incomplete or outdated, check the source code for more information. The types for the attributes might not be correct.
- b_to_save_syncity
Array to save synchronicity data.
- Type:
ndarray
- b_to_save_heat
Array to save heat data.
- Type:
ndarray
- base_load
Vector of base load in W.
- Type:
ndarray
Initializes the City object.
- Parameters:
NAME (str) – Name of the simulation.
SIMULATION (list) – List containing the parameters related to the simulation.
CITY (list) – List containing the parameters related to the city.
SPACE_HEATING (list) – List containing the parameters related to space heating demand.
HOT_WATER (list) – List containing the parameters related to hot water demand.
REPORTING (list) – List containing the parameters related to reporting.
- create_synthetic_city()[source]
Create a synthetic city representing the building stock based on statistics.
- update_synthetic_city(ref_matrix_res, ref_matrix_nres)[source]
Create a synthetic city representing the building stock based on statistics.
- call_create_synthetic_building(feederQueue, writerQueue)[source]
Calls function to create synthetic building
- call_update_synthetic_building(feederQueue, writerQueue)[source]
Calls function to update synthetic building. To update:
Refurbishment level
- create_synthetic_building(building)[source]
Creates building object and calculates missing building properties
- update_synthetic_building(building)[source]
Updates synthetic building. To update:
Refurbishment level
- calculate_city_heat_demand()[source]
Paralellizes the calculation of heating energy demand per building using a given number of processes. Every process modifies a shared dictionary where the heat demand is stored as power and energy.
- call_calculate_building_heat_demand(feederQueue, writerQueue)[source]
Calls function to calculate building heat demand
- calculate_building_heat_demand(building)[source]
Extracts building information needed to create a Building object. If the building is connected to the district heating network, then a Building object is created and the heat demand is calculted. If it is not, then the heat demand is set to zero.
- Parameters:
information (building dataframe with building) –
counter (iii building) –
- write_to_city_heat_demand(writerQueue, filename)[source]
Writes building properties and heat demand to file
- initialize_dhw_probabilities()[source]
Calculates dhw probabilities (daily consumption, event loads, flow rate and duration as interpolate objects.
- calculate_seasonal_variation_vector(amplitude=0.1, max_point=45)[source]
Creates a sine wave representing the change of the nominal consumption during the year due to the seasonal variation.
- calculate_day_vector()[source]
Calculates a vector of the days in the year included in the simulation time frame. Maximum length is 366.
- Returns:
- self.day_vector, list of day numbers in simulation time frame
with start and end indices
- Return type:
- calculate_min_vector()[source]
Calculates a vector of the simulation time steps in minutes of year. Maximum length is 366*24*60.
- Returns:
self.min_vector, list of time steps in minutes
- Return type:
- class UrbanHeatPro.Classes.HotWaterDemand(dt_vector, resolution, day_vector, seasonal_vector, activity_vector, Tw, daily_DHW, dhw_prob, hw_tank_capacity, hw_tank_limit, hw_tank_volume_t0, hw_flow, result_dir, use, year_class, btype, bid, debug, save_debug)[source]
HotWaterDemand class constructor
- Parameters:
dt_vector – Vector with datetime objects
resolution – Resolution in min
day_vector – Vector with day of year in simulation time frame
seasonal_vector – Vector with seasonal variation
activity_vector – Vector with building activity
Tw – Supply temperature of water in degC
daily_DHW – Mean daily hot water consumption [m3]
dhw_prob – DWH-loads probability
hw_tank_capacity – Hot water tank capacity in m3
hw_tank_limit – Hot water tank limit in percentage
hw_tank_volume_t0 – State of hot water tank in m3
hw_flow – Flow to refill hot water tank in L/min
result_dir – Result directory
use – Use of building
year_class – Year class
btype – Building type
bid – Building id
debug – Level of debug
save_debug – Whether to save debug files
- calculate()[source]
Calculates time series of domestic hot water demand in m3/min and W for the four dhw-load categories (0. Shower, 1. Bath, 2. Medium load and 3. Small load) for the whole simulation time.
- calculate_dhw_consumption_in_time_step(time_step, dt_vector_index, day, day_in_year)[source]
- Calculates hot water consumption events in every time step for the load categories:
0 shower 1 bath 2 medium load 3 small load
- Parameters:
object (time_step time step as datetime) –
dt_vector (dt_vector_index index of time step in simulation time frame) –
day_vector (day number of day in) –
year (day_in_year number of day in) –
- class UrbanHeatPro.Classes.Simulation(NAME, SIMULATION, CITY, SPACE_HEATING, HOT_WATER, REPORTING)[source]
Initialize the UrbanHeatPro Simulation object.
- Parameters:
NAME (str) – The name of the simulation.
SIMULATION (list) – A list containing the simulation parameters.
CITY (list) – A list containing the city parameters.
SPACE_HEATING (list) – A list containing the space heating parameters.
HOT_WATER (list) – A list containing the hot water parameters.
REPORTING (list) – A list containing the reporting options.
- read_raw_building_data()[source]
Reads building data from csv file. Returns a pd.DataFrame. Columns are renamed to variables in UrbanHeatPro.
- read_Tamb()[source]
Reads Tamb data from csv file. The file contains the Tamb values for the whole year in simulation resolution. Only the simulation timesteps are extracted.
- read_I()[source]
Reads solar radiation data from csv file. The file contains I values [W/m2] for the whole year in simulation resolution in the form [I_Gh, I_Dh, I_ex, hs]. Only the simulation timesteps are extracted.
- read_refurbishment_matrices()[source]
Reads refurbishment matrix for residential and non residential buildings for scenario simulated.
- prepare_result_directory(include_date=True)[source]
Creates a time stamped directory within the result folder. Returns path as string.
- read_data_from_csv(my_file, usecols=None)[source]
Uses numpy to read csv file and returns content as numpy array. Two rows of header are always skipped.
- calculate_typical_days()[source]
Calculates typical days based on Tamb timeseries. Based on Nahmmacher et al. (2016), Carpe diem: A novel approach to select representative days for long-term power system modeling.
- calculate_dt_vector()[source]
Calculates a vector of datetime objects based on the raw dt_matrix of the form [Y, M, D, h, m] and the simulation time steps.
- Returns:
self.dt_vector <list> List of datetime objects
- plot_power(space_heating=True, hot_water=True, total=True)[source]
Plot min, max, and mean power values for each time step.
- plot_energy(space_heating=True, hot_water=True, total=True)[source]
Plots histogram of aggregated heat demand for all simulations
- class UrbanHeatPro.Classes.SpaceHeatingDemand(dt_vector, resolution, heated_area, Tamb, I, Tb0, dT_per_hour, eta, thermal_intertia, U, V, C, Tset, dTset, activity_vector, occupancy_vector, sh_prob, _solar_gains, _internal_gains, _night_set_back, schedule_nsb, T_nsb, power_reduction, window_areas, coords, debug)
Initializes an instance of the SpaceHeatingDemand class.
- Parameters:
dt_vector – List of time steps as datetime objects.
resolution – Resolution in minutes.
heated_area – Heated area in square meters.
Tamb – Ambient temperature vector in degrees Celsius.
I – Solar radiation vector in W/m2.
Tb0 – Initial building temperature in degrees Celsius.
dT_per_hour – Maximum change in temperature allowed per hour in degrees Celsius.
eta – Heating process efficiency.
thermal_intertia – Thermal inertia of the heating system.
U – Building transmission losses in W/K.
V – Building ventilation losses in W/K.
C – Equivalent building thermal mass in J/K.
Tset – Set temperature or target temperature in degrees Celsius.
dTset – Delta temperature for Tset_min and Tset_max.
activity_vector – Building activity vector (0, 1).
occupancy_vector – Number of occupants in the building in each time step.
sh_prob – Probability vector of using space heating.
_solar_gains – Solar gains in W/m2.
_internal_gains – Internal gains in W/m2.
_night_set_back – Share of buildings with night set-back.
schedule_nsb – Start and end of night set-back in hours.
T_nsb – Night set-back temperature in degrees Celsius.
power_reduction – Percentage of power reduced (as decimal).
window_areas – Window area oriented to [E, S, W, N] in square meters.
coords – (latitude, longitude) of the building centroid.
debug – Debug flag.
- calculate()
Calculates the time series of space heating demand for a single building as the numerical solution of a first order building thermal model (1R1C). Transmission and ventilation losses through infiltration are included.
- Returns:
self.Tb self.sh_power self.internal_gains self.solar_gains
- calculate_Tset(iii)
Returns Tset to original value or recalculates it depending on night set-back
- calculate_flags(iii)
Calculates if heating system is active based on building temperature and building occupancy
- calculate_internal_gains(iii)
- Calculates heat gain in time step due to the activeness of the occupants:
80 W/occupant during the night (23:00 to 6:00)
Random between 100 - 125 W/occupant for the rest of the day
From Validation of RC Building Models for Application in Energy and DSM (Kuniyoshi, 2017) EESC Kramer [VDI 2078]
- Returns:
self.internal_gains[iii]: Heat gain in W
- Return type:
- calculate_solar_gains(iii, RED_FACTORS, ORIENTATION)
Calculates solar gains based on the windows size and orientation. Method adapted from TABULA
- Returns:
self.solar_gains[iii]: Heat gain in W
- Return type:
- calculate_incident_solar_irradiation(day_of_year, hour, I_Gh, I_Dh, I_ex, hs, lat, lon, slope, orientation)
Calculates the global incident solar irradiation on tilted surface in W/m2. Based on HDKR radiation model (anisotropic model) from High-resolution spatio-temporal matching of residential electricity consumption and PV power production at the urban scale (Molar-Cruz, 2015)
- Parameters:
I_Gh (float) – Global horizonal radiation in W/m2
I_Dh (float) – Diffuse horizontal radiation in W/m2
I_ex (float) – Extraterrestrial solar radiation in W/m2
hs (float) – Sun elevation angle in deg
lat (float) – Latitude in degrees
lon (float) – Longitude in degrees
slope (int) – Inclination angle of window. Vertical = 90 deg
orientation (int) – Window orientation
- Returns:
I_Gt: Incident global solar radiation on tilted surface
- Return type: