calculation.py

Ventilative Cooling Potential simulation functions.

FUNCTION	DESCRIPTION
calc_free_float_mode	Perform the calculation of time series in free float temperature mode.
calc_heating_and_cooling_needs_no_vcs	Perform the second set of calculations (Heating and Cooling needs, no VCS).
calc_heating_and_cooling_needs_with_vcs	Perform the third set of calculations (Heating and Cooling needs, with VCS).
calc_thermal_comfort_data	Calculate Thermal comfort data.
get_annual_data	Heating [kWh]
get_gains	Calculate solar and internal gains.
get_internal_gains	Retrieve internal gains according to building type
get_outdoor_climate_data	Retrieve outdoor climate data.
get_requirend_frequency_air_change_rate	Frequency of air change rate required to provide potential comfort.
get_simulation_year	Create a DataFrame for a sumulation.
get_vent_mode_over_year	Calculate Ventilative mode over year given results of VCT simulation.
get_ventilation_rate	Calculate Ventilation rates.
run_vct_simulation	Perform main VCT simulation.

calc_free_float_mode

calc_free_float_mode(building, c_int, vent_rate_m3_s, solar_gains, internal_gains, outdoor_dry_bulb_temp)

Perform the calculation of time series in free float temperature mode.

PARAMETER	DESCRIPTION
building	TYPE: A class:`Building` instance
c_int	total heat capacity of the reference room [J/K] TYPE: float
vent_rate_m3_s	A list with hourly values of ventilation rate [m³/s] TYPE: array-like of float, re
solar_gains	A list with hourly values of solar gains TYPE: array-like of float
internal_gains	A list with hourly values of internal gains TYPE: array-like of float
outdoor_dry_bulb_temp	A list with hourly values of Outdoor dry bulb temperature TYPE: array-like of float
All

RETURNS	DESCRIPTION
DataFrame	DataFrame with hourly values of: At [W/K] Bt [W] Internal temperature free float. ϴint;0;t [°C] Internal temperature calculated. ϴint;t [°C]

Source code in src/venticoolpy/calculation.py

