honeybee-energy 1.116.106__py3-none-any.whl

honeybee_energy/result/match.py

@@ -0,0 +1,202 @@
+# coding=utf-8
+"""Utilities for matching Model geometry with energy simulation results."""
+from __future__ import division
+
+import re
+
+from honeybee.typing import clean_ep_string
+from honeybee.door import Door
+from honeybee.aperture import Aperture
+from honeybee.face import Face
+
+
+def match_rooms_to_data(
+        data_collections, rooms, invert_multiplier=False, space_based=False,
+        zone_correct_mult=True):
+    """Match honeybee Rooms to the Zone-level data collections from SQLiteResult.
+
+    This method ensures that Room multipliers are correctly output for a given
+    EnergyPlus output.
+
+    Args:
+        data_collections: An array of data collections that will matched to
+            simulation results. Data collections can be of any class (eg.
+            MonthlyCollection, DailyCollection) but they should all have headers
+            with metadata dictionaries with 'Zone' or 'System' keys. These keys
+            will be used to match the data in the collections to the input rooms.
+        rooms: An array of honeybee Rooms, which will be matched to the data_collections.
+            The length of these Rooms does not have to match the data_collections.
+        invert_multiplier: Boolean to note whether the output room multiplier should be
+            included when the data type values already account for the multiplier
+            (False) or when they do not (True). (Default: False).
+        space_based: Boolean to note whether the result is reported on the EnergyPlus
+            Space level instead of the Zone level. In this case, the matching to
+            the Room will account for the fact that the Space name is the Room
+            name with _Space added to it. (Default: False).
+        zone_correct_mult: Boolean to note whether the multiplier in the returned result
+            should be divided by the number of Rooms within each zone when
+            space_based is False. This is useful for ensuring that, overall,
+            values reported on the zone level and matched to Rooms are not counted
+            more than once for zones with multiple Rooms. Essentially, multiplying
+            each Room data collection by the multiplier before summing results
+            together ensures that the final summed result is accurate. Setting
+            this to False will make the multiplier in the result equal to the
+            Room.multiplier property, which may be useful for certain visualizations
+            where rooms are to be colored with the total result for their parent
+            zone. (Default: True).
+
+    Returns:
+        An array of tuples that contain matched rooms and data collections. All
+        tuples have a length of 3 with the following:
+
+        -   room -- A honeybee Room object.
+
+        -   data_collection -- A data collection that matches the honeybee Room.
+
+        -   multiplier -- An integer for the Room multiplier, which may be useful
+            for calculating total results.
+    """
+    # extract the zone identifier from each of the data collections
+    zone_ids = []
+    use_mult = False
+    for data in data_collections:
+        if 'Zone' in data.header.metadata:
+            zone_ids.append(data.header.metadata['Zone'])
+        else:  # it's HVAC system data and we need to see if it's matchable
+            hvac_id = data.header.metadata['System']
+            use_mult = True
+            if ' IDEAL LOADS AIR SYSTEM' in hvac_id:  # convention of E+ HVAC Templates
+                zone_ids.append(hvac_id.split(' IDEAL LOADS AIR SYSTEM')[0])
+            elif '..' in hvac_id:  # convention used for service hot water
+                zone_ids.append(hvac_id.split('..')[-1])
+                use_mult = False if 'Gain' in data.header.metadata['type'] else True
+            else:
+                use_mult = False
+                zone_ids.append(hvac_id)
+    if invert_multiplier:
+        use_mult = not use_mult
+    if space_based:
+        zone_ids = [zid.replace('_SPACE', '') for zid in zone_ids]
+
+    # count the number of rooms in each zone to zone-correct the multiplier
+    if not space_based and zone_correct_mult:
+        zone_counter = {}
+        for room in rooms:
+            z_id = clean_ep_string(room.zone)
+            try:
+                zone_counter[z_id] += 1
+            except KeyError:  # first room found in the zone
+                zone_counter[z_id] = 1
+
+    # loop through the rooms and match the data to them
+    matched_tuples = []  # list of matched rooms and data collections
+    for room in rooms:
+        if space_based:
+            rm_id, zc = room.identifier.upper(), 1
+        else:
+            z_id = clean_ep_string(room.zone)
+            rm_id = z_id.upper()
+            zc = zone_counter[z_id] if zone_correct_mult else 1
+        for i, data_id in enumerate(zone_ids):
+            if data_id == rm_id:
+                mult = 1 if not use_mult else room.multiplier
+                matched_tuples.append((room, data_collections[i], mult / zc))
+                break
+
+    return matched_tuples
+
+
+def match_faces_to_data(data_collections, faces):
+    """Match honeybee faces/sub-faces to data collections from SQLiteResult.
+
+    This method will correctly match triangulated apertures and doors with a
+    merged version of the relevant data_collections.
+
+    Args:
+        data_collections: An array of data collections that will be matched to
+            the input faces Data collections can be of any class (eg.
+            MonthlyCollection, DailyCollection) but they should all have headers
+            with metadata dictionaries with 'Surface' keys. These keys will be
+            used to match the data in the collections to the input faces.
+        faces: An array of honeybee Faces, Apertures, and/or Doors which will be
+            matched to the data_collections. Note that a given input Face should
+            NOT have its child Apertures or Doors as a separate item.
+
+    Returns:
+        An array of tuples that contain matched faces/sub-faces and data collections.
+        All tuples have a length of 2 with the following:
+
+        -   face -- A honeybee Face, Aperture, or Door object.
+
+        -   data_collection -- A data collection that matches the Face,
+            Aperture, or Door.
+    """
+    matched_tuples = []  # list of matched faces and data collections
+
+    flat_f = []  # flatten the list of nested apertures and doors in the faces
+    for face in faces:
+        if isinstance(face, Face):
+            flat_f.append(face)
+            for ap in face.apertures:
+                flat_f.append(ap)
+            for dr in face.doors:
+                flat_f.append(dr)
+        elif isinstance(face, (Aperture, Door)):
+            flat_f.append(face)
+        else:
+            raise ValueError('Expected honeybee Face, Aperture, Door or Shade '
+                             'for match_faces_to_data. Got {}.'.format(type(face)))
+
+    # extract the surface id from each of the data collections
+    srf_ids = []
+    tri_srf_ids = {}  # track data collections from triangulated apertures/doors
+    tri_pattern = re.compile(r".*\.\.\d")
+    for data in data_collections:
+        if 'Surface' in data.header.metadata:
+            srf_ids.append(data.header.metadata['Surface'])
+            if tri_pattern.match(data.header.metadata['Surface']) is not None:
+                base_name = re.sub(r'(\.\.\d*)', '', data.header.metadata['Surface'])
+                try:
+                    tri_srf_ids[base_name].append(data)
+                except KeyError:  # first triangulated piece found
+                    tri_srf_ids[base_name] = [data]
+
+    # loop through the faces and match the data to them
+    for face in flat_f:
+        f_id = face.identifier.upper()
+        for i, data_id in enumerate(srf_ids):
+            if data_id == f_id:
+                matched_tuples.append((face, data_collections[i]))
+                break
+        else:  # check to see if it's a triangulated sub-face
+            try:
+                data_colls = tri_srf_ids[f_id]
+                matched_tuples.append(
+                    (face, _merge_collections(data_colls, f_id)))
+            except KeyError:
+                pass  # the face could not be matched with any data
+    return matched_tuples
+
+
+def _merge_collections(data_collections, surface_id):
+    """Combine several data collections for a triangulated surface into one.
+
+    This method will automatically decide to either sum the collection data or
+    average it depending on whether the data collection data_type is cumulative.
+
+    Args:
+        data_collections: A list of data collections to be merged.
+        surface_id: The identifier of the combined surface, encompassing
+            all triangulated pieces.
+    """
+    # total all of the values in the data collections
+    merged_data = data_collections[0]
+    for data in data_collections[1:]:
+        merged_data = merged_data + data
+    # divide by the number of collections if the data type is not cumulative
+    if not data_collections[0].header.data_type.cumulative:
+        merged_data = merged_data / len(data_collections)
+    # create the final data collection
+    merged_data = merged_data.duplicate()  # duplicate to avoid editing the header
+    merged_data.header.metadata['Surface'] = surface_id
+    return merged_data

