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.

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,
)

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

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
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

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.

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.