def calc_free_float_mode(
    building: Building,
    c_int,  # TODO: change name
    vent_rate_m3_s,
    solar_gains,
    internal_gains,
    outdoor_dry_bulb_temp,
) -> pd.DataFrame:
    """Perform the calculation of time series in free float temperature mode.

    Parameters
    ----------
    building : A class:`Building` instance
    c_int : float
        total heat capacity of the reference room [J/K]
    vent_rate_m3_s : array-like of float, re
        A list with hourly values of ventilation rate [m³/s]
    solar_gains : array-like of float 
        A list with hourly values of solar gains
    internal_gains : array-like of float
        A list with hourly values of internal gains
    outdoor_dry_bulb_temp : array-like of float
        A list with hourly values of Outdoor dry bulb temperature

    All parameters (except building) are the outputs of the previous steps.

    Returns
    -------
    pd.DataFrame
        DataFrame with hourly values of:

        - At [W/K]
        - Bt [W]
        - Internal temperature free float.  ϴint;0;t [°C]
        - Internal temperature calculated.  ϴint;t [°C]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    a_t = (
        c_int / 3600
        + (Air_properties_Cp * Air_properties_ro * vent_rate_m3_s)
        + building.average_u_value * building.envelope_area
    )

    internal_temperature_free_float = [None] * TOT_HOURS
    b_t = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        if i == 0:
            internal_temperature_free_float[0] = 20  # set first value

            b_t[0] = (
                c_int / 3600 * internal_temperature_free_float[0]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[0]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[0]
                + (solar_gains[0] + internal_gains[0]) * building.floor_area
            )
        else:
            b_t[i] = (
                c_int / 3600 * internal_temperature_free_float[i - 1]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[i]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[i]
                + (solar_gains[i] + internal_gains[i]) * building.floor_area
            )

            internal_temperature_free_float[i] = b_t[i] / a_t[i]

    df["At"] = a_t
    df["Bt"] = b_t
    df["Internal temperature free float"] = internal_temperature_free_float
    df["Internal temperature calculated"] = internal_temperature_free_float

    return df

calc_heating_and_cooling_needs_no_vcs

calc_heating_and_cooling_needs_no_vcs(building, c_int, vent_rate_m3_s, solar_gains, internal_gains, outdoor_dry_bulb_temp, a_t, lower_comfort_zone_limit, upper_comfort_zone_limit)

Perform the second set of calculations (Heating and Cooling needs, no VCS).

PARAMETER	DESCRIPTION
building	TYPE: A class:`Building` instance
c_int	total heat capacity of the reference room [J/K] TYPE: float
vent_rate_m3_s	A list with hourly values of ventilation rate [m³/s] TYPE: array-like of float
solar_gains	A list with hourly values of solar gains TYPE: array-like of float
internal_gains	A list with hourly values of internal gains TYPE: array-like of float
outdoor_dry_bulb_temp	A list with hourly values of Outdoor dry bulb temperature TYPE: array-like of float
a_t	A list with hourly values of At TYPE: array-like of float
lower_comfort_zone_limit	A list with hourly values of Lower comfort zone limit TYPE: array-like of float
upper_comfort_zone_limit	A list with hourly values of Upper comfort zone limit TYPE: array-like of float
All

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly values of: Ventilation rate. qV;t [m3/s] At [W/K] Bt [W] Internal temperature free float. ϴint;0;t [°C] Heating or cooling load. ΦHC;t [W] Internal temperature calculated. ϴint;t [°C]

Source code in src/venticoolpy/calculation.py

def calc_heating_and_cooling_needs_no_vcs(
    building: Building,
    c_int,
    vent_rate_m3_s,
    solar_gains,
    internal_gains,
    outdoor_dry_bulb_temp,
    a_t,
    lower_comfort_zone_limit,
    upper_comfort_zone_limit,
) -> pd.DataFrame:
    """Perform the second set of calculations (Heating and Cooling needs, no VCS).

    Parameters
    ----------
    building : A class:`Building` instance
    c_int : float
        total heat capacity of the reference room [J/K]
    vent_rate_m3_s : array-like of float
        A list with hourly values of ventilation rate [m³/s]
    solar_gains : array-like of float
        A list with hourly values of solar gains
    internal_gains : array-like of float
        A list with hourly values of internal gains
    outdoor_dry_bulb_temp : array-like of float
        A list with hourly values of Outdoor dry bulb temperature
    a_t : array-like of float
        A list with hourly values of At
    lower_comfort_zone_limit : array-like of float
        A list with hourly values of Lower comfort zone limit
    upper_comfort_zone_limit : array-like of float
        A list with hourly values of Upper comfort zone limit


    All parameters (except building) are the outputs of the previous steps.

    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Ventilation rate.  qV;t [m3/s]
            - At  [W/K]
            - Bt  [W]
            - Internal temperature free float.  ϴint;0;t [°C]
            - Heating or cooling load.  ΦHC;t [W]
            - Internal temperature calculated.  ϴint;t [°C]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    bt_no_vcs = [None] * TOT_HOURS
    internal_temperature_free_float_no_vcs = [None] * TOT_HOURS
    heating_cooling_load = [None] * TOT_HOURS
    internal_temperature_calc = [None] * TOT_HOURS

    for i in range(TOT_HOURS):
        if i == 0:
            internal_temperature_free_float_no_vcs[0] = 20
            bt_no_vcs[0] = (
                c_int / 3600 * internal_temperature_free_float_no_vcs[0]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[0]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[0]
                + (solar_gains[0] + internal_gains[0]) * building.floor_area
            )

        else:
            bt_no_vcs[i] = (
                c_int / 3600 * internal_temperature_calc[i - 1]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[i]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[i]
                + (solar_gains[i] + internal_gains[i]) * building.floor_area
            )

            internal_temperature_free_float_no_vcs[i] = bt_no_vcs[i] / a_t[i]

        if internal_temperature_free_float_no_vcs[i] < lower_comfort_zone_limit[i]:
            heating_cooling_load[i] = a_t[i] * lower_comfort_zone_limit[i] - bt_no_vcs[i]
        elif (
            internal_temperature_free_float_no_vcs[i] >= lower_comfort_zone_limit[i]
            and internal_temperature_free_float_no_vcs[i] <= upper_comfort_zone_limit[i]
        ):
            heating_cooling_load[i] = 0
        elif internal_temperature_free_float_no_vcs[i] > upper_comfort_zone_limit[i]:
            heating_cooling_load[i] = a_t[i] * upper_comfort_zone_limit[i] - bt_no_vcs[i]

        internal_temperature_calc[i] = (bt_no_vcs[i] + heating_cooling_load[i]) / a_t[i]

    df["Ventilation rate.1"] = vent_rate_m3_s
    df["At.1"] = a_t
    df["Bt.1"] = bt_no_vcs
    df["Internal temperature free float.1"] = internal_temperature_free_float_no_vcs
    df["Heating or cooling load"] = heating_cooling_load
    df["Internal temperature calculated.1"] = internal_temperature_calc

    return df

calc_heating_and_cooling_needs_with_vcs

calc_heating_and_cooling_needs_with_vcs(building, c_int, vent_rate_m3_s, solar_gains, internal_gains, outdoor_dry_bulb_temp, a_t, lower_comfort_zone_limit, upper_comfort_zone_limit, relative_humidity_of_outdoor_air, heating_cooling_load, time)

Perform the third set of calculations (Heating and Cooling needs, with VCS).