honeybee_energy/result/osw.py

@@ -0,0 +1,90 @@
+# coding=utf-8
+"""Module for parsing OpenStudio Workflow (OSW) files."""
+from __future__ import division
+
+import os
+import json
+
+
+class OSW(object):
+    """Object for parsing OpenStudio Workflow (OSW) files.
+
+    Args:
+        file_path: Full path to an OSW file.
+
+    Properties:
+        * file_path
+        * file_dict
+        * stdout
+        * warnings
+        * errors
+        * error_tracebacks
+    """
+
+    def __init__(self, file_path):
+        """Initialize OSW"""
+        assert os.path.isfile(file_path), 'No file was found at {}'.format(file_path)
+        assert file_path.endswith('.osw'), \
+            '{} is not an OSW file ending in .osw.'.format(file_path)
+        self._file_path = file_path
+        self._load_contents()
+        self._parse_contents()
+
+    @property
+    def file_path(self):
+        """Get the path to the .osw file."""
+        return self._file_path
+
+    @property
+    def file_dict(self):
+        """Get a dictionary of all contents in the file."""
+        return self._file_dict
+
+    @property
+    def stdout(self):
+        """Get a list of strings for all of the stdout of each step of the .osw file."""
+        return self._stdout
+
+    @property
+    def warnings(self):
+        """Get a list of strings for all of the warnings found in the .osw file."""
+        return self._warnings
+
+    @property
+    def errors(self):
+        """Get a list of strings for all of the fatal errors found in the .osw file."""
+        return self._errors
+
+    @property
+    def error_tracebacks(self):
+        """Get a list of strings for the tracebacks found in the .osw file."""
+        return self._error_tracebacks
+
+    def _load_contents(self):
+        """Parse all of the contents of a file path."""
+        with open(self._file_path) as json_file:
+            self._file_dict = json.load(json_file)
+
+    def _parse_contents(self):
+        """Sort the contents of the error file into warnings and errors."""
+        self._stdout = []
+        self._warnings = []
+        self._errors = []
+        self._error_tracebacks = []
+        try:
+            for step in self.file_dict['steps']:
+                result = step['result']
+                self._stdout.append(result['stdout'])
+                self._warnings.extend(result['step_warnings'])
+                for error in result['step_errors']:
+                    self._error_tracebacks.append(error)
+                    self._errors.append(error.split('\n')[0])
+        except KeyError:  # no results yet
+            pass
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'OSW: {}'.format(self.file_path)

