Buildings#
smart_control.simulator.building
#
Code for representing the control volumes within a building.
BaseSimulatorBuilding
#
Bases: ABC
Base class for building simulators.
Building
#
Building(
cv_size_cm: float,
floor_height_cm: float,
room_shape: Shape2D,
building_shape: Shape2D,
initial_temp: float,
inside_air_properties: MaterialProperties,
inside_wall_properties: MaterialProperties,
building_exterior_properties: MaterialProperties,
deprecation: bool = False,
)
Bases: BaseSimulatorBuilding
Represents a matrix of volumes of material in a building.
Attributes:
Name | Type | Description |
---|---|---|
cv_size_cm |
Scalar in cm representing width, length and height of control volume. |
|
floor_height_cm |
Height in cm floor to ceiling of each room. |
|
room_shape |
2-Tuple representing the number of air control volumes in the width and length of each room. |
|
building_shape |
2-Tuple representing the number of rooms in the width and length of the building. |
|
temp |
The current temp in K of each control volume. |
|
conductivity |
ndarray
|
Thermal conductivity in of each control volume W/m/K. |
heat_capacity |
ndarray
|
Thermal heat cpacity of each control volume in J/kg/K. |
density |
ndarray
|
Material density in kg/m3 of each control volume. |
input_q |
ndarray
|
Heat energy applied (sign indicates heating/cooling) at the CV in W (J/s). |
diffusers |
Proportion of the heat applied per VAV; sums to 1 for each zone. |
|
neighbors |
Matrix containing list of neighbor coordinates for each control volume. |
|
cv_type |
ndarray
|
a matrix noting whether each CV is outside air, interior space, or a wall. cv_type will be used in the sweep() function. |
Initializes the ControlVolumes.
Creates a matrix of control volumes representing the air and walls of a building. The size of each room (in terms of control volumes of air) is controlled by room_shape. The number of rooms in each building is controlled by building_shape. The outer 2 layers of the matrix represent special cells where the exterior walls and ambient air interact.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cv_size_cm
|
float
|
Width, length and height of control volume. |
required |
floor_height_cm
|
float
|
Height in cm floor to ceiling of each room. |
required |
room_shape
|
Shape2D
|
2-Tuple representing the number of air control volumes in the width and length of each room. |
required |
building_shape
|
Shape2D
|
2-Tuple representing the number of rooms in the width and length of the building. |
required |
initial_temp
|
float
|
Initial temperature for each control volume. |
required |
inside_air_properties
|
MaterialProperties
|
MaterialProperties for interior air. |
required |
inside_wall_properties
|
MaterialProperties
|
MaterialProperties for interior walls. |
required |
building_exterior_properties
|
MaterialProperties
|
MaterialProperties for building's exterior. |
required |
deprecation
|
bool
|
if true, the old code has been deprecated and transitioned to the new, geometrically flexible code. TODO(spangher): change to True when the former code is deprecated. |
False
|
apply_thermal_power_zone
#
Applies thermal power to zones, spread evenly across diffusers.
The thermal power [W] is applied to zones zone_x
and zone_y
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_coordinates
|
Coordinates2D
|
Tuple containing x and y coordinates for zone. |
required |
power
|
float
|
Watts to apply to zone. |
required |
get_zone_average_temps
#
Returns a dict of zone average temps.
The dict is formatted as {zone_coordinates
: temp
}.
get_zone_temp_stats
#
Returns the min, max, and mean temp of all air CVs in zone.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_coordinates
|
Coordinates2D
|
Tuple containing x and y coordinates for zone. |
required |
get_zone_thermal_energy_rate
#
Returns energy rate in W being input to specified zone.
Sums its CVs contributions.
Calculates and returns sum of input_q of all air CVs in a given zone.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_coordinates
|
Coordinates2D
|
Tuple containing x and y coordinates for zone. |
required |
DefaultExteriorWallRadiationProperties
dataclass
#
DefaultInsideAirRadiationProperties
dataclass
#
DefaultInsideWallRadiationProperties
dataclass
#
FloorPlanBasedBuilding
#
FloorPlanBasedBuilding(
cv_size_cm: float,
floor_height_cm: float,
initial_temp: float,
inside_air_properties: MaterialProperties,
inside_wall_properties: MaterialProperties,
building_exterior_properties: MaterialProperties,
zone_map: Optional[ndarray] = None,
zone_map_filepath: Optional[str] = None,
floor_plan: Optional[ndarray] = None,
floor_plan_filepath: Optional[str] = None,
buffer_from_walls: int = 3,
convection_simulator: Optional[BaseConvectionSimulator] = None,
reset_temp_values: ndarray | None = None,
inside_air_radiative_properties: RadiationProperties | None = None,
inside_wall_radiative_properties: RadiationProperties | None = None,
building_exterior_radiative_properties: RadiationProperties | None = None,
include_radiative_heat_transfer: bool = False,
view_factor_method: str = "ScriptF",
)
Bases: BaseSimulatorBuilding
Creates a Building that is floor plan based to avoid a messy deprecation.
Attributes:
Name | Type | Description |
---|---|---|
cv_size_cm |
Scalar in cm representing width, length and height of control volume. |
|
floor_height_cm |
Height in cm floor to ceiling of each room. |
|
room_shape |
2-Tuple representing the number of air control volumes in the width and length of each room. |
|
building_shape |
2-Tuple representing the number of rooms in the width and length of the building. |
|
floor_plan |
an np.ndarray representing the building's floor plan. |
|
temp |
The current temp in K of each control volume. |
|
conductivity |
ndarray
|
Thermal conductivity in of each control volume W/m/K. |
heat_capacity |
ndarray
|
Thermal heat capacity of each control volume in J/kg/K. |
density |
ndarray
|
Material density in kg/m3 of each control volume. |
input_q |
ndarray
|
Heat energy applied (sign indicates heating/cooling) at the CV in W (J/s). |
diffusers |
Proportion of the heat applied per VAV; sums to 1 for each zone. |
|
cv_type |
ndarray
|
a matrix noting whether each CV is outside air, interior space, or a wall. cv_type will be used in the sweep() function. |
neighbors |
Matrix containing list of neighbor coordinates for each control volume. |
|
len_neighbors |
matrix containing the length of neighbors |
|
include_radiative_heat_transfer |
bool to note whether to include radiative heat transfer. |
|
indexed_floor_plan |
matrix representing the building's floor plan. Used only for calculating interior radiative heat transfer. |
|
interior_wall_mask |
matrix representing the interior walls of the building. Used only for calculating interior radiative heat transfer. |
|
interior_wall_index |
matrix representing the index of the interior walls of the building. Used only for calculating interior radiative heat transfer. |
|
interior_wall_VF |
matrix representing the view factors of the interior walls of the building, which is denoted as F in the equation. Used only for calculating interior radiative heat transfer. |
|
epsilon |
matrix representing the emissivity of the nodes of the building. Used only for calculating radiative heat transfer. |
|
alpha |
matrix representing the absorptivity of the nodes of the building. Used only for calculating radiative heat transfer. |
|
tau |
matrix representing the transmittance of the nodes of the building. Used only for calculating radiative heat transfer. |
|
IFAinv |
matrix representing the inverse of the IFA matrix of the nodes of the building. Used only for calculating radiative heat transfer. The longwave radiation (\(q_{lwx}\)) is calculated as: \[q_{lwx} = \sigma(I-F)\tilde{A}_{inv}T^4\]
Where the term \((I-F)\tilde{A}_{inv}\) can be pre-calculated as: \[IFA_{inv} = (I-F)\tilde{A}_{inv}\]
|
Initializes the New Building.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cv_size_cm
|
float
|
Width, length and height of control volume. |
required |
floor_height_cm
|
float
|
Height in cm floor to ceiling of each room. |
required |
initial_temp
|
float
|
Initial temperature for each control volume. |
required |
inside_air_properties
|
MaterialProperties
|
MaterialProperties for interior air. |
required |
inside_wall_properties
|
MaterialProperties
|
MaterialProperties for interior walls. |
required |
building_exterior_properties
|
MaterialProperties
|
MaterialProperties for building's exterior. |
required |
inside_air_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for interior air. |
None
|
inside_wall_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for interior walls. |
None
|
building_exterior_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for building's exterior. |
None
|
zone_map
|
Optional[ndarray]
|
an np.ndarray noting where the VAV zones are. |
None
|
zone_map_filepath
|
Optional[str]
|
a string of where to find the zone_map in CNS. Note that the user requires only to provide one of either zone_map_filepath or zone_map. |
None
|
floor_plan
|
Optional[ndarray]
|
an np.ndarray to pass into the function if one has this. If this is None, then the user must pass in a filepath. |
None
|
floor_plan_filepath
|
Optional[str]
|
a string of where to find the floor_plan in CNS. Both floor_plan and floor_plan_filepath may not be None in the new code. debugging purposes. |
None
|
buffer_from_walls
|
int
|
int to note the space to put between thermal diffusers and walls |
3
|
convection_simulator
|
Optional[BaseConvectionSimulator]
|
object to simulate air convection |
None
|
reset_temp_values
|
ndarray | None
|
Temp values to use when resetting the building |
None
|
inside_air_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for interior air. |
None
|
inside_wall_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for interior walls. |
None
|
building_exterior_radiative_properties
|
RadiationProperties | None
|
RadiationProperties for building's exterior. |
None
|
include_radiative_heat_transfer
|
bool
|
bool to note whether to include radiative heat transfer. |
False
|
view_factor_method
|
str
|
str to note the method to use for view factors. Either "ScriptF" or "CarrollMRT". See LW Radiation Exchange Among Zone Surfaces for more details. |
'ScriptF'
|
apply_longwave_interior_radiative_heat_transfer
#
Applies long-wave interior radiative heat transfer.
This function calculates the net radiative heat flux and radiosity for each interior wall.
apply_thermal_power_zone
#
Applies thermal power to zones, spread evenly across diffusers.
The thermal power [W] is applied to zones zone_x
and zone_y
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_name
|
str
|
a string with the name of the zone to calculate over. Needs to be present in self.room_dict. |
required |
power
|
float
|
Watts to apply to zone. |
required |
get_zone_average_temps
#
Returns a dict of zone average temps.
The dict is formatted as: {zone_coordinates
: temp
}.
get_zone_temp_stats
#
Returns the min, max, and mean temp of all air CVs in zone.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_name
|
str
|
a string with the name of the zone to calculate over. Needs to be present in self.room_dict. |
required |
Returns:
Type | Description |
---|---|
Tuple[float, float, float]
|
the thermal energy rate of the zone. |
get_zone_thermal_energy_rate
#
Returns energy rate in W being input to specified zone.
Sums its CVs contributions.
Calculates and returns sum of input_q of all air CVs in a given zone.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_name
|
str
|
a string with the name of the zone to calculate over. Needs to be present in self.room_dict. |
required |
Returns:
Type | Description |
---|---|
float
|
the thermal energy rate of the zone. |
MaterialProperties
dataclass
#
Holds the physical constants for a material.
RadiationProperties
dataclass
#
Holds the radiative properties for a material.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
alpha
|
float
|
absorptivity. Absorptivity is the fraction of incident radiative heat that is absorbed by a surface. When radiation strikes a surface, a portion of its energy is converted into internal thermal energy, causing the temperature of the surface to rise. A value of 1 means the surface is a "black body" and absorbs all incident radiation, while a value of 0 means it absorbs none. |
required |
epsilon
|
float
|
emissivity. Emissivity is a measure of a surface's ability to emit thermal radiation. It is the ratio of the radiation emitted by a surface to the radiation emitted by a perfect black body at the same temperature. A black body has an emissivity of 1, as it is a perfect emitter. A surface with an emissivity of 0 is a theoretical "white body" that cannot emit radiation. High emissivity surfaces (like matte black paint) are excellent radiators of heat, while low emissivity surfaces (like polished metal) are poor radiators. |
required |
tau
|
float
|
transmittance. Transmittance is the fraction of incident radiative heat that passes through a medium without being absorbed or reflected. This property is particularly relevant for modeling radiation through transparent or semi-transparent materials, such as glass, air, or other gases. For an opaque surface, the transmittance is always 0 because no radiation passes through it. For a perfectly transparent medium, the transmittance is always 1. |
required |
rho
|
float
|
reflectivity. Reflectivity is the fraction of incident radiative heat that is reflected away from a surface. When radiation hits a surface, some of it bounces off. A highly polished, shiny surface will have a high reflectivity (approaching 1), while a dull, dark surface will have low reflectivity (approaching 0). |
None
|
Relationship between the properties:
- For any surface, the sum of absorptivity, reflectivity, and transmittance must equal 1, as all incident radiation is either absorbed, reflected, or transmitted.
- For an opaque (non-transparent) surface, where transmittance is 0, the sum of absorptivity and reflectivity must equal 1, as all incident radiation is either absorbed or reflected.
Each of the property values should be between 0 and 1 (inclusive). Example values for various common materials are displayed in the tables below.
Long-wave and solar emissivity for building surfaces:
Material | Long-wave emissivity (epsilon) | Solar absorptivity (alpha) |
---|---|---|
Building materials | 0.90 - 0.96 | 0.6 - 0.7 |
Wood | 0.9 | 0.9 - 0.96 |
Dark-colored paints | 0.91 - 0.95 | 0.98 |
Light-colored paints | 0.8 | 0.2 |
Galvanized metal | 0.28 | 0.8 |
Aluminum, polished | 0.03 | 0.09 |
Window glass | 0.9 - 0.95 | 0.02 - 0.04 |
Water | 0.96 | 0.1 - 1* |
Ice | 0.95 | 0.3 - 0.4 |
* Depends strongly on zenith angle; is close to unity for small angles and close to zero for large angles.
Source
Table 4.5, Mitchell, John W., and James E. Braun. Principles of heating, ventilation, and air conditioning in buildings. John Wiley & Sons, 2012.
assign_building_exterior_values
#
Assigns value to the building's exterior locations.
The outer 2 layers of the matrix are special CVs which represent the thicker exterior walls as well as the ambient air.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
array
|
ndarray
|
Numpy array to assign values to. |
required |
value
|
float
|
Value to assign. |
required |
assign_interior_wall_values
#
Assigns value to interior wall locations.
These are the walls dividing the rooms. None of these walls are on the outer 2 layers of the matrix which are reserved for the thicker outer walls.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
array
|
ndarray
|
Numpy array to assign values to. |
required |
value
|
float
|
Value to assign. |
required |
room_shape
|
Shape2D
|
2-Tuple representing the number of air control volumes in the width and length of each room. |
required |
enlarge_exterior_walls
#
enlarge_exterior_walls(
exterior_walls: ExteriorWalls, interior_walls: InteriorWalls
) -> Tuple[building_utils.ExteriorWalls, building_utils.InteriorWalls]
Sequentially calls helper functions for expanding exterior walls.
This function links together some necessary helper functions in building_utils.py so that it is clear and straightforward what they do when put in sequence. Given a FileInputFloorPlan, this function breaks out the necessary pieces of information for further processing.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
exterior_walls
|
ExteriorWalls
|
an ExteriorWalls noting where exterior walls are. |
required |
interior_walls
|
InteriorWalls
|
an InteriorWalls noting where interior walls are. |
required |
Returns:
Type | Description |
---|---|
ExteriorWalls
|
an ExteriorWalls with exterior walls expanded by |
InteriorWalls
|
constants.EXPAND_EXTERIOR_WALLS_BY_CV_AMOUNT. |
Tuple[ExteriorWalls, InteriorWalls]
|
an InteriorWalls with interior walls shrunk by |
Tuple[ExteriorWalls, InteriorWalls]
|
constants.EXPAND_EXTERIOR_WALLS_BY_CV_AMOUNT. |
generate_thermal_diffusers
#
Returns a matrix with four thermal air diffusers for a VAV in each zone.
This function places 4 diffusers in each room. The function aims to distribute them evenly in the room regardless of room size.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
matrix_shape
|
Shape2D
|
2-Tuple representing shape of a matrix. |
required |
room_shape
|
Shape2D
|
2-Tuple representing the number of air control volumes in the width and length of each room. |
required |
get_zone_bounds
#
get_zone_bounds(
zone_coordinates: Coordinates2D, room_shape: Shape2D
) -> Tuple[int, int, int, int]
Returns (min_x, max_x, min_y, max_y) index bounds for specified zone.
Helper function to get the minimum and maximum indices excluding walls in each dimension for specified zone.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
zone_coordinates
|
Coordinates2D
|
Tuple containing x and y coordinates for zone. |
required |
room_shape
|
Shape2D
|
2-Tuple representing the number of air control volumes in the width and length of each room. |
required |
smart_control.simulator.rejection_simulator_building
#
A simulator building that initially throws RPC exceptions before start.
RejectionSimulatorBuilding
#
Bases: BaseBuilding
A Building that throws exception while agent is awaiting authorization.
Initializes a RejectionSimulatorBuilding.
Takes on a BaseBuilding rather than extending it so other types of effects (like sensor errors, etc.) can be chained together.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
base_building
|
BaseBuilding
|
A BaseBuilding implementation. |
required |
initial_rejection_count
|
int
|
Number of action rejections before start. |
0
|
current_timestamp
property
#
Lists the current local time of the building.
reward_info
property
#
Returns a message with data to compute the instantaneous reward.
is_comfort_mode
#
Returns True if building is in comfort mode.
request_observations
#
request_observations(
observation_request: ObservationRequest,
) -> smart_control_building_pb2.ObservationResponse
Queries the building for its current state.
request_observations_within_time_interval
#
request_observations_within_time_interval(
observation_request: ObservationRequest,
start_timestamp: Timestamp,
end_timestamp: Timestamp,
) -> Sequence[smart_control_building_pb2.ObservationResponse]
Queries the building for observations between start and end times.
smart_control.simulator.simulator_building
#
Extension of BaseBuilding for a simulated building.
This file is used to build an RL environment with a simulator controlling the thermodynamics and observation/action space.
SimulatorBuilding
#
SimulatorBuilding(
simulator: Union[SimulatorFlexibleGeometries, Simulator, TFSimulator],
occupancy: BaseOccupancy,
)
Bases: BaseBuilding
Base class for a controllable building for reinforcement learning.
Creates SimulatorBuilding.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
simulator
|
Union[SimulatorFlexibleGeometries, Simulator, TFSimulator]
|
Simulator to run for the RL environment. This can take in either the floor_plan based simulator or the rectangular sim (deprecated). |
required |
occupancy
|
BaseOccupancy
|
a function to determine building occupancy by zone. |
required |
current_timestamp
property
#
Lists the current local time of the building.
devices
property
#
Lists the devices that can be queried and/or controlled.
reward_info
property
#
Returns a message with data to compute the instantaneous reward.
is_comfort_mode
#
Returns True if building is in comfort mode.
request_action
#
Issues a command to the building to change one or more setpoints.
request_observations
#
request_observations(
observation_request: ObservationRequest,
) -> smart_control_building_pb2.ObservationResponse
Queries the building for its current state.
request_observations_within_time_interval
#
request_observations_within_time_interval(
observation_request: ObservationRequest,
start_timestamp: Timestamp,
end_timestamp: Timestamp,
) -> Sequence[smart_control_building_pb2.ObservationResponse]
Queries the building for observations between start and end times.