Skip to content

Utilities#

smart_control.simulator.constants #

Defines constants for use in simulation code suite.

smart_control.simulator.building_utils #

Utils for computing the physical and thermal characteristics of buildings.

RoomIndicesDict module-attribute #

RoomIndicesDict = defaultdict[str, Any]

Note: The following four types all describe various aspects of the same

floorplan; i.e. all four types have the same dimensionality and encode similar variations of the same information. Here I will describe the differences between the types: (1) FileInputFloorPlan: the floorplan format as entered into the program. This specifically notes exterior space as 2's, walls as 1's, and inside space as 0's. This file type may have various "glitches" that the program will correct, such as walls that abut directly the frame of the image. (2) ConnectionReadyFloorPlan: the floorplan format as processed and ready for the opencv function connectedComponents . This format requires a very specific input type, namely 1's where there is open space and 0's everywhere else. Therefore, prior to this step, various pieces of information must be removed from the floor plan, such as the location of exterior space, and stored in other datatypes. (3) Connections: the floorplan format after opencv's connectedComponents is run on it. The Connections floorplan has each connected component, defined as the contiguous space within each component of interest (room, zone, etc.) labelled with an increasing integer indexing the component. It is an np.ndarray where 0's are walls and connected contiguous space are increasing integers. (4) ExteriorSpace: the floorplan format serves an auxiliary store of information so that the original floorplan can be stripped of a specific designation for exterior space in order to be prepared for ingestion into connectedComponents. It is an np.ndarray where 0's are walls or interior space and exterior space is marked with -1. (5) ExteriorWalls: a floorplan format that notes where exterior walls are with 1's and everywhere else with 0's. (6) InteriorWalls: a floorplan format that notes where interior walls are with -3 and everywhere else with 0's.

construct_building_data_types #

construct_building_data_types(
    floor_plan: FileInputFloorPlan,
    zone_map: FileInputFloorPlan,
    save_debugging_image: bool = False,
) -> Tuple[RoomIndicesDict, ExteriorWalls, InteriorWalls, ExteriorSpace]

Sequentially calls all preprocessing functions in building_utils.py.

This function links together the 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
floor_plan FileInputFloorPlan

an FileInputFloorPlan with outside air marked as constants.EXTERIOR_SPACE_VALUE_IN_FILE_INPUT, inside walls marked as constants.INTERIOR_WALL_VALUE_IN_FILE_INPUT, and inside space marked as constants.INTERIOR_SPACE_VALUE_IN_FILE_INPUT.

 required
zone_map FileInputFloorPlan

a FileInputFloorPlan that has, using the same int markings as the floor_plan, the VAV zones noted instead of the physical rooms.

 required
save_debugging_image bool

bool for whether we should save some debugging images to CNS.

 False

Returns:

Type Description
Tuple[RoomIndicesDict, ExteriorWalls, InteriorWalls, ExteriorSpace]

connections output with exterior space set negative.

enlarge_component #

enlarge_component(
    array_with_component_nonzero: ndarray, distance_to_augment: float
) -> np.ndarray

Enlarges the component in question by CVs within a certain distance.

Note: this function is a general purpose function intended to enlarge any component by measure of "distance_to_augment".

Parameters:

Name Type Description Default
array_with_component_nonzero ndarray

array where the object to enlarge is nonzero

 required
distance_to_augment float

return a new object with CVs within this distance selected.

 required

Returns:

Type Description
ndarray

An array with 1 being a CV to include and 0 being a CV to exclude.

guarantee_air_padding_in_frame #

guarantee_air_padding_in_frame(
    floor_plan: FileInputFloorPlan,
) -> FileInputFloorPlan

Adds a row or column of air if a building is abuts its frame edge.

Future computation relies on buildings being surrounded by at least one layer of air CVs between them and the edge of the floor plan frame. However, due to human variation in preparing floor plans for transformation into arrays, we may have the case where a floor plan is passed in that has wall CVs at the edge of the frame. Thus, this function should check that that is the case and will add a layer of exterior space CVs if building lies against the array's edge.

If walls are touching more than

one edge of the floor plan, the function should be able to compute this -- but if it adds rows of CVs and then does not update the shape of the floor plan, it will fail. Thus, we package the dimension tracking and rows to concatenate in a convenient helper function so it can be called multiple times without repetitive code.