honeybee_energy/result/rdd.py

@@ -0,0 +1,59 @@
+# coding=utf-8
+"""Module for parsing EnergyPlus Result Data Dictionary (RDD) files."""
+from __future__ import division
+
+from honeybee.search import filter_array_by_keywords
+import os
+
+
+class RDD(object):
+    """Object for parsing EnergyPlus Result Data Dictionary (RDD) files.
+
+    Args:
+        file_path: Full path to a RDD file that was generated by EnergyPlus.
+
+    Properties:
+        * file_path
+        * output_names
+    """
+
+    def __init__(self, file_path):
+        """Initialize RDD"""
+        assert os.path.isfile(file_path), 'No file was found at {}'.format(file_path)
+        assert file_path.endswith('.rdd'), \
+            '{} is not an RDD file ending in .rdd.'.format(file_path)
+        self._file_path = file_path
+        self._output_names = None
+
+    @property
+    def file_path(self):
+        """Get the path to the .rdd file."""
+        return self._file_path
+
+    @property
+    def output_names(self):
+        """Get a list of all output names in the .rdd file."""
+        if not self._output_names:
+            self._parse_outputs()
+        return self._output_names
+
+    def filter_outputs_by_keywords(self, keywords):
+        """Get a list of outputs in the RDD file filtered by keyword.
+
+        Args:
+            keywords: A list of keywords that will be used to filter the output names.
+        """
+        return filter_array_by_keywords(self.output_names, keywords, True)
+
+    def _parse_outputs(self):
+        """Parse all of the outputs from the file."""
+        with open(self._file_path) as rdd_result:
+            self._output_names = tuple(line.split(',')[-2] for line in rdd_result
+                                       if not line.startswith('!'))
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Energy RDD Result: {}'.format(self.file_path)

