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.
generate_stochastic_ambient_features(→ numpy.ndarray)	Generates stochastic ambient/environment features for the BuildingEnv.
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

Bases: NamedTuple

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

intwall: float

floor: float

outwall: float

roof: float

ceiling: float

groundfloor: float

window: float

sustaingym.envs.building.utils.BUILDINGS

sustaingym.envs.building.utils.GROUND_TEMP

sustaingym.envs.building.utils.WEATHER

class sustaingym.envs.building.utils.Zone

Bases: NamedTuple

name: str

Zaxis: float

Xmin: float

Xmax: float

Ymin: float

Ymax: float

Zmin: float

Zmax: float

FloorArea: float

ExteriorGrossArea: float

ExteriorWindowArea: float

ind: int

sustaingym.envs.building.utils.get_zones(path_or_file: str | io.TextIOBase) → tuple[list[list[Zone]], int, list[Zone]]

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

Checks whether zones in the same layer are connected.

Parameters:

• z1 (Zone) –

• z2 (Zone) –

Return type:

bool

sustaingym.envs.building.utils.checkconnect_layer(z1: Zone, z2: Zone) → bool

Checks whether zones in different layers are connected.

Parameters:

• z1 (Zone) –

• z2 (Zone) –

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]

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.generate_stochastic_ambient_features(stochastic_summer_percentage: float, num_rows: int, data: numpy.ndarray, block_size: int) → numpy.ndarray

Generates stochastic ambient/environment features for the BuildingEnv.

Parameters:

• stochastic_summer_percentage (float) – the weight (between 0 and 1) of the generated observations to be given to those generated from the summer distribution.

• num_rows (int) – the number of observations of the ambient features to generate

• data (numpy.ndarray) – shape [num_hours, 3], processed data containing the year’s worth of feature observations to be fed into the stochastic generator

• block_size (int) – the number of hours of data over which to infer a data-generating distribution that creates new instances of observations

Returns:

samples – The sampled ambient features in the desired season. Shape is (block_size x num_rows, num_obs_features).

Return type:

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 = '', stochastic_summer_percentage: float | None = None, episode_len: int = 288, block_size: int = None) → dict[str, Any]

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

• stochastic_summer_percentage (float | None) – fraction (between 0 and 1) of the generated observations that should be weighted toward those from the summer distribution. None if not using stochastic features

• episode_len (int) – number of time steps in each episode (default: 288 steps at 5-min time_res is 1 day)

• block_size (int) – size (in hours) of blocks of data to fit distributions to (e.g., block_size=24 will sample daily blocks of 24 hourly observations to fit distributions to)

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

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]

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]