Classes

districtgenerator.classes.datahandler

class districtgenerator.classes.datahandler.Datahandler

Bases: object

Handles data collection, processing, and simulation for urban building energy modeling.

This class integrates various sources of data, including site information, weather conditions, building configurations, and user behaviors. It generates realistic demand profiles for heating, domestic hot water, and electricity consumption.

Attributes:

• site (dict): Stores site-related data including weather and location.

• time (dict): Stores time-related parameters.

• district (list): A list containing all buildings.

• scenario_name (str or None): Name of the current scenario file being used.

• scenario (pd.DataFrame or None): DataFrame containing the scenario’s buildings parameters.

• counter (dict): Tracks unique building identifiers.

• srcPath (str): The base directory path of the project.

• filePath (str): The directory path where data files are stored.

• resultPath (str): The directory path where demand results are stored.

generateBuildings()

Loads building envelope and user data for each building in the district.

---

Parameters

• building features (dict): Contains building-specific data.

• number_of_floors (int): The number of floors in the building.

• height_of_floors (float): The height of each floor in the building.

Returns

• Creates and assigns building envelope data using the Envelope class.

• Generates and assigns user profiles for each building using the Users class.

• Computes design heat loads and assigns to each building.

generateDemands(calcUserProfiles=True, saveUserProfiles=True)

Generates cooling, heating, domestic hot water demand and household electricity demand profiles for each building.

---

Parameters

• calcUserProfiles (bool, optional): Determines whether to calculate new user profiles (True) or load

existing ones (False). Defaults to True. - saveUserProfiles (bool, optional): If True, saves calculated user profiles to the workspace. Only applicable if calcUserProfiles is True.

Returns

• Computes user behavior profiles for energy demand estimation.

• Cooling, heating, domestic hot water demand and household electricity demand profiles based on user behavior, envelope properties and site conditions.

generateDistrictComplete(scenario_name='example', calcUserProfiles=True, saveUserProfiles=True)

Executes the complete process of district generation, including environment setup, building initialization, envelope creation, and demand calculation.

generateEnvironment()

Loads and processes site and weather data for the simulation environment.

Parameters

• Site-specific data from site_data.json.

• Loads weather data (solar radiation and temperature) based on the selected TRY (Test Reference Year).

Returns

• Saving the interpolated data to the data handler.

initializeBuildings(scenario_name='example')

Initializes the district by loading building data from a scenario file.

---

Parameters

• scenario_name (str, optional): The name of the scenario file to be read. Defaults to ‘example’.

Returns

• Populates the district list with building objects containing their respective features.

loadDistrict(scenario_name='example')

Loads district data from a previously saved pickle file.

---

Parameters

• scenario_name (str, optional): The name of the scenario file to be loaded. Defaults to ‘example’.

Returns

• Restores the district data from the saved pickle file in the results directory.

saveDistrict()

Saves the district data as a pickle file for later use.

---

Returns

• Stores the current district data as a pickle file in the results directory.

districtgenerator.classes.envelope

class districtgenerator.classes.envelope.Envelope(prj, building_params, construction_type, file_path)

Bases: object

Abstract class for envelop component management handling

Attributes:

• prj (object): Instance of TEASER, contains functions to generate archetype buildings

• building_params (dict): building parameters like construction year, retrofit

• construction_type (str): building type

• file_path (str): file path

• id (int): building id

• construction_year (int): construction year of the building

• retrofit (str): retrofit of the building

calcHeatLoad(site, method='design')

Function to calculate the heat load of the building

Parameters

• site (dict): information about location and climate conditions

Returns

• Q_nHC (float): heat load

calcNormativeProperties(SunRad, internal_gains)

Function to thermal transmittance coefficient and heat flows

Parameters

• SunRad (array): solar radiation

• internal_gains (array): internal gains of the building

Returns

• thermal transmittance coefficients [W/K]

• heat flows [W]

loadAreas(prj)

Load component-specific area data

Parameters

• prj (object): contains component-specific area data

Returns

• A (dict): component-specific area data

loadComponentProperties(prj)

Load component-specific material parameters (attributes)

Parameters

• attributes (dict): component-specific material parameters

Returns

• specificHeatCapacity (float): specific heat capacity of each component

• U (dict): heat transfer coefficient of each component

loadMaterialID(mat_id, data_class)

Material loader by id.

Parameters

• mat_id (str): id of archetypes components