PARAMETER	DESCRIPTION
building	TYPE: A class:`Building` instance
vent_rate_m3_s	A list with hourly values of ventilation rate [m³/s] TYPE: array-like of float
solar_gains	A list with hourly values of solar gains TYPE: array-like of float
internal_gains	A list with hourly values of internal gains TYPE: array-like of float
outdoor_dry_bulb_temp	A list with hourly values of Outdoor dry bulb temperature TYPE: array-like of float
a_t	A list with hourly values of At TYPE: array-like of float
lower_comfort_zone_limit	A list with hourly values of Lower comfort zone limit TYPE: array-like of float
upper_comfort_zone_limit	A list with hourly values of Upper comfort zone limit TYPE: array-like of float
relative_humidity_of_outdoor_air	A list with hourly values of Relative humidity of outdoor air TYPE: array-like of float
heating_cooling_load	A list with hourly values of Heating or cooling load TYPE: array-like of float
time	A list with hourly values. A set of (1, 2, .., 24) for each day of simulation TYPE: array-like of int
All

RETURNS

DESCRIPTION

pd.DataFrame

A DataFrame with hourly values of: Ventilation rate without VCS. qV;t [m3/s] At [W/K] Bt [W] Internal temperature free float. ϴint;0;t [°C] Heating or cooling load "step 2". ΦHC;step2;t [W] Internal temperature calculated "Step2". ϴint;step2;t [°C] VC mode Required cooling ventilation rate (VC mode 1 or 2). ΔqV;vcs;req;t [m3/s] Actual ventilation rate. qV;vcs;t [m3/s] Avcs;t [W/K] Bvcs;t [W] Internal temperature free float. ϴint;0;t [°C] Heating or cooling load. ΦHC;vcs;t [W] Internal temperature calculated. ϴint;vcs;t [°C] HC load difference. ΔΦHC;vcs;t [W] Target indoor temperature for VCS. ϴint;set;vcs;t [°C]

Source code in src/venticoolpy/calculation.py

