Visitors - ptidejteam/tools4cities-metamenth GitHub Wiki

MetamEnTh has various visitors that traverse objects and gather data based on various criteria. All visitors inherit from the AbstractSpaceVisitor

AbstractSpaceVisitor

AbstractSpaceVisitor is an abstract base class designed to define an interface for visiting different spaces in buildings. It allows for customized visits to buildings, floors, rooms, and open spaces based on specified criteria.

Initialization

__init__(self, floor_criteria: Dict, room_criteria: Dict, open_space_criteria: Dict)

Initializes an AbstractSpaceVisitor instance with criteria for filtering down sensor searches within various building spaces.

Parameters:

  • floor_criteria: Dict - Criteria to filter the sensor search to specific floors.
  • room_criteria: Dict - Criteria to filter the sensor search to specific rooms.
  • open_space_criteria: Dict - Criteria to filter the sensor search to specific open spaces.

Attributes:

  • self._floor_criteria: Holds the filtering criteria for floors.
  • self._room_criteria: Holds the filtering criteria for rooms.
  • self._open_space_criteria: Holds the filtering criteria for open spaces.
  • self.found_entities: A list to store found entities that match the given criteria.

Abstract Methods

The following methods must be implemented by any subclass that inherits from AbstractSpaceVisitor.

visit_building(self, building)

Defines the operation for visiting a building. The method iterates over all floors in the building and calls the accept method on each floor to invoke the visitor.

Parameters:

  • building: Building - The building object to be visited. Should have an address attribute and a method get_floors() to retrieve its floors.

Output:

Prints a message indicating the building being visited and iterates over its floors.

visit_floor(self, floor)

Defines the operation for visiting a floor. It filters the visit based on the given criteria for floors, and if matched, it further visits rooms and open spaces within the floor.

Parameters:

  • floor: Floor - The floor object to be visited. Should have a number attribute and methods get_rooms() and get_open_spaces() to retrieve rooms and open spaces.

Output:

Prints a message indicating the floor being visited and iterates over its rooms and open spaces.

visit_room(self, room)

Defines the operation for visiting a room. This method is abstract and must be implemented by subclasses.

Parameters:

  • room: Room - The room object to be visited.

Output:

Must be defined by the subclass.

visit_open_space(self, open_space)

Defines the operation for visiting an open space. This method is abstract and must be implemented by subclasses.

Parameters:

  • open_space: OpenSpace - The open space object to be visited.

Output:

Must be defined by the subclass.

Utility Methods

_match_criteria(self, entity, criteria)

Compares a given entity against the specified criteria to check if it meets the search conditions.

Parameters:

  • entity: Entity - The entity being compared to the search criteria. The entity must have a get() method to access its attributes.
  • criteria: Dict - The filter criteria. Keys represent attribute names and values represent the expected values to match.

Returns:

  • bool: True if the entity matches the criteria, False otherwise.

Behaviour:

  • If no criteria are provided, the method returns True by default.
  • It supports both single-value and list-based matching.
  • For entities with attributes of type AbstractEnum, it matches against the value attribute of the enum.
  • The method safely handles entities that may not have all attributes present, catching AttributeError exceptions.

HVACComponentSearchVisitor

HVACComponentSearchVisitor is a concrete implementation of the AbstractSpaceVisitor class. It is used to search for HVAC components in various building spaces based on specified criteria.

Initialization

__init__(self, hvac_component_criteria: Dict, floor_criteria: Dict = None, room_criteria: Dict = None, open_space_criteria: Dict = None)

Initializes an HVACComponentSearchVisitor instance with criteria for searching HVAC components and optional criteria for filtering specific building spaces.

Parameters:

  • hvac_component_criteria: Dict - The search criteria for HVAC components. It must contain a key 'component_class' to specify the type of component being searched.
  • floor_criteria: Dict (optional) - Criteria to filter the sensor search to specific floors.
  • room_criteria: Dict (optional) - Criteria to filter the sensor search to specific rooms.
  • open_space_criteria: Dict (optional) - Criteria to filter the sensor search to specific open spaces.

Raises:

  • ValueError: If the hvac_component_criteria dictionary does not contain the key 'component_class'.

Methods

visit_room(self, room)

Visits a room and searches for HVAC components if the room matches the specified criteria.

Parameters:

  • room: Room - The room object to be visited. Should have a name attribute and a get_hvac_components() method to retrieve its HVAC components.

Output:

Prints a message indicating the room being visited and searches for HVAC components within the room.

visit_open_space(self, open_space)

Visits an open space and searches for HVAC components if the open space matches the specified criteria.

Parameters:

  • open_space: OpenSpace - The open space object to be visited. Should have a name attribute and a get_hvac_components() method to retrieve its HVAC components.

Output:

Prints a message indicating the open space being visited and searches for HVAC components within the space.

_search_hvac_components(self, space)

Searches for HVAC components in a given space (room or open space). It can handle nested components such as components within ducts or air volume boxes.