• data_class (dict): TABULA archetype’s material parameters

Returns

• name (string): material type

• density (float)density of the material

• thermal_conduc (florat): thermal conductivity

• heat_capac (float): heat capacity

• solar_absorp (float): solar adsorption

loadParams()

load physical and use-specific parameters

Parameters

• physics (json file): physical and use-specific parameters

Returns

• c_p_air (float): specific heat capacity of air [J/kgK]

• rho_air (float): density of air [kg/m3]

• T_set_min (float): minimum set temperature [°C]

• ventilationRate (float): ventilation rate [m3/h]

specificHeatCapacity(d, d_iso, density, cp)

Computation of (specific) heat capacity of each wall-type-surface (ISO 13786 A.2.4)

Parameters

• d (float): thickness of each layer in m

• d_iso (float): sum of all layer thicknesses in m

• density (float): density of each layer in kg/m3

• cp (float): heat capacity of each layer in J/kgK

Returns

• kappa(float): (specific) heat capacity of each wall-type-surface in J/m2K

districtgenerator.classes.profils

class districtgenerator.classes.profils.Profiles(number_occupants, initital_day, nb_days, time_resolution)

Bases: object

Profile class for calculating user related profiles of a building or flat

Attributes:

• number_occupants (int): Number of occupants who live in the house or flat.

• initial_day (int): Day of the week with which the generation starts 1-7 for monday-sunday.

• nb_days (int): Number of days for which a stochastic profile is generated.

• time_resolution (int): resolution of time steps of output array in seconds.

• activity_profile (array): Numpy-arry with acctive occupants 10-minutes-wise.

• occ_profile (array): stochastic occupancy profiles for a district

• app_load (array): Electric load profile of appliances in W.

• light_load (array):Electric load profile of lighting in W.

generate_activity_profile()

Generate a stochastic activity profile (on base of ridchardson.py).

Parameters

• number_occupants (int): Number of occupants who live in the house or flat.

• initial_day (int): Day of the week with which the generation starts. 1-7 for monday-sunday.

• nb_days (int): Number of days for which a stochastic profile is generated.

Returns

• activity_profile (array): Numpy-arry with acctive occupants 10-minutes-wise.

generate_dhw_profile()

Generate a stochastic dhw profile

Parameters

• time_resolution (int): resolution of time steps of output array in seconds.

• activity_profile (array): Numpy-arry with acctive occupants 10-minutes-wise.

• prob_profiles_dhw (array): probabilities of dhw usage

• initial_day (int): Day of the week with which the generation starts. 1-7 for monday-sunday.

Returns

• dhw_heat (array): Numpy-array with heat demand of dhw consumption in W.

generate_el_profile(irradiance, el_wrapper, annual_demand, do_normalization=True)

Generate electric load profile for one household

Parameters

• irradiance (array): if none is given default weather data (TRY 2015 Potsdam) is used

• el_wrapper (object): This objects holdes information about the lighting and appliance configuration.

• annual_demand (int): Annual elictricity demand in kWh.

• do_normalization (boolean): Normalize el. load profile to annual_demand

Returns

• loadcurve (array): Total electric load profile in W.

generate_gain_profile()

Generate profile of internal gains

Parameters

• personGain (float): Heat dissipation of one person

Source: SIA 2024/2015 D - Raumnutzungsdaten für Energie- und Gebäudetechnik - lightGain (float): share of waste heat (LED) Source: Elsland, Rainer ; Peksen, Ilhan ; Wietschel, Martin: Are Internal Heat Gains Underestimated in Thermal Performance Evaluation of Buildings? In: Energy Procedia 62 (2014), Januar, 32–41. - appGain (int): share of waste heat (assumed) Source: Elsland, Rainer ; Peksen, Ilhan ; Wietschel, Martin: Are Internal Heat Gains Underestimated in Thermal Performance Evaluation of Buildings? In: Energy Procedia 62 (2014), Januar, 32–41.

Returns

• gains (array): Internal gain of each flat

generate_occupancy_profiles()

Generate stochastic occupancy profiles for a district for calculating internal gains. Change time resolution of 10 min profiles to required resolution

Parameters

• time_resolution (int): resolution of time steps of output array in seconds.

• activity_profile (array): Numpy-arry with acctive occupants 10-minutes-wise.

Returns

• occ_profile (array): stochastic occupancy profile

loadProbabilitiesDhw()

Load probabilities of dhw usage