def calc_heating_and_cooling_needs_with_vcs(
    building: Building,
    c_int,
    vent_rate_m3_s,
    solar_gains,
    internal_gains,
    outdoor_dry_bulb_temp,
    a_t,
    lower_comfort_zone_limit,
    upper_comfort_zone_limit,
    relative_humidity_of_outdoor_air,
    heating_cooling_load,
    time,
) -> pd.DataFrame:
    """Perform the third set of calculations (Heating and Cooling needs, with VCS).

    Parameters
    ----------
    building : A class:`Building` instance
    vent_rate_m3_s : array-like of float
        A list with hourly values of ventilation rate [m³/s]
    solar_gains : array-like of float
        A list with hourly values of solar gains
    internal_gains : array-like of float
        A list with hourly values of internal gains
    outdoor_dry_bulb_temp : array-like of float
        A list with hourly values of Outdoor dry bulb temperature
    a_t : array-like of float
        A list with hourly values of At
    lower_comfort_zone_limit : array-like of float
        A list with hourly values of Lower comfort zone limit
    upper_comfort_zone_limit : array-like of float
        A list with hourly values of Upper comfort zone limit
    relative_humidity_of_outdoor_air : array-like of float
        A list with hourly values of Relative humidity of outdoor air
    heating_cooling_load : array-like of float
        A list with hourly values of Heating or cooling load
    time : array-like of int
        A list with hourly values. A set of (1, 2, .., 24) for each day of simulation

    All parameters (except building) are the outputs of the previous steps.

    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Ventilation rate without VCS.  qV;t [m3/s]
            - At  [W/K]
            - Bt  [W]
            - Internal temperature free float.  ϴint;0;t [°C]
            - Heating or cooling load "step 2".  ΦHC;step2;t [W]
            - Internal temperature calculated "Step2".  ϴint;step2;t [°C]
            - VC mode
            - Required cooling ventilation rate (VC mode 1 or 2).  ΔqV;vcs;req;t
                [m3/s]
            - Actual ventilation rate.  qV;vcs;t [m3/s]
            - Avcs;t  [W/K]
            - Bvcs;t  [W]
            - Internal temperature free float.  ϴint;0;t [°C]
            - Heating or cooling load.  ΦHC;vcs;t [W]
            - Internal temperature calculated.  ϴint;vcs;t [°C]
            - HC load difference.  ΔΦHC;vcs;t [W]
            - Target indoor temperature for VCS.  ϴint;set;vcs;t [°C]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    int_temp_free_float_with_vcs = [None] * TOT_HOURS
    bt_with_vcs = [None] * TOT_HOURS
    heating_cooling_load_with_vcs = [None] * TOT_HOURS
    internal_temperature_calc_with_vcs = [None] * TOT_HOURS

    for i in range(TOT_HOURS):
        if i == 0:
            int_temp_free_float_with_vcs[0] = 20

            bt_with_vcs[0] = (
                c_int / 3600 * int_temp_free_float_with_vcs[0]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[0]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[0]
                + (solar_gains[0] + internal_gains[0]) * building.floor_area
            )

        else:
            bt_with_vcs[i] = (
                c_int / 3600 * internal_temperature_calc_with_vcs[i - 1]
                + (
                    Air_properties_Cp * Air_properties_ro * vent_rate_m3_s[i]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[i]
                + (solar_gains[i] + internal_gains[i]) * building.floor_area
            )

            int_temp_free_float_with_vcs[i] = bt_with_vcs[i] / a_t[i]

        if int_temp_free_float_with_vcs[i] < lower_comfort_zone_limit[i]:
            heating_cooling_load_with_vcs[i] = (
                a_t[i] * lower_comfort_zone_limit[i] - bt_with_vcs[i]
            )
        elif (int_temp_free_float_with_vcs[i] >= lower_comfort_zone_limit[i]) and (
            int_temp_free_float_with_vcs[i] < upper_comfort_zone_limit[i]
        ):
            heating_cooling_load_with_vcs[i] = 0
        elif int_temp_free_float_with_vcs[i] > upper_comfort_zone_limit[i]:
            heating_cooling_load_with_vcs[i] = (
                a_t[i] * upper_comfort_zone_limit[i] - bt_with_vcs[i]
            )

        internal_temperature_calc_with_vcs[i] = (
            bt_with_vcs[i] + heating_cooling_load_with_vcs[i]
        ) / a_t[i]

    df["Ventilation rate without VCS"] = vent_rate_m3_s
    df["At.2"] = a_t
    df["Bt.2"] = bt_with_vcs
    df["Internal temperature free float.2"] = int_temp_free_float_with_vcs
    df['Heating or cooling load "step 2"'] = heating_cooling_load_with_vcs
    df['Internal temperature calculated "Step2"'] = internal_temperature_calc_with_vcs

    vc_mode = [None] * TOT_HOURS
    delta_theta_crit = 3  # °C, critical temperature difference for ventilative cooling to be effective
    for i in range(TOT_HOURS):
        if (time[i] >= building.time_control_on) and (
            time[i] <= building.time_control_off
        ):
            if int_temp_free_float_with_vcs[i] < lower_comfort_zone_limit[i]:
                vc_mode[i] = 0
            elif (int_temp_free_float_with_vcs[i] >= lower_comfort_zone_limit[i]) and (
                int_temp_free_float_with_vcs[i] <= upper_comfort_zone_limit[i]
            ):
                vc_mode[i] = 1
            elif (
                (int_temp_free_float_with_vcs[i] > upper_comfort_zone_limit[i])
                and (
                    outdoor_dry_bulb_temp[i]
                    <= (upper_comfort_zone_limit[i] - delta_theta_crit)
                )
                and (
                    relative_humidity_of_outdoor_air[i]
                    < building.max_outdoor_rel_hum_accepted
                )
            ):
                vc_mode[i] = 2
            else:
                vc_mode[i] = 3
        else:
            vc_mode[i] = None

    df["VC mode"] = vc_mode

    required_cooling_vent_rate = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        if vc_mode[i] == 2:
            required_cooling_vent_rate[i] = (
                bt_with_vcs[i] - a_t[i] * upper_comfort_zone_limit[i]
            ) / (
                Air_properties_Cp
                * Air_properties_ro
                * (upper_comfort_zone_limit[i] - outdoor_dry_bulb_temp[i])
            )
        else:
            required_cooling_vent_rate[i] = 0

    actual_ventilation_rate = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        if vc_mode[i] == 2:
            actual_ventilation_rate[i] = required_cooling_vent_rate[i] + vent_rate_m3_s[i]
        else:
            actual_ventilation_rate[i] = vent_rate_m3_s[i]

    a_vcs_t = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        a_vcs_t[i] = (
            c_int / 3600
            + Air_properties_Cp * Air_properties_ro * actual_ventilation_rate[i]
            + building.average_u_value * building.envelope_area
        )

    b_vcs_t = [None] * TOT_HOURS
    internal_temperature_free_s4 = [None] * TOT_HOURS  # s4 aka step 4
    heating_cooling_load_s4 = [None] * TOT_HOURS
    internal_temperature_calc_s4 = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        if i == 0:
            internal_temperature_free_s4[0] = 20
            b_vcs_t[0] = (
                c_int / 3600 * internal_temperature_free_s4[0]
                + (
                    Air_properties_Cp * Air_properties_ro * actual_ventilation_rate[0]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[0]
                + (solar_gains[0] + internal_gains[0]) * building.floor_area
            )
        else:
            b_vcs_t[i] = (
                c_int / 3600 * internal_temperature_calc_s4[i - 1]
                + (
                    Air_properties_Cp * Air_properties_ro * actual_ventilation_rate[i]
                    + building.average_u_value * building.envelope_area
                )
                * outdoor_dry_bulb_temp[i]
                + (solar_gains[i] + internal_gains[i]) * building.floor_area
            )

            internal_temperature_free_s4[i] = b_vcs_t[i] / a_vcs_t[i]

        if internal_temperature_free_s4[i] < lower_comfort_zone_limit[i]:
            heating_cooling_load_s4[i] = (
                a_vcs_t[i] * lower_comfort_zone_limit[i] - b_vcs_t[i]
            )
        elif (internal_temperature_free_s4[i] >= lower_comfort_zone_limit[i]) and (
            internal_temperature_free_s4[i] <= upper_comfort_zone_limit[i]
        ):
            heating_cooling_load_s4[i] = 0
        elif internal_temperature_free_s4[i] > upper_comfort_zone_limit[i]:
            heating_cooling_load_s4[i] = (
                a_vcs_t[i] * upper_comfort_zone_limit[i] - b_vcs_t[i]
            )

        internal_temperature_calc_s4[i] = (
            b_vcs_t[i] + heating_cooling_load_s4[i]
        ) / a_vcs_t[i]

    hc_load_difference = [None] * TOT_HOURS
    for i in range(TOT_HOURS):
        hc_load_difference[i] = -(heating_cooling_load[i] - heating_cooling_load_s4[i])

    df["Required cooling ventilation rate (VC mode 1 or 2)"] = (
        required_cooling_vent_rate
    )
    df["Actual ventilation rate"] = actual_ventilation_rate
    df["Avcs;t"] = a_vcs_t
    df["Bvcs;t"] = b_vcs_t
    df["Internal temperature free float.3"] = internal_temperature_free_s4
    df["Heating or cooling load.1"] = heating_cooling_load_s4
    df["Internal temperature calculated.2"] = internal_temperature_calc_s4
    df["HC load difference"] = hc_load_difference
    df["Target indoor temperature for VCS"] = upper_comfort_zone_limit

    return df

calc_thermal_comfort_data

calc_thermal_comfort_data(building, daily_mean_outdoor_temp)

Calculate Thermal comfort data.

PARAMETER	DESCRIPTION
building	TYPE: A class:`Building` instance

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly values of: Outdoor runnin mean temperature. Θrm [°C] Comfort temperature. Θc [°C] Lower comfort zone limit. Θint;set;H;t [°C] Upper comfort zone limit. Θint;set;C;t [°C]

Source code in src/venticoolpy/calculation.py

def calc_thermal_comfort_data(
    building: Building, daily_mean_outdoor_temp
) -> pd.DataFrame:
    """Calculate Thermal comfort data.

    Parameters
    ----------
    building : A class:`Building` instance


    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Outdoor runnin mean temperature.  Θrm [°C]
            - Comfort temperature.  Θc [°C]
            - Lower comfort zone limit.  Θint;set;H;t [°C]
            - Upper comfort zone limit.  Θint;set;C;t [°C]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    outdoor_runnin_mean_temperature = []
    temp = daily_mean_outdoor_temp[744:]
    for i in range(0, HOURS_IN_YEAR, 24):
        val = (
            temp[i - 24]
            + temp[i - 48] * 0.8
            + temp[i - 72] * 0.6
            + temp[i - 96] * 0.5
            + temp[i - 120] * 0.4
            + temp[i - 144] * 0.3
            + temp[i - 168] * 0.2
        ) / 3.8
        outdoor_runnin_mean_temperature.extend([val] * 24)

    full_year = outdoor_runnin_mean_temperature[-744:]
    full_year.extend(outdoor_runnin_mean_temperature)

    df["Outdoor runnin mean temperature"] = full_year

    t_min_k = get_t_min_k(building.comfort_requirements)

    temp_t_min_k= []
    for i in range(TOT_HOURS):
        time = (i + 1) % 24 # hours [1, 2, 3, ..., 23, 0]
        if time >= building.ti_day_start and time < building.ti_night_start:
            temp_t_min_k.append(t_min_k[building.bui_type])
        else:
            temp_t_min_k.append(building.ti_hsb)

    Ti_hsp = temp_t_min_k

    t_max_k = get_t_max_k(building.comfort_requirements)
    temp_t_max_k= []
    for i in range(TOT_HOURS):
        temp_t_max_k.append(t_max_k[building.bui_type])
    Ti_csp = temp_t_max_k

    k_lw = comfort_categories_LW[building.comfort_requirements]
    k_up = comfort_categories_UP[building.comfort_requirements]
    lower_comfort_zone_limit = [None] * TOT_HOURS
    upper_comfort_zone_limit = [None] * TOT_HOURS
    comfort_temperature = [None] * TOT_HOURS

    i = 0
    for i in range(TOT_HOURS):
        if full_year[i] > 10:
            upper_comfort_zone_limit[i] = 0.33 * full_year[i] + 18.8 + k_up
            comfort_temperature[i] = 0.33 * full_year[i] + 18.8
        else:
            upper_comfort_zone_limit[i] = Ti_csp[i]
            comfort_temperature[i] = (Ti_hsp[i] + Ti_csp[i]) / 2

    for i in range(TOT_HOURS):
        time = (i + 1) % 24
        if (time >= building.ti_day_start and time < building.ti_night_start) and full_year[i] > 10:
            lower_comfort_zone_limit[i] = 0.33 * full_year[i] + 18.8 + k_lw
        else:
            lower_comfort_zone_limit[i] = Ti_hsp[i]


    df["Comfort temperature"] = comfort_temperature
    df["Lower comfort zone limit"] = lower_comfort_zone_limit
    df["Upper comfort zone limit"] = upper_comfort_zone_limit

    return df