Parameters:

Name Type Description Default
floor_plan FileInputFloorPlan

a FileInputFloorPlan

 required

Returns:

Type Description
FileInputFloorPlan

an FileInputFloorPlan that has 2's padded along whichever array edge was missing them.

process_and_run_connected_components #

process_and_run_connected_components(
    floor_plan: FileInputFloorPlan,
) -> Connections

Public function that takes in floor plan and outputs a Components.

Parameters:

Name Type Description Default
floor_plan FileInputFloorPlan

FileInputFloorPlan

 required

Returns:

Type Description
Connections

connections output with exterior space set negative.

read_floor_plan_from_filepath #

read_floor_plan_from_filepath(
    filepath: str, save_debugging_image: bool = False
) -> FileInputFloorPlan

Reads a file from a disk (including CNS) and returns it.

Parameters:

Name Type Description Default
filepath str

name of the location on CNS. CSV and NPY files are supported, and they are both determined by the semantic naming of the path, i.e. the file type suffix.

 required
save_debugging_image bool

boolean for whether we should save the debugging image to cns.

 False

Returns:

Type Description
FileInputFloorPlan

a FileInputFloorPlan

save_images_to_cns_for_debugging #

save_images_to_cns_for_debugging(
    floor_plan: Union[
        FileInputFloorPlan,
        Connections,
        ExteriorWalls,
        InteriorWalls,
        ndarray,
        ConnectionReadyFloorPlan,
    ],
    path_ending: str,
    path_to_simulator_cns: str = "/cns/oi-d/home/smart_buildings/control/configs/simulation/",
) -> None

Saves a .png of a floorplan array to CNS for visual debugging.

Parameters:

Name Type Description Default
floor_plan Union[FileInputFloorPlan, Connections, ExteriorWalls, InteriorWalls, ndarray, ConnectionReadyFloorPlan]

one of the floor_plan types

 required
path_ending str

a path suffix to end saved files

 required
path_to_simulator_cns str

base path to save the files on CNS.

 '/cns/oi-d/home/smart_buildings/control/configs/simulation/'

smart_control.simulator.thermal_diffuser_utils #

Code for generating thermal diffusers in a building.

These helper functions are separated these out into their own file for extensibility: we can easily put in another function loading these from data and process this using similar function format.

diffuser_allocation_switch #

diffuser_allocation_switch(
    room_cv_indices: Collection[Coordinates2D],
    spacing: int = 10,
    interior_walls: Optional[InteriorWalls] = None,
    buffer_from_walls: int = 2,
) -> Collection[Coordinates2D]

Switches between random and even assignment of thermal diffusers.

A more in-depth explanation: here we provide a method for allocating thermal diffusers that is general for many types of rooms. At a high level, if a room is rectangular enough, we allocate diffusers evenly according to a grid determined by the input "spacing", and then only select the points that are inside the original set of room indices to ensure we don't place a diffuser outside. If a room is too insanely shaped (i.e. imagine a long snaking hallway or an entryway to a few private alcoves) we instead try to ensure that the appropriate number of diffusers are still placed, but for simplicity we place them randomly. This option is almost never taken, as most rooms are deemed rectangular enough according to our measure:

Here, from the number of CVs that define a room, extract the total number of CVs (num_CVs), the maximum and minimum x coordinates (x_max, x_min), and the maximum and minimum y coordinates (y_max, y_min), and set a threshold. If num_CVs / ((x_max - x_min) * (y_max - y_min)) > threshold, it is rectangular enough.

Parameters:

Name Type Description Default
room_cv_indices Collection[Coordinates2D]

a list of indices making up a room.

 required
spacing int

how many control volumes to put between each diffuser

 10
interior_walls Optional[InteriorWalls]

an InteriorWalls for determining whether thermal diffusers are allocated in walls. This measure is intended for cases in which one needs to provide a interior_walls and zone_map to the Building class, and they may not line up correctly on account of being from different photo sources.

 None
buffer_from_walls int

how far to place a thermal diffuser away from a wall.

 2

Returns:

Type Description
Collection[Coordinates2D]

a list of inds to place diffusers.