Parameters

• filename (str): Name of the file with the probabilities of dhw usage.

Returns

• prob_profiles_dhw (array): probabilities of dhw usage

districtgenerator.classes.solar

class districtgenerator.classes.solar.Sun(filePath)

Bases: object

Class for solar irradiance calulations

getGeometry(initialTime, timeDiscretization, timesteps, timeZone=1, location=(50.76, 6.07), altitude=0)

This function computes hour angle, declination, zenith angle of the sun and solar azimuth angle for a given location and time.

The implemented equations can be found in: Duffie, Beckman - Solar Engineering of Thermal Processes, 2013 (4th ed.)

Parameters

• initialTime (int): Time passed since January 1st, 00:00:00 in seconds

• timeDiscretization (int): Time between two consecutive time steps in seconds

• timesteps (int): Number of investigated / requested time steps

• timeZone (int): Shift between the location’s time and GMT in hours. CET would be 1.

• location (tuple): (latitude, longitude) of the simulated system’s position. Standard

values (50.76, 6.07) represent Aachen, Germany. - altitude (float): The locations altitude in meters

Returns

• omega (array): Hour angle. The angular displacement of the sun east or west of the

local meridian due to rotation of the earth on its axis at 15 degrees per hour; morning negative, afternoon positive - delta (array): Declination. The angular position of the sun at solar noon (i.e., when the sun is on the local meridian) with respect to the plane of the equator, north positive; −23.45 <= delta <= 23.45 - thetaZ (array): Zenith angle. The angle between the vertical and the line to the sun, that is, the angle of incidence of beam radiation on a horizontal surface; 0 <= thetaZ <= 90

getIncidenceAngle(beta, gamma, phi, omega, delta)

Compute the incidence angle on a tilted surface. All inputs/outputs are supposed to be in degrees!

Parameters

• beta (float): Slope, the angle (in degree) between the plane of the surface in

question and the horizontal. 0 <= beta <= 180. If beta > 90, the surface faces downwards. - gamma (float): Surface azimuth angle. The deviation of the projection on a horizontal plane of the normal to the surface from the local meridian, with zero due south, east negative, and west positive. -180 <= gamma <= 180 - phi (float): Latitude. North is positive, south negative. -90 <= phi <= 90 - omega (array): Hour angle. The angular displacement of the sun east or west of the local meridian due to rotation of the earth on its axis at 15 degrees per hour; morning negative, afternoon positive - delta (array): Declination. The angular position of the sun at solar noon (i.e., when the sun is on the local meridian) with respect to the plane of the equator, north positive; −23.45 <= delta <= 23.45

Returns

• incidence angle in radian

getSolarGains(initialTime, timeDiscretization, timeSteps, timeZone, location, altitude, beta, gamma, beam, diffuse, albedo)

Parameters

• initialTime (int): Time passed since January 1st, 00:00:00 in seconds

• timeDiscretization (int): Time between two consecutive time steps in seconds

• timesteps (int): Number of investigated / requested time steps

• timeZone (int): Shift between the location’s time and GMT in hours. CET would be 1.

• location (tuple): (latitude, longitude) of the simulated system’s position.

• altitude (float): The locations altitude in meters

• beta (list): Array of all slopes of building walls and roof.

A slope is the angle (in degree) between the plane of the surface in question and the horizontal. 0 <= beta <= 180. If beta > 90, the surface faces downwards. - gamma (list): Array of surface azimuth angles. The deviation of the projection on a horizontal plane of the normal to the surface from the local meridian, with zero due south, east negative, and west positive. -180 <= gamma <= 180 - beamRadiation (array): The solar radiation received from the sun without having been scattered by the atmosphere (also often named direct radiation) - diffuse (array): The solar radiation received from the sun after its direction has been changed by scattering by the atmosphere. - albedo (float): Ground reflectance. 0 <= albedo <= 1

Returns

• results (array): Solar radiation profiles for diffent all surface azimut angles in gamma.

getTotalRadiationTiltedSurface(theta, thetaZ, beamRadiation, diffuseRadiation, airmass, extraterrestrialIrradiance, beta, albedo)

Compute the total radiation on a tilted surface.

Parameters

• theta (array): Incidence angle.

• thetaZ (array): Zenith angle. The angle between the vertical and the line to the sun, that is, the angle

