sustaingym.envs.building.utils#

This module primarily implements the ParameterGenerator() function which generates the parameters dict for BuildingEnv.

All of the building layouts, U-factor values (thermal transmittance, in W/m2-K), ground temperatures, and weather data come from the Building Energy Codes Program: https://www.energycodes.gov/prototype-building-models.

Buildings models

  • HTM files were extracted from the “Individual Standard 90.1 Prototype Building Models” (version 90.1-2019)

  • We associate each building type with a list of 7 U-factor values (thermal transmittance, in W/m2-K) for different surfaces in the building in the order: [intwall, floor, outwall, roof, ceiling, groundfloor, window] These values are manually compiled from the HTM files, with missing values manually filled in from similar building types. For example, values missing from OfficeSmall were filled in from OfficeMedium.

Monthly ground temperature values come from the “Site:GroundTemperature:FCfactorMethod” table in the building HTM files.

Weather data come from EnergyPlus TMY3 Weather Files (in *.epw format) also provided by the Building Energy Codes Program.

Module Contents#

Classes#

Ufactor

Thermal transmittance (in W/m2-K) of different surfaces in a building

Zone

Functions#

get_zones(→ tuple[list[list[Zone]], int, list[Zone]])

Parses information from the HTM file and sorts each zone by layer.

checkconnect(→ bool)

Checks whether zones in the same layer are connected.

checkconnect_layer(→ bool)

Checks whether zones in different layers are connected.

