Structure - ptidejteam/tools4cities-metamenth GitHub Wiki

The Structure of MetamEnTh consists of spatial entities such as Building, Floor, Room, and OpenSpace and their relationships with themselves and other entities. These entities are relevant to recording the spatial locations of other entities (like Appliance, BuildingControlSystem, Sensor, and Actuator) and for tracking occupancy within the buildings.

Figure 1.0: MetamEnTh Structure, showing the various classes and their relationships

Figure 2.0: MetamEnTh Structure, showing the methods (behaviours) of various classes

Classes and Their Relationships

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

Building

The building class models different kinds of buildings with the following attributes and behaviours (methods).

Parent class

None

Relationships

  • Building has one-to-many relationship with WeatherStation.
  • Building has one-to-one relationship with SchedulableEntity.
  • Building has one-to-many relationship with Floor and must have at least one Floor.
  • Building has one-to-many relationship with Meter.
  • Building has one-to-many relationship with Zone.
  • Building has one-to-one relationship with Address.
  • Building has one-to-one relationship with Envelope.
  • Building has one-to-many relationship with BuildingControlSystem.

Attributes

  • construction_year: integer, the year of construction of the building
  • height: AbstractMeasure, consisting of a value and unit of measurement (e.g., meters) for the height of the building
  • floor_area: AbstractMeasure, consisting of a value and unit of measurement (e.g., meters) for the floor area of the building
  • internal_mass: AbstractMeasure, consisting of a value and unit of measurement for internal mass
  • address: Address, a class that defines the address of a building with additional attributes
  • building_type: BuildingType, a list (enumeration) of possible values of building types
  • terrain: TerrainType (optional), the terrain of the building, e.g., SUBURBS
  • solar_distribution: SolarDistributionType (optional), the solar distribution of the building, e.g., FULL_EXTERIOR
  • schedulable_entity: SchedulableEntity (optional), an object that models the operational schedules of a building
  • envelope: Envelope (optional), a class with additional attributes that define the envelope of a building
  • floors: List[Floor], a list of floors (a class with additional attributes) of a building
  • meters: List[Meter] (optional), a list of meters (a class with additional attributes) in a building
  • weather_stations: List[WeatherStation] (optional), a list of weather stations (a class with additional attributes) a building has
  • zones: List[Zone] (optional), a list of various zones (a class with additional attributes) in the building
  • control_systems: List[BuildingControlSystem] a list of control systems that the building have
  • track_state: bool (default is False), if set to true, keep track of value changes for building instance attributes

Behaviours (Methods)

  • add_weather_station(weather_station: WeatherStation): adds a weather station to the building
  • remove_weather_station(weather_station: WeatherStation): removes a weather station from the building
  • add_meter(meter: AbstractReader): adds a meter to the building
  • remove_meter(meter: AbstractReader): removes a meter from the building
  • add_floors(floors: List[Floor]): adds a floor to the building
  • remove_floor(floor: Floor): removes a floor from the building
  • get_floor_by_uid(uid: str) -> Floor: searches for a floor by its unique identifier
  • get_floor_by_number(floor_number: int) -> Floor: searches for a floor by its floor number
  • get_floors(search_terms: Dict) -> [Floors]: search for floors based on attribute values, e.g., {'number':2, 'floor_type': FloorType.REGULAR}
  • get_weather_station_by_name(name: str) -> WeatherStation: searches for a weather station by name
  • get_weather_station_by_uid(uid: str) -> WeatherStation: searches for a weather station by its unique identifier
  • get_weather_stations(search_terms: Dict) -> [WeatherStation]: searches for weather stations based on attribute values, e.g., {'name': 'WS 1'}
  • get_meter_by_uid(uid: str) -> AbstractReader: searches for a meter by its unique identifier
  • get_meter_by_type(meter_type: MeterType) -> [AbstractReader]: searches for meters based on the meter_type attribute
  • get_meters(search_terms: Dict) -> [AbstractReader]: searches for meters based on all meter attribute values, e.g., {'meter_type': MeterType.ELECTRICITY}
  • get_zone_by_name(name: str) -> Zone: searches for a zone in a building given the name of the zone
  • get_zone_by_uid(uid: str) -> Zone: searches for a zone in a building given the unique identifier of the zone
  • get_zones(search_terms: Dict) -> Zone: searches for zone in a building based on all zone attribute values, e.g., {'zone_type': ZoneType.HVAC}
  • add_room(floor_uid: str, name: str, area: AbstractMeasure, room_type: RoomType, location: str): adds a room to a building floor
  • add_open_space(floor_uid: str, name: str, area: AbstractMeasure, space_type: OpenSpaceType, location: str): adds an open space to a building floor

Envelope

This class defines a building's outer (and inner) covering with multiple Covers.

Parent Class

None

Relationships

An Envelope has a one-to-many relationship with a Cover.

Attributes

  • covers: List[Cover], a list of covers (e.g., wall, roof) associated with the building.

