model.py

Models.

CLASS	DESCRIPTION
Building	Information about the reference zone, inputs for the main thermal balance calculation.
ClimateData	Hourly climate datasets
WindowDesign	Window design input data.

Building

Building(bui_type, ceiling_to_floor_height, envelope_area, floor_area, fenestration_area, orientation, comfort_requirements, max_outdoor_rel_hum_accepted, u_value_opaque, u_value_fen, construction_mass, g_value_glazing_sys, shading_control_setpoint, shading_factor, time_control_on, time_control_off, ti_day_start=7, ti_night_start=23, ti_hsb=15, ti_csb=50, my_min_req_vent_rate=None, my_vent_rates_mu=VENT_RATES_MU[0], my_lighting_power_density=None, my_el_equipment_power_density=None, my_occupancy_gains_density=None, my_c_int=None)

Bases: object

Information about the reference zone, inputs for the main thermal balance calculation.

Objects of this class should be managed immutably throughout the simulation.

PARAMETER	DESCRIPTION
bui_type	Building type. TYPE: Literal['Apartment building', 'Daycare center', 'Detached house', 'Hospital', 'Hotel', 'Office', 'Restaurant', 'School']
ceiling_to_floor_height	Ceiling to floor height; H (m). The net room height to calculate net room air volume V = H * S TYPE: (float, required)
envelope_area	Envelope area; Ae (m²). The sum of walls, windows, ceiling and floor area with outdoor boundary conditions. This area, multiplied by the average thermal trasmittance, is used to estimate the transmission. TYPE: (float, required)
floor_area	Floor area; Af (m²). The net floor area of the room to calculate net room air volume V = H * S and internal gains. TYPE: (float, required)
fenestration_area	Fenestration area; Ag (m²). The glazing area on envelope used for the estimation of solar gains. TYPE: (float, required)
orientation	Fenestration orientation is the direction the window faces, expressed relative to the cardinal directions. TYPE: Literal['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW']
comfort_requirements	Comfort requirements. Comfort requirements refer to the comfort categories defined by the EN 16798:1-2019 standard. Reccomended input values given for each of the different comfort categories are included in the tool and automatically selected. TYPE: Literal['category I', 'category II', 'category III']
max_outdoor_rel_hum_accepted	Max. outdoor relative humidity accepted; RHmax (%). TYPE: (float, required)
u_value_opaque	U-value of the opaque envelope; Uo (W/m²K). Average thermal transmittance of the opaque surfaces (wall, roof, floor) with outdoor boundary conditions. TYPE: (float, required)
u_value_fen	U-value of the fenestration; Uw (W/m²K). Thermal transmittance of the window (or average thermal transmittance of windows if the room has more than one window), considering both glazing system and frame. TYPE: (float, required)
construction_mass	Predefined thermal mass of the construction. Heavy = 1.4 MJ/m³K, light = 0.9 MJ/m³K and medium = 1.15 MJ/m³K TYPE: Literal['heavy', 'light', 'medium']
g_value_glazing_sys	g value of the glazing system; g. Solar energy transmittance of the glazing system. TYPE: (float, required)
shading_control_setpoint	Shading control setpoint; Shd (W/m²). Shading is on if the specific beam plus diffuse solar radiation incident on the window exceeds this setpoint value (generally is between 40 and 150 W/m²). TYPE: (float, required)
shading_factor	Shading factor; Y: Shading factor due to exterior shading element (i.e. shutter, venetian blinds, roll up blinds..). TYPE: (float, required)
time_control_on	Time control on; ton; min 0, max 24. TYPE: (int, required)
time_control_off	Time control off; toff; min 0, max 24. TYPE: (int, required)
ti_day_start	The hour of the day at which the heating or cooling setpoint temperature becomes active. es: from 23:00 to 7:00 -> Ti_hsp_night, from 7:00 to 23:00 -> Ti_hsp_day TYPE: int DEFAULT: 7:00
ti_night_start	The hour of the day at which the heating or cooling setback temperature becomes active overwriting the setpoint temperature. It marks the start of the period during which the indoor temperature is allowed to deviate from the heating or cooling setpoint to a reduced (setback) level. NB! error in excel formula: ti_night_start = 24 TYPE: int DEFAULT: 23:00
my_min_req_vent_rate	Custom min required ventilation rates (otherwise it is obtained from other inputs). Minimum required air change rates (l/s-m²) calculated according to IEQ standard (EN 16798:1-2019) or design requirements to determine the ventilation losses within the energy balance of the reference room. It can include infiltration rates. TYPE: float DEFAULT: None
my_vent_rates_mu	Unit of measurement for my_min_req_vent_rate, according to which is defined the value of property min_req_vent_rate. TYPE: Literal['l/s-m²', '1/h', 'kg/s-m²', 'm³/h', 'm³/s'] DEFAULT: VENT_RATES_MU[0]
my_lighting_power_density	Custom lighting power density (otherwise it is calculated from other inputs). The maximum lighting level per floor area. Internal gains due to lighting are calculated by multiplying the lighting power by the pre-defined load profiles. TYPE: float DEFAULT: None
my_el_equipment_power_density	Custom electric equipment power density (otherwise it is obtained from other inputs); Qel_equip (W/m²). The maximum elecric eqipment level per floor area. Internal gains due to electric equipment are calculated by multiplying the lighting power by the pre-defined load profiles. TYPE: float DEFAULT: None
my_occupancy_gains_density	Custom occupancy density (otherwise it is obtained from other inputs); Qpeople (W/m²). The maximum floor area per person. Internal gains due to people are calculated by multiplying the maximum number of person by the pre-defined occupancy profiles. TYPE: float DEFAULT: None
my_c_int	Cint. is the (lumped) internal thermal capacity (J/K). Otherwise it is obtained from other inputs. TYPE: float DEFAULT: None

