Skip to content

Buildings#

smart_control.simulator.building #

Code for representing the control volumes within a building.

BaseSimulatorBuilding #

Bases: ABC

Base class for building simulators.

conductivity abstractmethod property #

conductivity: ndarray

Returns the conductivity array of the building.

cv_type abstractmethod property #

cv_type: ndarray

Returns the CV type array of the building.

density abstractmethod property #

density: ndarray

Returns the density array of the building.

heat_capacity abstractmethod property #

heat_capacity: ndarray

Returns the heat capacity array of the building.

get_zone_average_temps abstractmethod #

get_zone_average_temps() -> Union[Dict[Tuple[int, int], Any], Dict[str, Any]]

Returns the average temperature of each zone.

reset abstractmethod #

reset()

Resets the building to its initial parameters.

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 #

apply_thermal_power_zone(zone_coordinates: Coordinates2D, power: float)

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 #

get_zone_average_temps() -> Dict[Tuple[int, int], Any]

Returns a dict of zone average temps.

The dict is formatted as {zone_coordinates: temp}.

get_zone_temp_stats #

get_zone_temp_stats(
    zone_coordinates: Coordinates2D,
) -> Tuple[float, float, float]

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 #

get_zone_thermal_energy_rate(zone_coordinates: Coordinates2D) -> float

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

reset #

reset()

Resets the building to its initial parameters.

DefaultExteriorWallRadiationProperties dataclass #

DefaultExteriorWallRadiationProperties()

Bases: RadiationProperties

The default radiation properties for building materials.

DefaultInsideAirRadiationProperties dataclass #

DefaultInsideAirRadiationProperties()

Bases: RadiationProperties

The default radiation properties for inside air.

DefaultInsideWallRadiationProperties dataclass #

DefaultInsideWallRadiationProperties()

Bases: RadiationProperties

The default radiation properties for light colored paints.

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 #

apply_longwave_interior_radiative_heat_transfer(
    temperature_estimates: ndarray,
) -> np.ndarray

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 #

apply_thermal_power_zone(zone_name: str, power: float)

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 #

get_zone_average_temps() -> Dict[str, Any]

Returns a dict of zone average temps.

The dict is formatted as: {zone_coordinates: temp}.

get_zone_temp_stats #

get_zone_temp_stats(zone_name: str) -> Tuple[float, float, float]

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 #

get_zone_thermal_energy_rate(zone_name: str) -> float

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 #

MaterialProperties(conductivity: float, heat_capacity: float, density: float)

Holds the physical constants for a material.

RadiationProperties dataclass #

RadiationProperties(
    alpha: float, epsilon: float, tau: float, rho: float | None = None
)

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 #

assign_building_exterior_values(array: ndarray, value: float)

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 #

assign_interior_wall_values(array: ndarray, value: float, room_shape: Shape2D)

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 #

generate_thermal_diffusers(
    matrix_shape: Shape2D, room_shape: Shape2D
) -> np.ndarray

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 #

RejectionSimulatorBuilding(
    base_building: BaseBuilding, initial_rejection_count: int = 0
)

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 #

current_timestamp: Timestamp

Lists the current local time of the building.

num_occupants property #

num_occupants: int

Returns the number of occupants in building.

reward_info property #

reward_info: RewardInfo

Returns a message with data to compute the instantaneous reward.

time_step_sec property #

time_step_sec: float

Returns the amount of time between time steps.

zones property #

zones: Sequence[ZoneInfo]

Lists the zones in the building managed by the RL agent.

is_comfort_mode #

is_comfort_mode(current_time: Timestamp) -> bool

Returns True if building is in comfort mode.

render #

render(path: str) -> None

Renders the current state of the building.

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.

reset #

reset() -> None

Resets the building, throwing a RuntimeError if this is impossible.

wait_time #

wait_time() -> None

Returns after a certain amount of time.

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 #

current_timestamp: Timestamp

Lists the current local time of the building.

devices property #

devices: Sequence[DeviceInfo]

Lists the devices that can be queried and/or controlled.

reward_info property #

reward_info: RewardInfo

Returns a message with data to compute the instantaneous reward.

time_step_sec property #

time_step_sec: float

Returns the amount of time between time steps.

zones property #

zones: Sequence[ZoneInfo]

Lists the zones in the building managed by the RL agent.

is_comfort_mode #

is_comfort_mode(current_time: Timestamp) -> bool

Returns True if building is in comfort mode.

render #

render(path: str) -> None

Renders the current state of the building.

request_action #

request_action(
    action_request: ActionRequest,
) -> smart_control_building_pb2.ActionResponse

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.

reset #

reset() -> None

Resets the building, throwing a RuntimeError if this is impossible.

wait_time #

wait_time() -> None

Returns after a certain amount of time.