Parameters:

  • space: Space - The space object (room or open space) to search within. Should have a get_hvac_components() method to retrieve its HVAC components.

Behaviour:

  • Checks if the HVAC component matches the component_class specified in the criteria.
  • If the component is a Duct, it searches within the duct's entities like heat exchangers, fans, connected air volume boxes, and dampers.
  • If the component is an AirVolumeBox, it checks the inlet dampers within the air volume box.

_add_hvac_component(self, entity)

Adds an HVAC component to the list of found entities if it matches the specified criteria.

Parameters:

  • entity: HVACComponent - The HVAC component entity being added. Should have attributes that match the hvac_component_criteria provided.

Behaviour:

  • Compares the entity's attributes against the criteria.
  • If the entity matches the criteria, it is added to the found_entities list.

Attributes

  • self._hvac_component_criteria: Stores the search criteria for HVAC components.
  • self.found_entities: A list to store found HVAC components that match the given criteria.

Example Usage:

If hvac_component_criteria is {'component_class': 'Damper', 'damper_type': DamperType.MANUAL_VOLUME.value}, it will search for all damper components with the damper type of DamperType.MANUAL_VOLUME.value in the specified spaces (rooms or open spaces).

MeterSearchVisitor

MeterSearchVisitor is a concrete implementation of the AbstractSpaceVisitor class. It is used to search for meters in various building spaces or zones based on specified criteria.

Initialization

__init__(self, meter_criteria: Dict, floor_criteria: Dict = None, room_criteria: Dict = None, open_space_criteria: Dict = None)

Initializes a MeterSearchVisitor instance with criteria for searching meters and optional criteria for filtering specific building spaces.

Parameters:

  • meter_criteria: Dict - The search criteria for meters.
  • floor_criteria: Dict (optional) - Criteria to filter the meter search to specific floors.
  • room_criteria: Dict (optional) - Criteria to filter the meter search to specific rooms.
  • open_space_criteria: Dict (optional) - Criteria to filter the meter search to specific open spaces.

Methods

visit_building(self, building)

Visits a building and searches for meters at the building level as well as in its floors, rooms, and open spaces.

Parameters:

  • building: Building - The building object to be visited. Should have an address attribute and methods like get_meters() and get_floors() to retrieve its meters and floors respectively.

Behaviour:

  • Prints the address of the building being visited.
  • Searches for meters at the building level that match the specified criteria.
  • Invokes the accept() method on each floor of the building to visit the floor.

visit_room(self, room)

Visits a room and searches for meters if the room matches the specified criteria.

Parameters:

  • room: Room - The room object to be visited. Should have a name attribute and a meter attribute.

Behaviour:

  • Prints a message indicating the room being visited.
  • Searches for meters within the room that match the specified criteria.
  • Invokes the _search_meters() method to perform a detailed search in the room.

visit_open_space(self, open_space)

Visits an open space and searches for meters if the open space matches the specified criteria.

Parameters:

  • open_space: OpenSpace - The open space object to be visited. Should have a name attribute and a meter attribute.

Behaviour:

  • Prints a message indicating the open space being visited.
  • Searches for meters within the open space that match the specified criteria.
  • Invokes the _search_meters() method to perform a detailed search in the open space.

_search_meters(self, space)

Searches for meters in a given space (room or open space). It can also search meters within HVAC components or energy systems associated with the space.

Parameters:

  • space: Space - The space object (room or open space) to search within. Should have a meter attribute and methods like get_hvac_components() and get_energy_systems() to retrieve its HVAC components and energy systems respectively.

Behavior:

  • Checks if the space's meter matches the specified criteria.
  • Adds the meter to the found_entities list if it matches the criteria.
  • Invokes _search_entities() to search for meters within HVAC components and energy systems in the space.

_search_entities(self, entities)

Searches for meters within a list of entities such as HVAC components or energy systems.

Parameters:

  • entities: List - A list of entities to search within. Each entity should have a meter attribute.

Behaviour:

  • Iterates through each entity in the list.
  • Checks if the entity's meter matches the specified criteria.
  • Adds the meter to the found_entities list if it matches the criteria.

Attributes

  • self._meter_criteria: Stores the search criteria for meters.
  • self.found_entities: A list to store found meters that match the given criteria.

Example Usage:

If meter_criteria is {'type': MeterType.ELECTRICITY.value}, it will search for all electricity meters in the specified spaces (rooms or open spaces).

SensorSearchVisitor

SensorSearchVisitor is a concrete implementation of the AbstractSpaceVisitor class. It is used to search for sensors in various building spaces or zones based on specified criteria.

Initialization

__init__(self, sensor_criteria: Dict, floor_criteria: Dict = None, room_criteria: Dict = None, open_space_criteria: Dict = None)

Initializes a SensorSearchVisitor instance with criteria for searching sensors and optional criteria for filtering specific building spaces.