of incidence of beam radiation on a horizontal surface; 0 <= thetaZ <= 90 - beamRadiation (array): The solar radiation received from the sun without having been scattered by the atmosphere (also often named direct radiation) - diffuseRadiation (array_like): The solar radiation received from the sun after its direction has been changed by scattering by the atmosphere. - airmass (array): The ratio of the mass of atmosphere through which beam radiation passes to the mass it would pass through if the sun were at the zenith. Thus at sea level m=1 when the sun is at the zenith and m=2 for a zenith angle thetaZ=60 degrees. - extraterrestrialIrradiance (array_like): Extraterrestrial radiation incident on the plane normal to the radiation on the nth day of the year. - beta (float): Slope, the angle (in degree) between the plane of the surface in question and the horizontal. 0 <= beta <= 180. If beta > 90, the surface faces downwards. - albedo (float): Ground reflectance. 0 <= albedo <= 1

Returns

• total radiation on a tilted surface

districtgenerator.classes.users

class districtgenerator.classes.users.Users(building, area)

Bases: object

Building Users class describing the number of occupants and their configs

Attributes:

• building (object): buildings objects of TEASER project

• area (int): Floor area of different building types

• nb_flats (int): number of flats in building

• annual_el_demand (array): annual elictricity consumption in dependency of the building type and the number of occupants

• lighting_index (int): This index defines the lighting configuration of the houshold.

• el_wrapper (object): This objects holdes information about the lighting and appliance configuration.

• nc_occ (list): list with the number of occupants for each flat of the current building.

• occ (array): occupancy profile for each flat of the current building.

• dhw (array): drinking hot water profile for each building.

• elec (array): electrical demand for each building.

• gains (array): internal gains for each building.

• heat (array): heat demand for each building.

• cooling (array): cooling demand for each building.

calcHeatingProfile(site, envelope, time_resolution)

Calclulate heat demand for each building

Parameters

• site (dict): site data, e.g. weather

• envelope (object): containing all physical data of the envelope

• time_resolution (int): resolution of time steps of output array in seconds.

Returns

• Q_HC (float): Heating (positive) or cooling (negative) load for the current time step in Watt.

calcProfiles(site, time_resolution, time_horizon, initital_day=1)

Calclulate profiles for every flat and summarize them for the whole building

Parameters

• site (dict): site data, e.g. weather

• time_horizon (int): Time horizon for which a stochastic profile is generated.

• time_resolution (int): resolution of time steps of output array in seconds.

Returns

• occ (array): occupancy profile for each building.

• dhw (array): drinking hot water profile for each building.

• elec (array): electrical demand for each building.

• gains (array): internal gains for each building.

create_el_wrapper()

Creat a wrapper-object holding information about the lighting and appliance configuration.

Parameters

• annual_demand (int): Annual elictricity demand in kWh.

• light_config (int): This index defines the lighting configuration of the houshold.

There are 100 predifined ligthing configurations.

Returns

• el_wrapper (object): This objects holdes information about the lighting and appliance configuration

generate_annual_el_consumption()

Generate annual elictricity consumption in dependency of the building type and the number of occupants

Parameters

• standard_consumption : standard annual consumption in kWh (assumption)

Returns

• annual_el_demand (array): annual elictricity consumption in Wh for each flat of the current building

generate_lighting_index()

Choose a random lighting index between 0 and 99. This index defines the lighting configuration of the houshold. There are 100 predifined ligthing configurations.

Assumption: All lighting configurations are equally likely. No distinction between building types.

Parameters

• random_nb (float): random number in [0,1)

Returns

• lighting_index (int): This index defines the lighting configuration of the houshold.

generate_number_flats(area)

Generate number of flats for different of building types.

Parameters

• area (int): Floor area of different building types

Returns

• nb_flats (int): number of flats in building

generate_number_occupants()

Generate number of occupants for different of building types.

Parameters

• building (object): building type and number of flats

Returns

• nb_occ (list): list with the number of occupants for each flat of the current building.

loadProfiles(unique_name, path)

Load profiles from csv

Parameters

• unique_name (str): unique building name

• path (str): results path

Returns

• profiles assigned to the object

saveHeatingProfile(unique_name, path)

Save heat demand to csv

Parameters

• unique_name (str): unique building name

• path (str): results path

Returns

• csv files with heat demand

saveProfiles(unique_name, path)

Save profiles to csv

Parameters

• unique_name (str):unique building name

• path (str): results path

Returns

• csv files with profiles