ATTRIBUTE	DESCRIPTION
average_u_value	Average U Value of opaque and glazed envelope; Uavg (W/m²K).
c_int	Cint. is the (lumped) internal thermal capacity (J/K).
el_equipment_power_density	Electric equipment power density; Qel_equip (W/m²).
lighting_power_density	Lighting power density; Qlight (W/m²).
min_req_vent_rate	Min. required ventilation rates.
nr_of_occupied_hrs	Nr of occupied hours over the day.
occupancy_gains_density	Occupancy density; Qpeople (person/m²).
room_volume	Room volume; V (m³).

Source code in src/venticoolpy/model.py

def __init__(
    self,
    bui_type: Literal["Apartment building", "Daycare center", "Detached house", "Hospital", "Hotel", "Office", "Restaurant", "School"],
    ceiling_to_floor_height,
    envelope_area,
    floor_area,
    fenestration_area,
    orientation: Literal['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'],
    comfort_requirements: Literal["category I", "category II", "category III"],
    max_outdoor_rel_hum_accepted,
    u_value_opaque,
    u_value_fen,
    construction_mass: Literal["heavy", "light", "medium"],
    g_value_glazing_sys,
    shading_control_setpoint,
    shading_factor,
    time_control_on,
    time_control_off,
    ti_day_start=7,
    ti_night_start=23,
    ti_hsb=15,
    ti_csb=50,
    my_min_req_vent_rate=None, 
    my_vent_rates_mu: Literal["l/s-m²", "1/h", "kg/s-m²", "m³/h", "m³/s"] = VENT_RATES_MU[0],
    my_lighting_power_density=None,
    my_el_equipment_power_density=None,
    my_occupancy_gains_density=None,
    my_c_int=None,
):
    self.bui_type = bui_type
    self.ceiling_to_floor_height = ceiling_to_floor_height
    self.envelope_area = envelope_area
    self.floor_area = floor_area
    self.fenestration_area = fenestration_area
    self.orientation = orientation
    self.comfort_requirements = comfort_requirements
    self.max_outdoor_rel_hum_accepted = max_outdoor_rel_hum_accepted
    self.u_value_opaque = u_value_opaque
    self.u_value_fen = u_value_fen
    self.construction_mass = construction_mass
    self.g_value_glazing_sys = g_value_glazing_sys
    self.shading_control_setpoint = shading_control_setpoint
    self.shading_factor = shading_factor
    self.time_control_on = time_control_on
    self.time_control_off = time_control_off
    self.ti_hsb = ti_hsb
    self.ti_csb = ti_csb

    self.ti_day_start = ti_day_start  
    self.ti_night_start = ti_night_start  
    self.my_min_req_vent_rate=my_min_req_vent_rate
    self.my_vent_rates_mu = my_vent_rates_mu 
    self.my_lighting_power_density=my_lighting_power_density
    self.my_el_equipment_power_density=my_el_equipment_power_density
    self.my_occupancy_gains_density=my_occupancy_gains_density
    self.my_c_int=my_c_int

    if (
        bui_type not in BUILDING_TYPE
        or orientation not in ORIENTATION
        or comfort_requirements not in COMFORT_REQUIREMENTS
        or construction_mass not in CONSTRUCTION_MASS
        or (my_vent_rates_mu is not None and my_vent_rates_mu not in VENT_RATES_MU)
    ):
        raise BuildingCreateException

average_u_value property

average_u_value

Average U Value of opaque and glazed envelope; Uavg (W/m²K).

c_int property

c_int

Cint. is the (lumped) internal thermal capacity (J/K).

el_equipment_power_density property

el_equipment_power_density

Electric equipment power density; Qel_equip (W/m²).

The maximum elecric eqipment level per floor area. Internal gains due to electric equipment are calculated by multiplying the lighting power by the pre-defined load profiles.

lighting_power_density property

lighting_power_density

Lighting power density; Qlight (W/m²).

The maximum lighting level per floor area. Internal gains due to lighting are calculated by multiplying the lighting power by the pre-defined load profiles.