get_annual_data

get_annual_data(df_sim)

Heating [kWh] Cooling no VCP [kWh] Cooling VCP [kWh]

Source code in src/venticoolpy/calculation.py

def get_annual_data(df_sim: pd.DataFrame):
    """
    Heating [kWh]
    Cooling no VCP [kWh]
    Cooling VCP [kWh]
    """

    df = pd.DataFrame(index=range(1, 13))
    cols = [
        "Heating",
        "Cooling no VCP",
        "Cooling VCP",
    ]
    df[cols] = pd.DataFrame([[None] * len(cols)], index=df.index)

    for i, _ in df.iterrows():
        value = (
            df_sim.loc[
                (df_sim["Month"] == i) & (df_sim["Heating or cooling load"] > 0)
            ]["Heating or cooling load"].sum()
            / 1000
        )
        df.loc[i, "Heating"] = value

        value = (
            df_sim.loc[
                (df_sim["Month"] == i) & (df_sim["Heating or cooling load"] < 0)
            ]["Heating or cooling load"].sum()
            / 1000
        )
        df.loc[i, "Cooling no VCP"] = abs(value)

        value = (
            df_sim.loc[
                (df_sim["Month"] == i) & (df_sim["Heating or cooling load.1"] < 0)
            ]["Heating or cooling load.1"].sum()
            / 1000
        )
        df.loc[i, "Cooling VCP"] = abs(value)

    return df