Nfind_neighbor(→ tuple[dict[str, list[int]], ...)

This function is for the building model.

ParameterGenerator(* 7, ground_temp, shgc, ...)

Generates parameters from the selected building and temperature file for the env.

construct_A_matrix(→ numpy.ndarray)

Constructs the A matrix for the building environment.

construct_BD_matrix(→ tuple[numpy.ndarray, numpy.ndarray])

Constructs the B matrix for the building environment.

Attributes#

BUILDINGS

GROUND_TEMP

WEATHER

class sustaingym.envs.building.utils.Ufactor[source]#

Bases: NamedTuple

Thermal transmittance (in W/m2-K) of different surfaces in a building

intwall: float[source]#
floor: float[source]#
outwall: float[source]#
roof: float[source]#
ceiling: float[source]#
groundfloor: float[source]#
window: float[source]#
sustaingym.envs.building.utils.BUILDINGS[source]#
sustaingym.envs.building.utils.GROUND_TEMP[source]#
sustaingym.envs.building.utils.WEATHER[source]#
class sustaingym.envs.building.utils.Zone[source]#

Bases: NamedTuple

name: str[source]#
Zaxis: float[source]#
Xmin: float[source]#
Xmax: float[source]#
Ymin: float[source]#
Ymax: float[source]#
Zmin: float[source]#
Zmax: float[source]#
FloorArea: float[source]#
ExteriorGrossArea: float[source]#
ExteriorWindowArea: float[source]#
ind: int[source]#
sustaingym.envs.building.utils.get_zones(path_or_file: str | io.TextIOBase) → tuple[list[list[Zone]], int, list[Zone]][source]#

Parses information from the HTM file and sorts each zone by layer.

Parameters:

path_or_file (str | io.TextIOBase) – path to building HTM file, or a file-like object

Returns:

  • layers – Zones grouped by Zaxis, layers[i] is a list of Zones in layer i

  • n – number of zones

  • all_zones – list of n Zones

Return type:

tuple[list[list[Zone]], int, list[Zone]]

sustaingym.envs.building.utils.checkconnect(z1: Zone, z2: Zone) → bool[source]#

Checks whether zones in the same layer are connected.

Parameters:
Return type:

bool

sustaingym.envs.building.utils.checkconnect_layer(z1: Zone, z2: Zone) → bool[source]#

Checks whether zones in different layers are connected.

Parameters:
Return type:

bool

sustaingym.envs.building.utils.Nfind_neighbor(n: int, layers: collections.abc.Sequence[collections.abc.Sequence[Zone]], ufactor: Ufactor, SpecificHeat_avg: float) → tuple[dict[str, list[int]], numpy.ndarray, numpy.ndarray, numpy.ndarray][source]#

This function is for the building model.

Parameters:

  • n (int) – number of rooms

  • layers (collections.abc.Sequence[collections.abc.Sequence[Zone]]) – sorted layer list

  • ufactor (Ufactor) – list of 7 U-values (thermal transmittance) for different surfaces in the building in the order [intwall, floor, outwall, roof, ceiling, groundfloor, window].

  • SpecificHeat_avg (float) – specific heat of air (in J/kg-K)

Returns:

  • neighbors – maps zone name to a list of neighboring zone indices

  • Rtable – shape [n, n+1], thermal conductance between rooms (in W/K)

  • Ctable – shape [n], heat capacity of each zone (in J/K)

  • Windowtable – shape [n], exterior window area of each zone (in m^2)

Return type:

tuple[dict[str, list[int]], numpy.ndarray, numpy.ndarray, numpy.ndarray]

sustaingym.envs.building.utils.ParameterGenerator(building: str, weather: str, location: str, U_Wall: Ufactor = (0,) * 7, ground_temp: collections.abc.Sequence[float] = (0,) * 12, shgc: float = 0.252, shgc_weight: float = 0.01, ground_weight: float = 0.5, full_occ: numpy.ndarray | float = 0, max_power: numpy.ndarray | int = 8000, ac_map: numpy.ndarray | int = 1, time_res: int = 300, reward_beta: float = 0.999, reward_pnorm: float = 2, target: numpy.ndarray | float = 22, activity_sch: numpy.ndarray | float = 120, temp_range: tuple[float, float] = (-40, 40), is_continuous_action: bool = True, root: str = '') → dict[str, Any][source]#

Generates parameters from the selected building and temperature file for the env.

Parameters:

  • building (str) – name of a building in BUILDINGS, or path (relative to root) to a htm file for building idf

  • weather (str) – name of a weather condition in WEATHER, or path to an epw file.

  • location (str) – name of a location in GROUND_TEMP

  • U_Wall (Ufactor) – list of 7 U-values (thermal transmittance) for different surfaces in the building in the order [intwall, floor, outwall, roof, ceiling, groundfloor, window]. Only used if building cannot be found in BUILDINGS

  • ground_temp (collections.abc.Sequence[float]) – monthly ground temperature (in Celsius) when location is not in GROUND_TEMP

  • shgc (float) – Solar Heat Gain Coefficient for windows (unitless)

  • shgc_weight (float) – Weight factor for extra loss of solar irradiance (ghi)

  • ground_weight (float) – Weight factor for extra loss of heat from ground

  • full_occ (numpy.ndarray | float) – max number of people that can occupy each room, either an array of shape (n,) specifying maximum for each room, or a scalar maximum that applies to all rooms

  • max_power (numpy.ndarray | int) – max power output of a single HVAC unit (in W)

  • ac_map (numpy.ndarray | int) – binary indicator of presence (1) or absence (0) of AC, either a boolean array of shape (n,) to specify AC presence in individual rooms, or a scalar indicating AC presence in all rooms

  • time_res (int) – length of 1 timestep in seconds. Default is 300 (5 min).

  • reward_beta (float) – temperature error penalty weight for reward function

  • reward_pnorm (float) – p to use for norm in reward function

  • target (numpy.ndarray | float) – target temperature setpoints (in Celsius), either an array specifying individual setpoints for each zone, or a scalar setpoint for all zones

  • activity_sch (numpy.ndarray | float) – metabolic rate of people in the building (in W), either an array of shape (T,) to specify metabolic rate at every time step, or a scalar rate for all time steps

  • temp_range (tuple[float, float]) – (min temperature, max temperature) in Celsius, defining the possible temperature in the building

  • is_continuous_action (bool) – whether to use continuous action space (as opposed to MultiDiscrete)

  • root (str) – root directory for building and weather data files, only used when building and weather do not correspond to keys in BUILDINGS and WEATHER

Returns:

parameters – Contains all parameters needed for environment initialization.

Return type:

dict[str, Any]

sustaingym.envs.building.utils.construct_A_matrix(RCtable: numpy.ndarray, weightcmap: numpy.ndarray, connectmap: numpy.ndarray, occu_coef: float, n: int) → numpy.ndarray[source]#

Constructs the A matrix for the building environment.

Parameters:

  • RCtable (numpy.ndarray) – shape (n, n+1), represents 1/resistance-capacitance values for each room. The last column represents the connection to the outside.

  • weightcmap (numpy.ndarray) – shape (n, n+4), represents weighted connections for each room. Columns represent [people, ground, outside, AC, window, solar gain].

  • connectmap (numpy.ndarray) – shape (n, n+1), represents connectivity between rooms. A value of 1 indicates a connection, 0 indicates no connection. The last column represents the connection to the outside.

  • occu_coef (float) – Occupancy linear coefficient. Represents the effect of occupancy on the room’s temperature.

  • n (int) – Number of rooms or zones in the building.

Returns:

A – shape (n, n)

Return type:

numpy.ndarray

sustaingym.envs.building.utils.construct_BD_matrix(weightcmap: numpy.ndarray, connectmap: numpy.ndarray, RCtable: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray][source]#

Constructs the B matrix for the building environment.

Parameters:

  • weightcmap (numpy.ndarray) – shape (n, n+4), represents weighted connections for each room. Columns represent [people, ground, outside, AC (n cols), solar gain].

  • connectmap (numpy.ndarray) – shape (n, n+1), represents connectivity between rooms. A value of 1 indicates a connection, 0 indicates no connection. The last column represents the connection to the outside.

  • RCtable (numpy.ndarray) – shape (n, n+1), represents resistance-capacitance values for each room. The last column represents the connection to the outside.

Returns:

  • B – B matrix of shape (n, n+3)

  • D – D vector of shape (n,)

Return type:

tuple[numpy.ndarray, numpy.ndarray]