min_req_vent_rate property

min_req_vent_rate

Min. required ventilation rates. Minimum required air change rates (l/s-m²) calculated according to IEQ standard (EN 16798:1-2019) or design requirements to determine the ventilation losses within the energy balance of the reference room.

nr_of_occupied_hrs property

nr_of_occupied_hrs

Nr of occupied hours over the day.

occupancy_gains_density property

occupancy_gains_density

Occupancy density; Qpeople (person/m²).

The maximum floor area per person. Internal gains due to people are calculated by multiplying the maximum number of person by the pre-defined occupancy profiles.

room_volume property

room_volume

Room volume; V (m³).

ClimateData

ClimateData(df_outdoor_dry_bulb_temperature, df_relative_humidity_outdoor_air, df_isol_tot)

Hourly climate datasets

Source code in src/venticoolpy/model.py

def __init__(
    self,
    df_outdoor_dry_bulb_temperature,
    df_relative_humidity_outdoor_air,
    df_isol_tot,
):
    self.df_outdoor_dry_bulb_temperature=df_outdoor_dry_bulb_temperature
    self.df_relative_humidity_outdoor_air=df_relative_humidity_outdoor_air
    self.df_isol_tot=df_isol_tot

WindowDesign

WindowDesign(room_depth, ventilation_strategy, window_opening_type, window_maximum_opening_angle, window_opening_discharge_coeff, indoor_temperature, indoor_outdoor_temperature_diff, wind_speed, has_insect_screen, stack_height, wind_pressure_coeff_window_1, wind_pressure_coefficient_window_2)

Bases: object

Window design input data.

Room depth: distance between the window and the opposite wall; D (m). Ventilation strategy: ventilation strategy to be applied for the estimation of the ventilation rate and ventilation losses. It can be natural, mechanical or mixed ventilation. Select window opening type: the type of window opening to be applied for the estimation of the ventilation rate and ventilation losses. It can be top hung, side hung, awning, pivot, roof window, sliding or fixed. Window maximum opening angle: the maximum opening angle of the window, which is used for the estimation of the ventilation rate and ventilation losses. It can be between 0° and 90°. Window opening discharge coefficient: the discharge coefficient of the window opening, which is used for the estimation of the ventilation rate and ventilation losses. It can be between 0 and 1. Indoor temperature: the indoor temperature, which is used for the estimation of the ventilation rate and ventilation losses. It can be between 15°C and 30°C. Indoor-outdoor temperature difference: the difference between the indoor and outdoor temperature, which is used for the estimation of the ventilation rate and ventilation losses. It can be between 0°C and 20°C. Wind speed: the wind speed, which is used for the estimation of the ventilation rate and ventilation losses. It can be between 0 m/s and 20 m/s. Insect screen: whether the window has an insect screen or not, which is used for the estimation of the ventilation rate and ventilation losses. It can be either yes or no. Stack height - vertical distance between 2 openings: the window and the opposite wall; Hs (m). Wind pressure coefficient - window 1: the wind pressure coefficient of the window, which is used for the estimation of the ventilation rate and ventilation losses. It can be between -1 and 1. Wind pressure coefficient - window 2: the wind pressure coefficient of the opposite wall, which is used for the estimation of the ventilation rate and ventilation losses. It can be between -1 and 1.

Collect all data needed for Windows Design simulation.

ATTRIBUTE	DESCRIPTION
indoor_temperature_K	Convert Indoor temperature from C to K

Source code in src/venticoolpy/model.py

def __init__(
    self,
    room_depth,
    ventilation_strategy,
    window_opening_type,  # add const for window opending type
    window_maximum_opening_angle,
    window_opening_discharge_coeff,
    indoor_temperature,
    indoor_outdoor_temperature_diff,
    wind_speed,
    has_insect_screen,
    stack_height,
    wind_pressure_coeff_window_1,
    wind_pressure_coefficient_window_2,
):
    """Collect all data needed for Windows Design simulation."""
    self.room_depth = room_depth
    self.ventilation_strategy = ventilation_strategy
    self.window_opening_type = window_opening_type
    self.window_maximum_opening_angle = window_maximum_opening_angle
    self.window_opening_discharge_coeff = window_opening_discharge_coeff
    self.indoor_temperature = indoor_temperature
    self.indoor_outdoor_temperature_diff = indoor_outdoor_temperature_diff
    self.wind_speed = wind_speed
    self.has_insect_screen = has_insect_screen
    self.stack_height = stack_height
    self.wind_pressure_coeff_window_1 = wind_pressure_coeff_window_1
    self.wind_pressure_coefficient_window_2 = wind_pressure_coefficient_window_2

    if (
        ventilation_strategy not in VENTILATION_STRATEGY
        or window_opening_type not in WINDOW_OPENING_TYPE
    ):
        raise WindowDesignCreateException

indoor_temperature_K property

indoor_temperature_K

Convert Indoor temperature from C to K