get_gains

get_gains(building, climate_data)

Calculate solar and internal gains.

Patameters

building : A class:Building instance

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly values of: Solar gains. Φsol [W/m²] Internal gains. Φint [W/m²]

Source code in src/venticoolpy/calculation.py

def get_gains(building: Building, climate_data: ClimateData) -> pd.DataFrame:
    """Calculate solar and internal gains.

    Patameters
    ----------
    building : A class:`Building` instance

    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Solar gains.  Φsol [W/m²]
            - Internal gains.  Φint [W/m²]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    isol_tot = climate_data.isol_tot

    solar_gains = [
        x
        * (1 - building.shading_factor)
        * building.g_value_glazing_sys
        * building.fenestration_area
        / building.floor_area
        for x in isol_tot
    ]
    df["Solar gains"] = solar_gains

    internal_gains = get_internal_gains(building)

    df["Internal gains"] = internal_gains

    return df

get_internal_gains

get_internal_gains(building)

Retrieve internal gains according to building type

Source code in src/venticoolpy/calculation.py

def get_internal_gains(building: Building):
    """Retrieve internal gains according to building type"""

    data_resource = resources.files("venticoolpy.data").joinpath("occ_lgt_apl.csv")
    with resources.as_file(data_resource) as f:
        df_occ_lgt_apl = pd.read_csv(f)

    internal_gains = (
        f_conv_occ * (building.occupancy_gains_density) * df_occ_lgt_apl['OCC.'+building.bui_type] +
        f_conv_lgt * building.lighting_power_density * df_occ_lgt_apl['LGT.'+building.bui_type] +
        f_conv_app * building.el_equipment_power_density * df_occ_lgt_apl['APL.'+building.bui_type]
    )

    internal_gains = np.append(internal_gains[8016:8760].values, internal_gains[0:8760].values)

    return internal_gains

get_outdoor_climate_data

get_outdoor_climate_data(claimate_data)

Retrieve outdoor climate data.

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly values of: Outdoor dry-bulb temperature. θe;a [°C] Relative humidity of outdoor air. ΦHU;e;a;t [%] Daily mean outdoor temperature. θe;a;mean [°C]

Source code in src/venticoolpy/calculation.py

def get_outdoor_climate_data(claimate_data: ClimateData) -> pd.DataFrame:
    """Retrieve outdoor climate data.

    Parameters
    ----------
        # TODO: update

    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Outdoor dry-bulb temperature.  θe;a [°C]
            - Relative humidity of outdoor air.  ΦHU;e;a;t [%]
            - Daily mean outdoor temperature.  θe;a;mean [°C]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    df["Outdoor dry-bulb temperature"] = claimate_data.outdoor_dry_bulb_temperature
    outdoor_dry_bulb_temp = df["Outdoor dry-bulb temperature"].values

    df["Relative humidity of outdoor air"] = claimate_data.relative_humidity_outdoor_air

    daily_mean_outdoor_temp = []
    for i in range(0, TOT_HOURS, 24):
        val = mean(outdoor_dry_bulb_temp[i : i + 24])
        daily_mean_outdoor_temp.extend([val] * 24)
    df["Daily mean outdoor temperature"] = daily_mean_outdoor_temp

    return df