Behaviours (Methods)

  • add_cover(cover: Cover): adds a cover to the building
  • get_covers_by_uid(uid: str) -> Cover: retrieves a cover by its unique identifier
  • get_covers(search_terms: Dict) -> [Cover]: retrieves covers based on specified attributes and their values

Cover

This class defines the cover that makes up the envelope of a building.

Parent Class

None

Relationships

A Cover has a one-to-many relationship with Layer.

Attributes

  • cover_type: CoverType, the type of building cover
  • building_orientation: BuildingOrientation, the direction of the buiilding for the defined cover, e.g., BuildingOrientation.NORTH
  • floor_number: int: the floor where the cover is located
  • neighbours: Dict: defines the neighbour covers that sorround a cover
  • layers: List[Layer], a list of layers (e.g., external wall) in the building cover

Behaviours (Methods)

  • add_layer(layer: Layer): adds a layer (e.g., external wall) to the building cover
  • get_layer_by_uid(uid: str) -> Layer: retrieves a layer by its unique identifier
  • get_layers(search_terms: Dict) -> [Layer]: retrieves layers based on specified attributes and their values
  • add_neighbours(cover: Cover, neighbour_type: str): adds a neighbour to a cover
  • get_neighbour(neighbour_type: str) -> Union[str, None]: returns the UID of a neighbour cover

Layer

This class defines a layer in the cover of a building.

Parent Class

None

Relationships

A Layer has a one-to-one relationship with Material.

Attributes

  • height: AbstractMeasure, consisting of a value and unit of measurement (e.g., cm) for the height of the layer
  • length: AbstractMeasure, consisting of a value and unit of measurement (e.g., cm) for the length of the layer
  • thickness: AbstractMeasure, consisting of a value and unit of measurement (e.g., cm) for the thickness of the layer
  • material: Material, the material that makes up the layer
  • roughness: LayerRoughness, the roughness of the layer
  • has_vapour_barrier: bool, indicates whether the layer has a vapour barrier
  • has_air_barrier: bool, indicates whether the layer has an air barrier

Behaviours (Methods)

  • No specific methods provided.

Material

The Material class defines the material a layer in a building cover comprises.

Parent Class

None

Attributes

  • description: string, a description of the material
  • material_type: MaterialType, the type of material
  • density: AbstractMeasure, consisting of a value and unit of measurement (e.g., kg/m^3) for the density of the material
  • heat_capacity: AbstractMeasure, consisting of a value and unit of measurement (e.g., J/kg·K) for the heat capacity of the material
  • thermal_transmittance: AbstractMeasure, consisting of a value and unit of measurement (e.g., W/m^2·K) for the thermal transmittance of the material
  • thermal_resistance: AbstractMeasure, consisting of a value and unit of measurement (e.g., m^2·K/W) for the thermal resistance of the material
  • thermal_conductivity (optional): AbstractMeasure, consisting of a value and unit of measurement (e.g., W/m.K) measuring the thermal conductivity of the material
  • solar_heat_gain_coefficient: float (optional), the solar heat gain coefficient of the material
  • thermal_absorptance: float (optional), a value from 0 to 1 measuring the thermal absorptance of the material
  • solar_absorptance: float (optional), a value from 0 to 1 measuring the solar absorptance of the material
  • visible_absorptance: float (optional), a value from 0 to 1 measuring the visible absorptance of the material

Behaviours (Methods)

  • No specific methods provided.

AbstractSpace

This abstract class defines attributes and methods common to all space entities: Floor, Room and OpenSpace.

Parent Class

AbstractZonalEntity

Relationships

  • All AbstractSpace have one-to-many relationship with Zone.
  • All AbstractSpace have one-to-one relationship with SchedulableEntity.

Attributes

  • area: AbstractMeasure, a value and measurement unit for the area of the space
  • location: str (optional), what word location of the space
  • zones: List[Zone] (optional), a list of zones (a class with additional attributes) associated with the space
  • schedules: List[OperationalSchedule] (optional), a list of operational schedules for the space

Behaviours (Methods)

None. This class inherit methods from the parent class.

AbstractFloorSpace

This class defines common properties (attributes) and behaviours common to spaces on a building floor. It inherits all the attributes and behaviours of AbstractSpace.

Parent Class

AbstractSpace AbstractDynamicEntity

Relationships

  • All AbstractFloorSpace have one-to-many relationships with AbstractFloorSpace (a space on a floor can have another space as an adjacent space) and AbstractTransducer.
  • AbstractFloorSpace has one-to-many relationship with Appliance.
  • AbstractFloorSpace has one-to-many relationship with AbstractCommonEnergySystem.
  • AbstractFloorSpace has one-to-many relationship with AbstractVentilationSystem.
  • AbstractFloorSpace has one-to-many relationship with AbstractHVACComponent.
  • AbstractFloorSpace has one-to-one relationship with Meter.