honeybee_energy/result/zsz.py

@@ -0,0 +1,190 @@
+# coding=utf-8
+"""Module for parsing EnergyPlus ZSZ csv result files into Ladybug DataCollections."""
+from __future__ import division
+
+from ladybug.futil import csv_to_matrix
+from ladybug.datacollection import HourlyContinuousCollection
+from ladybug.header import Header
+from ladybug.analysisperiod import AnalysisPeriod
+from ladybug.dt import Date
+from ladybug.datatype.power import Power
+from ladybug.datatype.massflowrate import MassFlowRate
+
+import os
+from datetime import datetime
+
+
+class ZSZ(object):
+    """Object for parsing EnergyPlus Zone Sizing (ZSZ) csv result files.
+
+    Args:
+        file_path: Full path to a ZSZ csv file that was generated by EnergyPlus.
+        cooling_date: A ladybug Date object for the cooling design day. This is needed
+            as the ZSZ file contains no information about the dates of the loads.
+        heating_date: A ladybug Date object for the heating design day. This is needed
+            as the ZSZ file contains no information about the dates of the loads.
+
+    Properties:
+        * file_path
+        * cooling_date
+        * heating_date
+        * timestep
+        * cooling_load_data
+        * heating_load_data
+        * cooling_flow_data
+        * heating_flow_data
+    """
+    # a list if keywords to identify design day names from room names in headers
+    DES_DAY_KEYWORDS = (' CLG ', ' HTG ', ' DESIGN DAY ')
+
+    def __init__(self, file_path, cooling_date=Date(1, 1), heating_date=Date(1, 1)):
+        """Initialize ZSZ"""
+        # check that the file exists
+        assert os.path.isfile(file_path), 'No file was found at {}'.format(file_path)
+        assert file_path.endswith('.csv'), \
+            '{} is not an CSV file ending in .csv.'.format(file_path)
+        self._file_path = file_path
+
+        # parse the data in the file
+        data_mtx = csv_to_matrix(file_path)
+
+        # extract the header and the peak values
+        headers = data_mtx[0][:]  # copy the list
+        del headers[0]
+        peak = data_mtx[-3][:]  # copy the list
+        del peak[0]
+        del data_mtx[0]
+        for i in range(3):
+            del data_mtx[-1]
+        self._headers = headers
+        self._peak = peak
+
+        # process the timestep of the data
+        data_mtx = list(zip(*data_mtx))
+        time1 = datetime.strptime(data_mtx[0][0], '%H:%M:%S')
+        time2 = datetime.strptime(data_mtx[0][1], '%H:%M:%S')
+        t_delta = time2 - time1
+        self._timestep = int(3600 / t_delta.seconds)
+        self._cooling_date = cooling_date
+        self._heating_date = heating_date
+        self._cool_a_period = AnalysisPeriod(
+            cooling_date.month, cooling_date.day, 0,
+            cooling_date.month, cooling_date.day, 23, timestep=self._timestep)
+        self._heat_a_period = AnalysisPeriod(
+            heating_date.month, heating_date.day, 0,
+            heating_date.month, heating_date.day, 23, timestep=self._timestep)
+
+        # process the body of the data
+        del data_mtx[0]
+        self._data = data_mtx
+
+        # properties to be computed upon request
+        self._cooling_load_data = None
+        self._heating_load_data = None
+        self._cooling_flow_data = None
+        self._heating_flow_data = None
+
+    @property
+    def file_path(self):
+        """Get the path to the .rdd file."""
+        return self._file_path
+
+    @property
+    def cooling_date(self):
+        """Get the date object assigned to the cooling design day."""
+        return self._cooling_date
+
+    @property
+    def heating_date(self):
+        """Get the date object assigned to the heating design day."""
+        return self._heating_date
+
+    @property
+    def timestep(self):
+        """Get the timestep of the data in the file."""
+        return self._timestep
+
+    @property
+    def cooling_load_data(self):
+        """Get a list of HourlyContinuousCollections for zone cooling load.
+
+        There will be one data collection per conditioned zone in the model. Data
+        collections are at the timestep of this object and values are in Watts.
+        """
+        if self._cooling_load_data is None:
+            self._cooling_load_data = self._process_collections(
+                'Summer Design Day Sensible Cooling Load', 'Des Sens Cool Load [W]', 'W')
+        return self._cooling_load_data
+
+    @property
+    def heating_load_data(self):
+        """Get a list of HourlyContinuousCollections for zone heating load.
+
+        There will be one data collection per conditioned zone in the model. Data
+        collections are at the timestep of this object and values are in Watts.
+        """
+        if self._heating_load_data is None:
+            self._heating_load_data = self._process_collections(
+                'Winter Design Day Heating Load', 'Des Heat Load [W]', 'W')
+        return self._heating_load_data
+
+    @property
+    def cooling_flow_data(self):
+        """Get a list of HourlyContinuousCollections for zone cooling mass flow.
+
+        There will be one data collection per conditioned zone in the model. Data
+        collections are at the timestep of this object and values are in m3/s.
+        """
+        if self._cooling_flow_data is None:
+            self._cooling_flow_data = self._process_collections(
+                'Summer Design Day Cooling Mass Flow',
+                'Des Cool Mass Flow [kg/s]', 'kg/s')
+        return self._cooling_flow_data
+
+    @property
+    def heating_flow_data(self):
+        """Get a list of HourlyContinuousCollections for zone heating mass flow.
+
+        There will be one data collection per conditioned zone in the model. Data
+        collections are at the timestep of this object and values are in m3/s.
+        """
+        if self._heating_flow_data is None:
+            self._heating_flow_data = self._process_collections(
+                'Winter Design Day Heating Flow', 'Des Heat Mass Flow [kg/s]', 'kg/s')
+        return self._heating_flow_data
+
+    def _process_collections(self, description, data_type_text, unit):
+        """Convert the raw data in the hidden _data property to data collections."""
+        data_type = Power() if unit == 'W' else MassFlowRate()
+        a_per = self._cool_a_period if 'Summer' in description else self._heat_a_period
+        collections = []
+        for i, col_head in enumerate(self._headers):
+            if data_type_text in col_head:
+                # try to differentiate the Zone name from the design day name
+                c_head, zone_names, end_found = col_head.split(':')[:-1], [], False
+                for name in c_head:
+                    for kwrd in self.DES_DAY_KEYWORDS:
+                        if kwrd in name:
+                            end_found = True
+                            break
+                    else:
+                        zone_names.append(name)
+                    if end_found:
+                        break
+                if len(zone_names) == len(c_head):  # we did not find it
+                    zone_name = c_head[0]
+                else:
+                    zone_name = ':'.join(zone_names)
+                # create the header
+                metadata = {'type': description, 'Zone': zone_name}
+                head = Header(data_type, unit, a_per, metadata)
+                collections.append(HourlyContinuousCollection(
+                    head, [float(val) for val in self._data[i]]))
+        return collections
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Energy ZSZ Result: {}'.format(self.file_path)