get_requirend_frequency_air_change_rate

get_requirend_frequency_air_change_rate(df_sim, building)

Frequency of air change rate required to provide potential comfort.

Source code in src/venticoolpy/calculation.py

def get_requirend_frequency_air_change_rate(df_sim: pd.DataFrame, building: Building):
    """Frequency of air change rate required to provide potential comfort."""

    df = pd.DataFrame()
    df.index = ["2", "4", "6", "8", "10", "12", "14", "16", "18", ">18"]

    df_sim = df_sim.loc[df_sim["VC mode"] == 2]

    values = [
        x * 3600 / building.room_volume
        for x in df_sim["Required cooling ventilation rate (VC mode 1 or 2)"].values
    ]
    df_sim["Required cooling ventilation rate"] = values

    frequency = []
    for index, _ in df.iterrows():
        if index == ">18":
            frequency.append(
                df_sim.loc[
                    df_sim["Required cooling ventilation rate"].between(
                        18, sys.maxsize, "neither"
                    ),
                    "Required cooling ventilation rate",
                ].count()
            )
        else:
            i = int(index)
            frequency.append(
                df_sim.loc[
                    df_sim["Required cooling ventilation rate"].between(
                        i - 2, i, "right"
                    ),
                    "Required cooling ventilation rate",
                ].count()
            )

    df["frequency"] = frequency
    tot_frequency = sum(frequency)
    df["frequency_percentage"] = [x / tot_frequency for x in frequency]

    cumulative_percentage = []
    for i in range(len(frequency)):
        cumulative_percentage.append(sum(frequency[: i + 1]) / tot_frequency)
    df["cumulative_percentage"] = cumulative_percentage

    return df

get_simulation_year

get_simulation_year()

Create a DataFrame for a sumulation.

Lenght is equal to December month + 1 standard year

RETURNS	DESCRIPTION
pd.DataFrame	Dataframe with columns: Date Month Day Time: integer (1, 2, ..., 24)

Source code in src/venticoolpy/calculation.py

def get_simulation_year() -> pd.DataFrame:
    """Create a DataFrame for a sumulation.

    Lenght is equal to December month + 1 standard year

    Returns
    -------
        pd.DataFrame
            Dataframe with columns:

            - Date
            - Month
            - Day
            - Time: integer (1, 2, ..., 24)
    """
    df = pd.DataFrame(index=range(TOT_HOURS))
    dates = pd.concat(
        [
            pd.Series(
                pd.date_range(start="2011-12-01", end="{}-01-01".format(2012), freq="h")
            )[0:744],
            pd.Series(
                pd.date_range(start="2011-01-01", end="{}-01-01".format(2012), freq="h")
            )[0:8760],
        ]
    )
    df["Date"] = dates.values

    df["Month"] = [d.month for d in dates]
    df["Day"] = [d.day for d in dates]
    df["Time"] = [d.hour + 1 for d in dates]

    return df

get_vent_mode_over_year

get_vent_mode_over_year(df_sim)

Calculate Ventilative mode over year given results of VCT simulation.

Source code in src/venticoolpy/calculation.py

def get_vent_mode_over_year(df_sim: pd.DataFrame):
    """Calculate Ventilative mode over year given results of VCT simulation."""
    df = pd.DataFrame()
    for i in range(1, 13):
        values = []
        for j in range(4):
            values.append(
                df_sim.loc[(df_sim["Month"] == i) & (df_sim["VC mode"] == j)].shape[0]
            )

        df[datetime.date(1900, i, 1).strftime("%B")] = values

    df = df.T
    for col in df.columns:
        df.loc["Year", col] = df[col].sum()

    return df

get_ventilation_rate

get_ventilation_rate(building)

Calculate Ventilation rates.

PARAMETER	DESCRIPTION
building	TYPE: A class:`Building` instance

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly values of: Ventilation rate. qV;t [m3/s]

Source code in src/venticoolpy/calculation.py