Parameters:

  • sensor_criteria: Dict - The search criteria for sensors.
  • floor_criteria: Dict (optional) - Criteria to filter the sensor search to specific floors.
  • room_criteria: Dict (optional) - Criteria to filter the sensor search to specific rooms.
  • open_space_criteria: Dict (optional) - Criteria to filter the sensor search to specific open spaces.

Methods

visit_room(self, room)

Visits a room and searches for sensors if the room matches the specified criteria.

Parameters:

  • room: Room - The room object to be visited. Should have a name attribute and a method like get_transducers() to retrieve its sensors.

Behaviour:

  • Prints a message indicating the room being visited.
  • Searches for sensors within the room that match the specified criteria.
  • Invokes the _search_sensors() method to perform a detailed search in the room.

visit_open_space(self, open_space)

Visits an open space and searches for sensors if the open space matches the specified criteria.

Parameters:

  • open_space: OpenSpace - The open space object to be visited. Should have a name attribute and a method like get_transducers() to retrieve its sensors.

Behaviour:

  • Prints a message indicating the open space being visited.
  • Searches for sensors within the open space that match the specified criteria.
  • Invokes the _search_sensors() method to perform a detailed search in the open space.

_search_sensors(self, space)

Searches for sensors in a given space (room or open space). It can also search sensors within HVAC components, appliances, and energy systems associated with the space.

Parameters:

  • space: Space - The space object (room or open space) to search within. Should have methods like get_transducers(), get_hvac_components(), get_appliances(), and get_energy_systems() to retrieve its sensors, HVAC components, appliances, and energy systems respectively.

Behaviour:

  • Iterates through each sensor in the space's transducers.
  • Adds the sensor to the found_entities list if it matches the criteria.
  • Invokes _search_entities() to search for sensors within HVAC components, appliances, and energy systems in the space.

_search_entities(self, entities)

Searches for sensors within a list of entities such as HVAC components, appliances, or energy systems.

Parameters:

  • entities: List - A list of entities to search within. Each entity should have a method like get_transducers() to retrieve its sensors.

Behaviour:

  • Iterates through each entity in the list.
  • Iterates through each sensor in the entity's transducers.
  • Adds the sensor to the found_entities list if it matches the criteria.

Attributes

  • self._sensor_criteria: Stores the search criteria for sensors.
  • self.found_entities: A list to store found sensors that match the given criteria.

Example Usage:

If sensor_criteria is {'measure': 'SensorMeasure.TEMPERATURE.value'}, it will search for all temperature sensors in the specified spaces (rooms or open spaces).

SpaceSearchVisitor

SpaceSearchVisitor is a concrete implementation of the AbstractSpaceVisitor class. It is used to search for specific spaces such as floors, rooms, or open spaces within a building, based on specified criteria.

Initialization

__init__(self, floor_criteria: Dict = None, room_criteria: Dict = None, open_space_criteria: Dict = None, include_floor: bool = True)

Initializes a SpaceSearchVisitor instance with optional criteria for searching specific building spaces.

Parameters:

  • floor_criteria: Dict (optional) - Criteria to filter the search to specific floors.
  • room_criteria: Dict (optional) - Criteria to filter the search to specific rooms.
  • open_space_criteria: Dict (optional) - Criteria to filter the search to specific open spaces.
  • include_floor: bool (optional) - If True, includes the floor in the search results when it matches the criteria. Default is True.

Methods

visit_floor(self, floor)

Visits a floor and searches for rooms and open spaces if the floor matches the specified criteria.

Parameters:

  • floor: Floor - The floor object to be visited. Should have a number attribute and methods like get_rooms() and get_open_spaces() to retrieve its rooms and open spaces.

Behaviour:

  • Prints a message indicating the floor being visited.
  • Adds the floor to the found_entities list if it matches the criteria and include_floor is set to True.
  • Iterates through each room in the floor and calls the accept() method to visit the room.
  • Iterates through each open space in the floor and calls the accept() method to visit the open space.

visit_room(self, room)

Visits a room and adds it to the search results if it matches the specified criteria.

Parameters:

  • room: Room - The room object to be visited. Should have methods like accept() to process the room.

Behaviour:

  • Adds the room to the found_entities list if it matches the criteria specified in room_criteria.

visit_open_space(self, open_space)

Visits an open space and adds it to the search results if it matches the specified criteria.

Parameters:

  • open_space: OpenSpace - The open space object to be visited. Should have methods like accept() to process the open space.

Behaviour:

  • Adds the open space to the found_entities list if it matches the criteria specified in open_space_criteria.

Attributes

  • self._include_floor: Indicates whether to include the floor in the search results when it matches the criteria.
  • self.found_entities: A list to store found spaces (floors, rooms, or open spaces) that match the given criteria.

Usage Example

If floor_criteria is {'floor_type': FloorType.ROOFTOP.value}, room_criteria is {'room_type': RoomType.OFFICE.value}, and open_space_criteria is {'name': 'Lobby'}, the visitor will search for:

  • Rooftop level floors if include_floor is set to True.
  • office rooms on the matching floors.
  • Open spaces named 'Lobby' on the matching floors.