Attributes

  • area: AbstractMeasure, representing the area of the floor space with a value of measurement unit
  • name: string, the name of the floor space
  • location: string (optional), the location of the floor space
  • adjacent_spaces: List[AbstractFloorSpace] (optional), a list of adjacent floor spaces
  • transducers: List[AbstractTransducer] (optional), a list of transducers associated with the floor space
  • meter: Meter (optional), the meter in this space
  • hvac_components: Union[List[AbstractHVACComponent], List[AbstractVentilationComponent]], the HVAC entities that are located within floor spaces
  • energy_systems: [AbstractCommonEnergySystem], the energy systems that are located within floor spaces

Behaviours (Methods)

  • add_adjacent_space(adjacent_space: AbstractFloorSpace): adds an adjacent floor space
  • remove_adjacent_space(adjacent_space: AbstractFloorSpace): removes an adjacent floor space
  • add_transducer(new_transducer: AbstractTransducer): adds a transducer to the floor space
  • remove_transducer(new_transducer: AbstractTransducer): removes a transducer from the floor space
  • add_appliance(appliance: Appliance): adds an appliance to floor spaces, e.g., room
  • remove_appliance(appliance: Appliance): removes an appliance from floor spaces
  • add_hvac_component(hvac_component: Union[AbstractHVACComponent, AbstractVentilationComponent]): adds an HVAC component to floor spaces
  • remove_hvac_component(hvac_component: Union[AbstractHVACComponent, AbstractVentilationComponent]): removes an HVAC component from floor spaces
  • get_hvac_components(search_terms: Dict = None) -> Union[List[AbstractHVACComponent], List[AbstractVentilationComponent]]: searches for HVAC components in floor spaces based on attributes and their values
  • get_adjacent_space_by_name(name: str) -> AbstractFloorSpace: searches for adjacent spaces in floor spaces given the name
  • get_adjacent_space_by_uid(uid: str) -> AbstractFloorSpace: searchers for adjacent spaces in floor spaces given their unique identifier
  • get_adjacent_spaces(search_terms: Dict = None) -> [AbstractFloorSpace]: searches for adjacent spaces in floor spaces based on attributes and their values
  • get_appliance_by_name(name: str) -> Appliance: searches for an appliance in floor spaces given the name of the appliance
  • get_appliance_by_uid(uid: str) -> Appliance: searches for an appliance in floor spaces given the unique identifier of the appliance
  • get_appliances(search_terms: Dict = None) -> [Appliance]: searches for appliances in floor spaces based on attributes and their values
  • add_energy_system(self, energy_system: AbstractCommonEnergySystem): adds an energy system to floor spaces
  • remove_energy_system(self, energy_system: AbstractCommonEnergySystem): removes an energy system from floor spaces
  • get_energy_systems(self, search_terms: Dict = None) -> [AbstractCommonEnergySystem]: searches for energy systems in floor spaces based on attributes and their values

Floor

This class defines a building's floor. The Floor class inherits all the properties and behaviours from AbstractSpace.

Parent Class

AbstractSpace

Relationships

  • Floor has a one-to-many relationship with Room and a one-to-many relationship with OpenSpace.

Attributes

  • description: string, a description of the floor
  • number: integer, the floor number
  • floor_type: FloorType, the type of floor
  • open_spaces: List[OpenSpace], a list of open spaces on the floor
  • rooms: List[Room], a list of rooms on the floor
  • location: what word location of the floor
  • height: AbstractMeasure, the height of the floor

NB: A Floor must have at least one RoomorOpenSpace.`

Behaviours (Methods)

  • add_open_spaces(open_spaces: List['OpenSpace']): Adds one or multiple OpenSpaces to the floor
  • add_rooms(rooms: List['Room']): Adds one or multiple rooms to the floor
  • remove_open_space(open_space: OpenSpace): Removes an open space from the floor
  • remove_room(room: Room): Removes a room from the floor
  • get_open_space_by_uid(uid: str) -> OpenSpace: Retrieves an open space given the UID
  • get_room_by_uid(uid: str) -> Room: Retrieves a room given the UID
  • get_open_space_by_name(name: str) -> OpenSpace: Retrieves an open space given the name
  • get_room_by_name(name: str) -> Room: Retrieves a room given the name
  • get_rooms(search_term: Dict) -> [Room]: Retrieves rooms based on attribute values
  • get_open_spaces(search_term: Dict) -> [OpenSpace]: Retrieves open spaces based on attribute values

Room

Room defines a room on the Floor of a Building. Room inherits all the properties and behaviours of AbstractFloorSpace.

Parent Class

AbstractFloorSpace

Attributes

  • name: string, the name of the room
  • room_type: RoomType, the type of the room

Behaviours (Methods)

None.

OpenSpace

OpenSpace defines open spaces, e.g., corridors, on the Floor of a Building. OpenSpace inherits all the properties and behaviours of AbstractFloorSpace.

Parent Class

AbstractFloorSpace

Attributes

  • space_type: OpenSpaceType, the type of open space

Behaviours (Methods)

None