Subsystem - ptidejteam/tools4cities-metamenth GitHub Wiki

MetamEnTh Subsystem has two main classes: BuildingControlSystem and Appliance, with BuildingControlSystem having one control system class, HVACSystem, in a composition (a whole-part relationship where BuildingControlSystem is the whole and HVACSystem, the part relationship. This design allows the extension and inclusion of other control systems in MetamEnTh in the future.

Figure 1.0: MetamEnTh Subsystem, showing the various classes and their relationships, including the HVAC building control system

Figure 2.0: MetamEnTh Subsystem, showing classes and the methods they possess

Figure 3.0: MetamEnTh Appliance Subsystem class and its relationship with other classes

Classes and Their Relationships

All classes (entities) have auto-generated IDs (UID) to uniquely identify objects created from them.

AbstractSubsystem

This class serves as the parent class for all subsystems. All subsystems inherit the attributes of this class.

Parent Class

None

Relationships

None

Attributes

  • name: string, the name of the subsystem, e.g., HVAC system

Behaviours (Methods)

None

AirVolumeBox

The AirVolumeBox class models air volume boxes in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

  • AirVolumeBox has one-to-many relationship with Damper

Attributes

  • air_volume_type: AirVolumeType, the type of air volume box, e.g., VARIABLE_AIR_VOLUME
  • inlet_dampers: List[Damper], inlet dampers that may be installed in an air volume box
  • has_heating_capability: bool (default is False), indicates if the air volume box has heating capability
  • has_cooling_capability: bool (default is False), indicates if the air volume box has cooling capability

Behaviours (Methods)

Inherits methods from parent classes.

Boiler

The Boiler class models boilers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • category: BoilerCategory, the category of boiler, e.g., LPG
  • power_state: PowerState, the power state of the boiler, e.g., OFF

Behaviours (Methods)

Inherits methods from parent classes.

BuildingControlSystem

This class models various control systems in a building.

Parent Class

AbstractSubsystem

Relationships

  • BuildingControlSystem has a one-to-one relationship with HVACSystem.

Attributes

  • hvac_system: HVACSystem, the HVAC control system

Behaviours (Methods)

None

Appliance

The Appliance class of subsystem models appliances in a building.

Parent Classes

AbstractSubsystem AbstractDynamicEntity

Relationships

  • AbstractFloorSpace has a one-to-many relationship with Appliance, e.g., a room can have multiple appliances
  • Appliance has one one-to-many relationship with Transducer, e.g., an appliance can have multiple sensors

Attributes

  • hvac_system: HVACSystem, the HVAC control system
  • appliance_category: ApplianceCategory, the appliance category, e.g., home appliance.
  • appliance_type : List[ApplianceType], the appliance type, e.g., photocopier
  • manufacturer: string, the manufacturer of the appliance
  • consumption_capacity: AbstractMeasure, the power consumption capacity of the appliance
  • rated_device_measure: RatedDeviceMeasure, the rated device measure of the appliance
  • operating_conditions: List[ContinuousMeasure], the operating conditions of the appliance

Behaviours (Methods)

Inherits methods from parent classes.

AbstractVentilationComponent

This class serves as the parent class for all ventilation-related entities.

Parent Classes

AbstractDynamicEntity

Relationships

None

Attributes

  • name: string, the name of the ventilation component
  • operating_conditions: List[ContinuousMeasure], the operating conditions of the appliance

Behaviours (Methods)

None

BaseboardHeater

This class models baseboard heaters in buildings.

Parent Classes

AbstractVentilationComponent

Relationships

Inherits relationships from parent classes, e.g., AbstractFloorSpace (e.g., room) has one-to-many relationship with AbstractVentilationComponent (e.g., baseboard heater)

Attributes

  • heating_type: HeatingType, the heating type of the baseboard heater, e.g., HYDRONIC
  • power_state: PowerState, the power state of the baseboard heater, e.g., ON

Behaviours (Methods)

None

Controller

The Controoler class models controllers that actuate specific HVAC components in a building.

Parent Classes

AbstractHVACComponent

Relationships

  • Controller has one-to-many relationship with other AbstractHVACComponent
  • Controller has one-to-many relationship with an Appliance

Attributes

  • controller_entities: List[Union[AbstractHVACComponent, Appliance]], the HVAC entities or appliance the controller actuates, e.g., fan
  • set_point: Dict[str, AbstractMeasure], a dictionary that stores all the set points for the controller. For each setpoint that is added, there must be a sensor and an actuator. The key for each set point entry is the name of the sensor, a colon, and the name of the actuator. For example, set_point['sensor_name:actuator_name'] = set point value

Behaviours (Methods)

  • get_controller_entities(self, search_terms: Dict = None) -> [Union[AbstractHVACComponent, Appliance]]: searches for entities actuated by the controller using attributes and their values
  • add_set_point(self, set_point: AbstractMeasure, transducer_pair: tuple):: adds a set point for a sensor-actuator pair to the controller
  • get_set_point(self, sensor_name: str, actuator_name: str) -> AbstractMeasure: gets a set point for a sensor-actuator pair
  • remove_set_point(self, sensor_name: str, actuator_name: str): removes a set point for a sensor-actuator pair
  • add_controller_entity(self, entity: Union[AbstractHVACComponent, Appliance]): adds an entity actuated by this controller
  • remove_controller_entity(self, entity: Union[AbstractHVACComponent, Appliance]): removes an entity actuated by this controller

HVACSystem

The HVACSystem class models Heating, Ventilation, and Air-Conditioning (HVAC) systems in buildings.

Parent Classes

None

Relationships

  • HVACSystem has one-to-many relationship with VentilationSystem
  • BuildingControlSystem has one-to-one relationship with HVACSystem

Attributes

  • ventilation_systems: List[VentilationSystem], the ventilation systems of an HVAC system

Behaviours (Methods)

None

RadiantSlab

This class models radiant slabs used in some buildings to provide additional heating.

Parent Classes

AbstractVentilationComponent

Relationships

  • Inherits relationships from parent classes, e.g., AbstractFloorSpace (e.g., room) has one-to-many relationship with AbstractVentilationComponent (e.g., radiant slabs)

Attributes

  • radiant_slab_type: RadiantSlabType, the type of radiant slab, e.g., ELECTRIC

Behaviours (Methods)

None

ThermalStorage

The ThermalStorage class models systems to store thermal energy in buildings.

Parent Classes

AbstractVentilationComponent

Relationships

  • Inherits relationships from parent classes, e.g., AbstractFloorSpace (e.g., room) has one-to-many relationship with AbstractVentilationComponent (e.g., thermal storage)

Attributes

  • Inherit attributes from parent classes

Behaviours (Methods)

None

VentilationSystem

The VentilationSystem class models ventilation systems with air handling units (AHU).

Parent Classes

None

Relationships

  • VentilationSystem has one-to-one relationship with Duct
  • VentilationSystem has one-to-many relationship with AbstractVentilationComponent
  • VentilationSystem has one-to-many relationship with Engine

Attributes

  • ventilation_type: VentilationType, the type of ventilation system, e.g., AHU
  • principal_duct: Duct, the principal air duct of the ventilation system
  • components: List[Union[AbstractVentilationComponent, Engine]], a list of entities, e.g., baseboard heaters, possessed by the ventilation system

Behaviours (Methods)

  • get_components(search_terms: Dict) -> [Union[AbstractVentilationComponent, Engine]]: searches for ventilation components in a ventilation system
  • add_component(component: Union[AbstractVentilationComponent, Engine]): adds a ventilation component to a ventilation system
  • remove_component(component: Union[AbstractVentilationComponent, Engine]): removes a ventilation component from a ventilation system

AbstractDuctConnectedComponent

The AbstractDuctConnectedComponent is the parent class for all entities connected to a ventilation duct.

Parent Classes

AbstractHVACComponent

Relationships

Inherits relationships from the parent class

Attributes

  • ducts: List[Duct], ventilation ducts that are connected to ventilation components
  • vfd: VariableFrequencyDrive, variable frequency drives that are installed on ventilation components

Behaviours (Methods)

  • add_duct(duct: Dict): adds ventilation duct to a ventilation component. This captures all the ventilation ducts a ventilation component is connected to

AbstractHVACComponent

The AbstractHVACComponent is the parent class for all HVAC-related entities.

Parent Classes

AbstractDynamicEntity

Relationships

  • AbstractHVACComponent has one-to-one relationship with SchedulableEntity

Attributes

  • name: string, the name of the HVAC component
  • meter: AbstractReader (optional), a meter that may be installed on the HVAC component
  • rated_device_meassure: RatedDeviceMeasure (optional), the rated device measure of the HVAC component
  • schedulable_entity: SchedulableEntity models the various operational schedules of the HVAC component
  • operating_conditions: List[ContinuousMeasure], the operating conditions of the HVAC component
  • spaces: List[AbstractFloorSpace], the spaces, e.g., room, that contain or are serviced by the HVAC component
  • status_measure: List[StatusMeasure], the power status of the HVAC component recorded over time

Behaviours (Methods)

  • add_spaces(space: [AbstractFloorSpace]): adds spaces serviced by an HVAC component or the space that contains the HVAC component
  • remove_spaces(space: AbstractFloorSpace): remove spaces from an HVAC component
  • get_spaces(search_terms: Dict) -> [AbstractFloorSpace]: searches for various spaces serviced by (or that contain) an HVAC component
  • add_status_measure(status: StatusMeasure): records the power status of an HVAC component at a particular time
  • remove_status_measure(status: StatusMeasure): removes the power status at a particular time from an HVAC component
  • get_status_measure(search_terms: Dict) -> [StatusMeasure]: searches for power status data of an HVAC component based on attributes and their values
  • get_status_measure_by_date(from_timestamp: str, to_timestamp: str) -> [StatusMeasure]: searches for power status data of an HVAC component between (inclusive) from_timestamp to to_timestamp. If to_timestamp is not provided, it searches data from from_timestamp to the last data point available.

Chiller

The Chiller class models chillers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • chiller_type: ChillerType, the type of chiller, e.g., WATER_COOLED
  • power_state: PowerState, the power state of the boiler, e.g., OFF

Behaviours (Methods)

Inherits methods from parent classes.

CirculationPump

The CirculationPump class models chillers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • pump_type: CirculationPumpType, the type of circulation pump, e.g., CENTRIFUGAL
  • power_state: PowerState, the power state of the boiler, e.g., OFF

Behaviours (Methods)

Inherits methods from parent classes.

Compressor

The Compressor class models chillers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • compressor_type: CompressorType, the type of compressor, e.g., RECIPROCATING_HERMETIC

Behaviours (Methods)

Inherits methods from parent classes.

Condenser

The Compressor class models chillers that are parts of an HVAC system in a building.

Parent Classes

AbstractHVACComponent

Relationships

Inherits relationships from parent classes

Attributes

  • refrigerant_type: RefrigerantType, the type of refrigerant used in the condenser, e.g., R134A
  • coil_mater: CoilMaterial, the material used for the condenser coil, e.g., COPPER
  • heat_transfer_area: AbstractMeasure, the area of the heat transfer material of the condenser
  • heat_transfer_coefficient: float (default is 0.0), the heat transfer coefficient of the condenser

Behaviours (Methods)

Inherits methods from parent classes.

CoolingTower

The CoolingTower class models cooling towers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

Inherits attributes from parent classes

Behaviours (Methods)

Inherits methods from parent classes

Damper

The Damper class models dampers installed in ventilation ducts in buildings.

Parent Classes

AbstractHVACComponent

Relationships

Inherits relationships from parent classes

Attributes

  • damper_type: DamperType, the type of damper, e.g., BASIC_MANUAL_VOLUME
  • percentage_opened: List[DamperPosition], saves data on the damper position over time

Behaviours (Methods)

  • add_damper_position(damper_position: DamperPosition): adds damper position (how wide the damper is opened) for a damper
  • remove_damper_position(damper_position: DamperPosition): remove damper positions data from an HVAC component
  • get_damper_positions(search_terms: Dict) -> [DamperPosition]: searches for damper positions data
  • get_damper_positions_by_date(from_timestamp: str, to_timestamp: str) -> [DamperPosition]: searches for damper positions data between (inclusive) from_timestamp to to_timestamp. If to_timestamp is not provided, it searches data from from_timestamp to the last data point available.

Duct

The Duct class models various ductwork in buildings' HVAC systems.

Parent Classes

AbstractDynamicEntity AbstractZonalEntity

Relationships

  • Duct has a one-to-many relationship with HeatExchanger
  • Duct has a one-to-many relationship with Fan
  • Duct has a one-to-many relationship with Damper
  • Duct has a one-to-many relationship with AirVolumeBox

Attributes

  • name: string, the name of the ventilation duct
  • duct_type: DuctType captures what substance flows through the duct, e.g., WATER_WITH_ANTI_FREEZE
  • duct_sub_type: DuctSubType (optional) captures the type of substance indicated with the duct_type attribute, e.g., GLYCOL
  • connections: DuctConnection, an object that models other ducts and HVAC components connected to a duct
  • heat_exchangers: List[HeatExchanger], a list of heat exchangers installed in a ventilation duct
  • fans: `List[Fan], a list of fans installed in a ventilation duct
  • dampers: `List[Damper], a list of dampers installed in a ventilation duct
  • connected_air_volume_box: `List[AirVolumeBox], a list of air volume boxes connected to a ventilation duct

Behaviours (Methods)

  • add_heat_exchanger(heat_exchanger: HeatExchanger): adds a heat exchanger to a ventilation duct
  • add_fan(fan: Fan): adds a fan to a ventilation duct
  • add_connected_air_volume_box(air_volume_box: AirVolumeBox): adds air volume box connected to a ventilation duct
  • add_damper(damper: Damper): adds a damper installed in a ventilation duct
  • add_filter(hvac_filter: Filter): adds a filter installed in a ventilation duct
  • remove_heat_exchanger(heat_exchanger: HeatExchanger): adds a heat exchanger to a ventilation duct
  • remove_fan(fan: Fan): remove a fan from a ventilation duct
  • remove_connected_air_volume_box(air_volume_box: AirVolumeBox): removes an air volume box from a ventilation duct
  • remove_damper(damper: Damper): removes a damper from a ventilation duct
  • remove_filter(hvac_filter: Filter): removes a filter from a ventilation duct
  • get_heat_exchangers(search_terms: Dict) -> [HeatExchanger]: searches for heat exchangers installed in a ventilation duct based on attributes and their values
  • get_dampers(search_terms: Dict) -> [Damper]: searches for dampers installed in a ventilation duct based on attributes and their values
  • get_fans(search_terms: Dict) -> [Fan]: searches for fans installed in a ventilation duct based on attributes and their values
  • get_connected_air_volume_boxes(search_terms: Dict) -> [AirVolumeBox]: searches for air volume boxes connected to a ventilation duct based on attributes and their values
  • get_filters(search_terms: Dict) -> [Filter]: searches for air filters installed in a ventilation duct based on attributes and their values

DuctConnection

The DuctConnection class models various source and destination entities connected to ducts in buildings' HVAC systems.

Parent Classes

None

Relationships

  • DuctConnection has a one-to-many relationship with AbstractHVACComponent, e.g., HVAC components can be connected to ducts through the DuctConnection object
  • DuctConnection has a one-to-many relationship with AbstractSpace, e.g., various spaces, like rooms, can be connected to ducts through the DuctConnection object
  • DuctConnection has a one-to-many relationship with Duct, e.g., ducts can be connected to other ducts through the DuctConnection object

Attributes

  • source_entities: List[AbstractHVACComponent], source entities connected to a duct, e.g., duct
  • destination_entities: List[AbstractHVACComponent], destination entities connected to a duct, e.g., room
  • inside_entities: Union[List[Fan], List[HeatExchanger], List[Damper]], HVAC entities found within a ventilation duct. This is currently limited to fans, dampers, and heat exchangers
  • is_loop: bool (default is False) indicates if the source entities of a duct can become the destination entity and vice versa

Behaviours (Methods)

  • add_entity(entity_type: DuctConnectionEntityType, duct_entity: AbstractHVACComponent): adds a source, destination or inside entities to a DuctConnection
  • add_entity(entity_type: DuctConnectionEntityType, duct_entity: AbstractHVACComponent): removes a source, destination or inside entities from a DuctConnection
  • get_source_entities(search_terms: Dict) -> [AbstractHVACComponent]: searches for HVAC components installed as source entities based on attributes and their values
  • get_destination_entities(search_terms: Dict) -> [AbstractHVACComponent]: searches for HVAC components installed as destination entities based on attributes and their values
  • get_inside_entities(search_terms: Dict) -> [AbstractHVACComponent]: searches for HVAC components installed within a duct based on attributes and their values

Fan

The Fan class models fans that are parts of an HVAC system in a building.

Parent Classes

AbstractHVACComponent

Relationships

  • Duct has a one-to-many relationship with Fan

Attributes

  • power_state: PowerState, the power state of the fan
  • vfd: VariableFrequencyDrive, variable frequency drives that may be installed to control fans in an HVAC system

Behaviours (Methods)

Inherits methods from parent classes

Filter

The Fan class models filters that are installed in ventilation ducts.

Parent Classes

AbstractHVACComponent

Relationships

  • Duct has a one-to-many relationship with Filter

Attributes

  • filter_type: FilterType, the type of filter
  • air_flow_rate: BinaryMeasure, the rate of air flow usually measure in cubic feet per meter
  • life_span: int the lifespan of the filter measured in days
  • efficiency: int the efficiency of the filter measure with a number ranging from 1 to 16

Behaviours (Methods)

Inherits methods from parent classes

FanCoilUnit

The FanCoilUnit class models fan coil units that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

  • FanCoilUnit has a one-to-one relationship with HeatExchanger
  • FanCoilUnit has a one-to-one relationship with Fan

Attributes

  • heat_exchanger: HeatExchanger, the heat exchanger that forms part of the fan coil unit
  • fan: Fan, the fan that forms part of the fan coil unit (FCU)
  • fcu_type: FCUType, the type of fan coil unit
  • fcu_pipe_system: FCUPipeSystem, the fan coil unit pipe system, e.g., FCUPipeSystem.TWO_PIPE
  • is_ducted: bool (default is True) indicates if the FCU is connected to ventilation ducts

Behaviours (Methods)

Inherits methods from parent classes

HeatExchanger

The HeatExchanger class models heat exchangers that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • heat_exchanger_type: HeatExchangerType, the type of heat exchanger, e.g., SHELL_AND_TUBE
  • heat_exchanger_flow_type: HeatExchangerFlowType, the flow type of the heat exchanger, e.g., COUNTER

Behaviours (Methods)

Inherits methods from parent classes

HeatPump

The HeatPump class models heat pumps that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

  • HeatPump has a one-to-many relationship with HeatExchanger
  • HeatPump has a one-to-one relationship with Condenser
  • HeatPump has a one-to-one relationship with Compressor

Attributes

  • heat_exchangers: List[HeatExchanger], heat exchangers that form part of the heat pump
  • heat_source: HeatSource, the source of heat for the heat pump, e.g., AMBIENT_AIR
  • manufacturer: string (optional), the manufacturer of the heat pump
  • condenser: Condenser (optional), a condenser that may be part of the heat pump
  • compressor: Compressor (optional), a compressor that may be part of the heat pump

Behaviours (Methods)

  • add_heat_exchanger(heat_exchanger: HeatExchanger): adds a heat exchanger to a heat pump

VariableFrequencyDrive

The VariableFrequencyDrive class models variable frequency drives that are parts of an HVAC system in a building.

Parent Classes

AbstractHVACComponent

Relationships

Inherits relationships from parent classes

Attributes

  • motor_speed: float (default is 0.0), the motor speed of the variable frequency drive
  • max_motor_speed: float (default is 1000.0), the maximum motor speed of the variable frequency drive
  • speed_measure: MeasurementUnit (default is RELOLUTIONS_PER_MINUTE), the unit for measuring the motor speed of the variable frequency drive

Behaviours (Methods)

Inherits methods from parent classes

Pump

The Pump class models pumps that are parts of an HVAC system in a building.

Parent Classes

AbstractDuctConnectedComponent

Relationships

Inherits relationships from parent classes

Attributes

  • pump_type: PumpType, the type of heat exchanger, e.g., BOOSTER
  • flow_rate: BinaryMeasure (optional), the flow rate of the pump mostly measured in liters per second (L/s)
  • efficiency: float (optional), the efficiency of the pump (as a percentage, between 0 and 100)
  • power_consumption: BinaryMeasure (optional), the power consumption of the pump in kilowatts (kW)

Behaviours (Methods)

Inherits methods from parent classes