def get_ventilation_rate(building: Building) -> pd.DataFrame:
    """Calculate Ventilation rates.

    Parameters
    ----------
    building : A class:`Building` instance


    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly values of:

            - Ventilation rate.  qV;t [m3/s]
    """
    df = pd.DataFrame(index=range(TOT_HOURS))

    if building.my_min_req_vent_rate is not None: # custom, constant
        vent_rate_m3_s = building.min_req_vent_rate * building.floor_area / 1000
        ventilation_rate = [vent_rate_m3_s] * TOT_HOURS
    else: #hourly
        data_resource = resources.files("venticoolpy.data").joinpath("occ_lgt_apl.csv")
        with resources.as_file(data_resource) as f:
            df_occ_lgt_apl = pd.read_csv(f)

        min_req_vent_rate = (
            (Qp_comfort_category[building.comfort_requirements]
            * building.floor_area
            / m2_per_person[building.bui_type]) * df_occ_lgt_apl['OCC.'+building.bui_type]
            + Qa_comfort_category[building.comfort_requirements] * building.floor_area
        ) / building.floor_area

        vent_rate_m3_s = min_req_vent_rate * building.floor_area / 1000
        ventilation_rate = np.append(vent_rate_m3_s[8016:8760].values, vent_rate_m3_s[0:8760].values)

    df["Ventilation rate"] = ventilation_rate

    return df

run_vct_simulation

run_vct_simulation(inputs, climate_data)

Perform main VCT simulation.

RETURNS	DESCRIPTION
pd.DataFrame	A DataFrame with hourly simulation

Source code in src/venticoolpy/calculation.py

def run_vct_simulation(
    inputs: Building, 
    climate_data: ClimateData,
) -> pd.DataFrame:
    """
    Perform main VCT simulation.

    Returns
    -------
        pd.DataFrame
            A DataFrame with hourly simulation
    """
    df = get_simulation_year()

    ###############################################################
    #                 OUTDOOR CLIMATE DATA
    ###############################################################
    df_temp = get_outdoor_climate_data(climate_data)
    df = pd.concat([df, df_temp], axis=1)

    ###############################################################
    #                 THERMAL COMFORT DATA
    ###############################################################
    df_temp = calc_thermal_comfort_data(
        inputs, df["Daily mean outdoor temperature"].values
    )
    df = pd.concat([df, df_temp], axis=1)

    ###############################################################
    #                         GAINS
    ###############################################################
    df_temp = get_gains(inputs, climate_data)
    df = pd.concat([df, df_temp], axis=1)

    df_temp = get_ventilation_rate(inputs)
    df = pd.concat([df, df_temp], axis=1)

    ###############################################################
    #           FREE FLOAT MODE (1st SET OF CALCULATIONS)
    ###############################################################
    vent_rate_m3_s = df["Ventilation rate"].values
    solar_gains = df["Solar gains"].values
    internal_gains = df["Internal gains"].values
    outdoor_dry_bulb_temp = df["Outdoor dry-bulb temperature"].values
    c_int = inputs.c_int

    df_temp = calc_free_float_mode(
        building=inputs,
        c_int=c_int,
        vent_rate_m3_s=vent_rate_m3_s,
        solar_gains=solar_gains,
        internal_gains=internal_gains,
        outdoor_dry_bulb_temp=outdoor_dry_bulb_temp,
    )
    df = pd.concat([df, df_temp], axis=1)

    ###############################################################
    #  HEATING AND COOLING NEEDS, NO VCS (2nd SET OF CALCULATIONS)
    ###############################################################
    a_t = df["At"].values
    lower_comfort_zone_limit = df["Lower comfort zone limit"].values
    upper_comfort_zone_limit = df["Upper comfort zone limit"].values

    df_temp = calc_heating_and_cooling_needs_no_vcs(
        building=inputs,
        c_int=c_int,
        vent_rate_m3_s=vent_rate_m3_s,
        solar_gains=solar_gains,
        internal_gains=internal_gains,
        outdoor_dry_bulb_temp=outdoor_dry_bulb_temp,
        a_t=a_t,
        lower_comfort_zone_limit=lower_comfort_zone_limit,
        upper_comfort_zone_limit=upper_comfort_zone_limit,
    )
    df = pd.concat([df, df_temp], axis=1)

    ###############################################################
    # HEATING AND COOLING NEEDS, WITH VCS (3rd SET OF CALCULATIONS)
    ###############################################################
    relative_humidity_of_outdoor_air = df["Relative humidity of outdoor air"].values
    heating_cooling_load = df["Heating or cooling load"].values
    time = df["Time"].values

    df_temp = calc_heating_and_cooling_needs_with_vcs(
        building=inputs,
        c_int=c_int,
        vent_rate_m3_s=vent_rate_m3_s,
        solar_gains=solar_gains,
        internal_gains=internal_gains,
        outdoor_dry_bulb_temp=outdoor_dry_bulb_temp,
        a_t=a_t,
        lower_comfort_zone_limit=lower_comfort_zone_limit,
        upper_comfort_zone_limit=upper_comfort_zone_limit,
        relative_humidity_of_outdoor_air=relative_humidity_of_outdoor_air,
        heating_cooling_load=heating_cooling_load,
        time=time,
    )
    df = pd.concat([df, df_temp], axis=1)
    return df