honeybee-energy 1.116.106__py3-none-any.whl

honeybee_energy/properties/shade.py

@@ -0,0 +1,314 @@
+# coding=utf-8
+"""Shade Energy Properties."""
+from honeybee.typing import clean_rad_string
+from honeybee.checkdup import is_equivalent
+
+from ..construction.shade import ShadeConstruction
+from ..schedule.ruleset import ScheduleRuleset
+from ..schedule.fixedinterval import ScheduleFixedInterval
+from ..generator.pv import PVProperties
+
+from ..lib.constructions import generic_context
+from ..lib.constructionsets import generic_construction_set
+
+
+class ShadeEnergyProperties(object):
+    """Energy Properties for Honeybee Shade.
+
+    Args:
+        host: A honeybee_core Shade object that hosts these properties.
+        construction: An optional ShadeConstruction object to set the reflectance
+            and specularity of the Shade. The default is set by a ConstructionSet
+            if the shade is the parent to an object. Otherwise, if it is an
+            orphaned shade, the default is a completely diffuse construction
+            with 0.2 visible and solar reflectance.
+        transmittance_schedule: An optional schedule to set the transmittance
+            of the shade, which can vary throughout the day or year. Default
+            is None for a completely opaque object.
+        pv_properties: An optional PVProperties object to specify photovoltaic
+            behavior of the Shade. If None, the Shade will have no Photovoltaic
+            properties. Note that the normal of the Shade is important in
+            determining the performance of the shade as a PV geometry.
+
+    Properties:
+        * host
+        * construction
+        * transmittance_schedule
+        * pv_properties
+        * is_construction_set_on_object
+    """
+
+    __slots__ = ('_host', '_construction', '_transmittance_schedule', '_pv_properties')
+
+    def __init__(self, host, construction=None, transmittance_schedule=None,
+                 pv_properties=None):
+        """Initialize Shade energy properties."""
+        self._host = host
+        self.construction = construction
+        self.transmittance_schedule = transmittance_schedule
+        self.pv_properties = pv_properties
+
+    @property
+    def host(self):
+        """Get the Shade object hosting these properties."""
+        return self._host
+
+    @property
+    def construction(self):
+        """Get or set a ShadeConstruction for the shade.
+
+        If the construction is not set on the shade-level, then it will be assigned
+        based on the ConstructionSet assigned to the parent Room.  If the parent Room's
+        ConstructionSet has no construction for the Shade type, it will be assigned
+        using the honeybee default generic ConstructionSet. If there is no parent
+        Room, it will be the generic context construction.
+        """
+        if self._construction:  # set by user
+            return self._construction
+        elif not self._host.has_parent:
+            return generic_context if self._host.is_detached else \
+                generic_construction_set.shade_construction
+        else:
+            c_set = self._parent_construction_set(self._host.parent)
+            if c_set is None:
+                c_set = generic_construction_set
+        return c_set.shade_construction
+
+    @construction.setter
+    def construction(self, value):
+        if value is not None:
+            assert isinstance(value, ShadeConstruction), \
+                'Expected ShadeConstruction. Got {}.'.format(type(value))
+            value.lock()  # lock editing in case construction has multiple references
+        self._construction = value
+
+    @property
+    def transmittance_schedule(self):
+        """Get or set the transmittance schedule of the shade."""
+        return self._transmittance_schedule
+
+    @transmittance_schedule.setter
+    def transmittance_schedule(self, value):
+        if value is not None:
+            assert isinstance(value, (ScheduleRuleset, ScheduleFixedInterval)), \
+                'Expected schedule for shade transmittance schedule. ' \
+                'Got {}.'.format(type(value))
+            if value.schedule_type_limit is not None:
+                assert value.schedule_type_limit.unit == 'fraction', 'Transmittance ' \
+                    'schedule should be fractional [Dimensionless]. Got a schedule ' \
+                    'of unit_type [{}].'.format(value.schedule_type_limit.unit_type)
+            value.lock()  # lock editing in case schedule has multiple references
+        self._transmittance_schedule = value
+
+    @property
+    def pv_properties(self):
+        """Get or set a PVProperties object for photovoltaic behavior of the Shade."""
+        return self._pv_properties
+
+    @pv_properties.setter
+    def pv_properties(self, value):
+        if value is not None:
+            assert isinstance(value, PVProperties), \
+                'Expected PVProperties. Got {}.'.format(type(value))
+            value.lock()  # lock editing in case construction has multiple references
+        self._pv_properties = value
+
+    @property
+    def is_construction_set_on_object(self):
+        """Boolean noting if construction is assigned on the level of this Shade.
+
+        This is opposed to having the construction assigned by a ConstructionSet.
+        """
+        return self._construction is not None
+
+    def reset_construction_to_set(self):
+        """Reset the construction and transmittance schedule of this Shade to default.
+
+        This means that the Shade's construction will be assigned by a ConstructionSet.
+        """
+        self._construction = None
+        self._transmittance_schedule = None
+
+    def radiance_modifier_solar(self):
+        """Get a Radiance modifier that combines the construction and transmittance.
+
+        Note that only the first value from the transmittance schedule will be used
+        to create the Trans modifier and so this method is really only intended for
+        cases of constant transmittance schedules. If there is no transmittance
+        schedule, a plastic material will be returned.
+        """
+        return self._radiance_modifier(self.construction.solar_reflectance)
+
+    def radiance_modifier_visible(self):
+        """Get a Radiance modifier that combines the construction and transmittance.
+
+        Note that only the first value from the transmittance schedule will be used
+        to create the Trans modifier and so this method is really only intended for
+        cases of constant transmittance schedules. If there is no transmittance
+        schedule, a plastic material will be returned.
+        """
+        return self._radiance_modifier(self.construction.visible_reflectance)
+
+    @classmethod
+    def from_dict(cls, data, host):
+        """Create ShadeEnergyProperties from a dictionary.
+
+        Note that the dictionary must be a non-abridged version for this
+        classmethod to work.
+
+        Args:
+            data: A dictionary representation of ShadeEnergyProperties with the
+                format below.
+            host: A Shade object that hosts these properties.
+
+        .. code-block:: python
+
+            {
+            "type": 'ShadeEnergyProperties',
+            "construction": {},  # A ShadeConstruction dictionary
+            "transmittance_schedule": {},  # A transmittance schedule dictionary
+            "pv_properties": {}  # A PVProperties dictionary
+            }
+        """
+        assert data['type'] == 'ShadeEnergyProperties', \
+            'Expected ShadeEnergyProperties. Got {}.'.format(data['type'])
+
+        new_prop = cls(host)
+        if 'construction' in data and data['construction'] is not None:
+            new_prop.construction = ShadeConstruction.from_dict(data['construction'])
+        if 'transmittance_schedule' in data and \
+                data['transmittance_schedule'] is not None:
+            sch_dict = data['transmittance_schedule']
+            if sch_dict['type'] == 'ScheduleRuleset':
+                new_prop.transmittance_schedule = \
+                    ScheduleRuleset.from_dict(data['transmittance_schedule'])
+            elif sch_dict['type'] == 'ScheduleFixedInterval':
+                new_prop.transmittance_schedule = \
+                    ScheduleFixedInterval.from_dict(data['transmittance_schedule'])
+            else:
+                raise ValueError(
+                    'Expected non-abridged Schedule dictionary for Shade '
+                    'transmittance_schedule. Got {}.'.format(sch_dict['type']))
+        if 'pv_properties' in data and data['pv_properties'] is not None:
+            new_prop.pv_properties = PVProperties.from_dict(data['pv_properties'])
+        return new_prop
+
+    def apply_properties_from_dict(self, abridged_data, constructions, schedules):
+        """Apply properties from a ShadeEnergyPropertiesAbridged dictionary.
+
+        Args:
+            abridged_data: A ShadeEnergyPropertiesAbridged dictionary (typically
+                coming from a Model).
+            constructions: A dictionary of constructions with constructions identifiers
+                as keys, which will be used to re-assign constructions.
+            schedules: A dictionary of schedules with schedule identifiers as keys,
+                which will be used to re-assign schedules.
+        """
+        if 'construction' in abridged_data and abridged_data['construction'] is not None:
+            try:
+                self.construction = constructions[abridged_data['construction']]
+            except KeyError:
+                raise ValueError('Shade construction "{}" was not found in '
+                                 'constructions.'.format(abridged_data['construction']))
+        if 'transmittance_schedule' in abridged_data and \
+                abridged_data['transmittance_schedule'] is not None:
+            self.transmittance_schedule = \
+                schedules[abridged_data['transmittance_schedule']]
+        if 'pv_properties' in abridged_data and \
+                abridged_data['pv_properties'] is not None:
+            self.pv_properties = PVProperties.from_dict(abridged_data['pv_properties'])
+
+    def to_dict(self, abridged=False):
+        """Return energy properties as a dictionary.
+
+        Args:
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version (True).
+                Default: False.
+        """
+        base = {'energy': {}}
+        base['energy']['type'] = 'ShadeEnergyProperties' if not \
+            abridged else 'ShadeEnergyPropertiesAbridged'
+        if self._construction is not None:
+            base['energy']['construction'] = \
+                self._construction.identifier if abridged else \
+                self._construction.to_dict()
+        if self.transmittance_schedule is not None:
+            base['energy']['transmittance_schedule'] = \
+                self.transmittance_schedule.identifier if abridged else \
+                self.transmittance_schedule.to_dict()
+        if self.pv_properties is not None:
+            base['energy']['pv_properties'] = self.pv_properties.to_dict()
+        return base
+
+    def duplicate(self, new_host=None):
+        """Get a copy of this object.
+
+        Args:
+            new_host: A new Shade object that hosts these properties.
+                If None, the properties will be duplicated with the same host.
+        """
+        _host = new_host or self._host
+        return ShadeEnergyProperties(
+            _host, self._construction, self._transmittance_schedule, self._pv_properties)
+
+    def is_equivalent(self, other):
+        """Check to see if these energy properties are equivalent to another object.
+
+        This will only be True if all properties match (except for the host) and
+        will otherwise be False.
+        """
+        if not is_equivalent(self._construction, other._construction):
+            return False
+        if not is_equivalent(
+                self._transmittance_schedule, other._transmittance_schedule):
+            return False
+        if not is_equivalent(self._pv_properties, other._pv_properties):
+            return False
+        return True
+
+    def _radiance_modifier(self, ref):
+        """Get a Radiance modifier that respects the transmittance schedule.
+
+        Args:
+            ref: The reflectance to be used in the modifier.
+        """
+        # check to be sure that the honeybee-radiance installed
+        try:
+            from honeybee_radiance.modifier.material import Trans
+        except ImportError as e:
+            raise ImportError('honeybee_radiance library must be installed to use '
+                              'Shade radiance_modifier methods. {}'.format(e))
+
+        # create the modifier from the properties
+        if self.transmittance_schedule is None:
+            return self.construction._to_radiance(ref)
+        else:
+            mod_id = '{}_mod'.format(clean_rad_string(self.host.identifier))
+            if isinstance(self.transmittance_schedule, ScheduleRuleset):
+                trans = self.transmittance_schedule.default_day_schedule.values[0]
+            else:
+                trans = self.transmittance_schedule.values[0]
+            avg_ref = (1 - trans) * ref
+            return Trans.from_average_properties(
+                mod_id, average_reflectance=avg_ref, average_transmittance=trans,
+                is_specular=self.construction.is_specular, is_diffusing=False)
+
+    @staticmethod
+    def _parent_construction_set(host_parent):
+        """Recursively search through host parents to find a ConstructionSet."""
+        if hasattr(host_parent.properties.energy, 'construction_set'):
+            # we found the room with the construction set
+            return host_parent.properties.energy.construction_set
+        elif host_parent.has_parent:
+            # we found an aperture or face that could have a room with a construction set
+            return ShadeEnergyProperties._parent_construction_set(host_parent.parent)
+        else:
+            # there is no parent room
+            return None
+
+    def ToString(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Shade Energy Properties: [host: {}]'.format(self.host.display_name)

honeybee_energy/properties/shademesh.py

@@ -0,0 +1,262 @@
+# coding=utf-8
+"""Shade Energy Properties."""
+from honeybee.typing import clean_rad_string
+from honeybee.checkdup import is_equivalent
+
+from ..construction.shade import ShadeConstruction
+from ..schedule.ruleset import ScheduleRuleset
+from ..schedule.fixedinterval import ScheduleFixedInterval
+
+from ..lib.constructions import generic_context
+from ..lib.constructionsets import generic_construction_set
+
+
+class ShadeMeshEnergyProperties(object):
+    """Energy Properties for Honeybee ShadeMesh.
+
+    Args:
+        host: A honeybee_core ShadeMesh object that hosts these properties.
+        construction: An optional ShadeConstruction object to set the reflectance
+            and specularity of the Shade. If None, it will be a generic context
+            construction that is completely diffuse with 0.2 visible and solar
+            reflectance. Unless it is building attached, in which case it will be
+            set by the default generic ConstructionSet.
+        transmittance_schedule: An optional schedule to set the transmittance
+            of the shade, which can vary throughout the day or year. Default
+            is None for a completely opaque object.
+
+    Properties:
+        * host
+        * construction
+        * transmittance_schedule
+        * is_construction_set_on_object
+    """
+
+    __slots__ = ('_host', '_construction', '_transmittance_schedule')
+
+    def __init__(self, host, construction=None, transmittance_schedule=None):
+        """Initialize ShadeMesh energy properties."""
+        self._host = host
+        self.construction = construction
+        self.transmittance_schedule = transmittance_schedule
+
+    @property
+    def host(self):
+        """Get the ShadeMesh object hosting these properties."""
+        return self._host
+
+    @property
+    def construction(self):
+        """Get or set a ShadeConstruction for the shade mesh object.
+
+        If the construction is not set on the shade-level, then it will be the
+        generic context construction or the generic exterior shade construction
+        if it is not detached.
+        """
+        if self._construction:  # set by user
+            return self._construction
+        return generic_context if self._host.is_detached else \
+            generic_construction_set.shade_construction
+
+    @construction.setter
+    def construction(self, value):
+        if value is not None:
+            assert isinstance(value, ShadeConstruction), \
+                'Expected ShadeConstruction. Got {}.'.format(type(value))
+            value.lock()  # lock editing in case construction has multiple references
+        self._construction = value
+
+    @property
+    def transmittance_schedule(self):
+        """Get or set the transmittance schedule of the shade."""
+        return self._transmittance_schedule
+
+    @transmittance_schedule.setter
+    def transmittance_schedule(self, value):
+        if value is not None:
+            assert isinstance(value, (ScheduleRuleset, ScheduleFixedInterval)), \
+                'Expected schedule for shade mesh transmittance schedule. ' \
+                'Got {}.'.format(type(value))
+            if value.schedule_type_limit is not None:
+                assert value.schedule_type_limit.unit == 'fraction', 'Transmittance ' \
+                    'schedule should be fractional [Dimensionless]. Got a schedule ' \
+                    'of unit_type [{}].'.format(value.schedule_type_limit.unit_type)
+            value.lock()  # lock editing in case schedule has multiple references
+        self._transmittance_schedule = value
+
+    @property
+    def is_construction_set_on_object(self):
+        """Boolean noting if construction is assigned on the level of this Shade.
+
+        This is opposed to having the construction assigned by a ConstructionSet.
+        """
+        return self._construction is not None
+
+    def reset_construction_to_set(self):
+        """Reset the construction and transmittance schedule of this Shade to default.
+
+        This means that the Shade's construction will be assigned by a ConstructionSet.
+        """
+        self._construction = None
+        self._transmittance_schedule = None
+
+    def radiance_modifier_solar(self):
+        """Get a Radiance modifier that combines the construction and transmittance.
+
+        Note that only the first value from the transmittance schedule will be used
+        to create the Trans modifier and so this method is really only intended for
+        cases of constant transmittance schedules. If there is no transmittance
+        schedule, a plastic material will be returned.
+        """
+        return self._radiance_modifier(self.construction.solar_reflectance)
+
+    def radiance_modifier_visible(self):
+        """Get a Radiance modifier that combines the construction and transmittance.
+
+        Note that only the first value from the transmittance schedule will be used
+        to create the Trans modifier and so this method is really only intended for
+        cases of constant transmittance schedules. If there is no transmittance
+        schedule, a plastic material will be returned.
+        """
+        return self._radiance_modifier(self.construction.visible_reflectance)
+
+    @classmethod
+    def from_dict(cls, data, host):
+        """Create ShadeMeshEnergyProperties from a dictionary.
+
+        Note that the dictionary must be a non-abridged version for this
+        classmethod to work.
+
+        Args:
+            data: A dictionary representation of ShadeMeshEnergyProperties with the
+                format below.
+            host: A Shade object that hosts these properties.
+
+        .. code-block:: python
+
+            {
+            "type": 'ShadeMeshEnergyProperties',
+            "construction": {},  # A ShadeConstruction dictionary
+            "transmittance_schedule": {}  # A transmittance schedule dictionary
+            }
+        """
+        assert data['type'] == 'ShadeMeshEnergyProperties', \
+            'Expected ShadeMeshEnergyProperties. Got {}.'.format(data['type'])
+
+        new_prop = cls(host)
+        if 'construction' in data and data['construction'] is not None:
+            new_prop.construction = ShadeConstruction.from_dict(data['construction'])
+        if 'transmittance_schedule' in data and \
+                data['transmittance_schedule'] is not None:
+            sch_dict = data['transmittance_schedule']
+            if sch_dict['type'] == 'ScheduleRuleset':
+                new_prop.transmittance_schedule = \
+                    ScheduleRuleset.from_dict(data['transmittance_schedule'])
+            elif sch_dict['type'] == 'ScheduleFixedInterval':
+                new_prop.transmittance_schedule = \
+                    ScheduleFixedInterval.from_dict(data['transmittance_schedule'])
+            else:
+                raise ValueError(
+                    'Expected non-abridged Schedule dictionary for Shade '
+                    'transmittance_schedule. Got {}.'.format(sch_dict['type']))
+        return new_prop
+
+    def apply_properties_from_dict(self, abridged_data, constructions, schedules):
+        """Apply properties from a ShadeMeshEnergyPropertiesAbridged dictionary.
+
+        Args:
+            abridged_data: A ShadeMeshEnergyPropertiesAbridged dictionary (typically
+                coming from a Model).
+            constructions: A dictionary of constructions with constructions identifiers
+                as keys, which will be used to re-assign constructions.
+            schedules: A dictionary of schedules with schedule identifiers as keys,
+                which will be used to re-assign schedules.
+        """
+        if 'construction' in abridged_data and abridged_data['construction'] is not None:
+            try:
+                self.construction = constructions[abridged_data['construction']]
+            except KeyError:
+                raise ValueError('Shade construction "{}" was not found in '
+                                 'constructions.'.format(abridged_data['construction']))
+        if 'transmittance_schedule' in abridged_data and \
+                abridged_data['transmittance_schedule'] is not None:
+            self.transmittance_schedule = \
+                schedules[abridged_data['transmittance_schedule']]
+
+    def to_dict(self, abridged=False):
+        """Return energy properties as a dictionary.
+
+        Args:
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version (True).
+                Default: False.
+        """
+        base = {'energy': {}}
+        base['energy']['type'] = 'ShadeMeshEnergyProperties' if not \
+            abridged else 'ShadeMeshEnergyPropertiesAbridged'
+        if self._construction is not None:
+            base['energy']['construction'] = \
+                self._construction.identifier if abridged else \
+                self._construction.to_dict()
+        if self.transmittance_schedule is not None:
+            base['energy']['transmittance_schedule'] = \
+                self.transmittance_schedule.identifier if abridged else \
+                self.transmittance_schedule.to_dict()
+        return base
+
+    def duplicate(self, new_host=None):
+        """Get a copy of this object.
+
+        Args:
+            new_host: A new Shade object that hosts these properties.
+                If None, the properties will be duplicated with the same host.
+        """
+        _host = new_host or self._host
+        return ShadeMeshEnergyProperties(
+            _host, self._construction, self._transmittance_schedule)
+
+    def is_equivalent(self, other):
+        """Check to see if these energy properties are equivalent to another object.
+
+        This will only be True if all properties match (except for the host) and
+        will otherwise be False.
+        """
+        if not is_equivalent(self._construction, other._construction):
+            return False
+        if not is_equivalent(
+                self._transmittance_schedule, other._transmittance_schedule):
+            return False
+        return True
+
+    def _radiance_modifier(self, ref):
+        """Get a Radiance modifier that respects the transmittance schedule.
+
+        Args:
+            ref: The reflectance to be used in the modifier.
+        """
+        # check to be sure that the honeybee-radiance installed
+        try:
+            from honeybee_radiance.modifier.material import Trans
+        except ImportError as e:
+            raise ImportError('honeybee_radiance library must be installed to use '
+                              'Shade radiance_modifier methods. {}'.format(e))
+
+        # create the modifier from the properties
+        if self.transmittance_schedule is None:
+            return self.construction._to_radiance(ref)
+        else:
+            mod_id = '{}_mod'.format(clean_rad_string(self.host.identifier))
+            if isinstance(self.transmittance_schedule, ScheduleRuleset):
+                trans = self.transmittance_schedule.default_day_schedule.values[0]
+            else:
+                trans = self.transmittance_schedule.values[0]
+            avg_ref = (1 - trans) * ref
+            return Trans.from_average_properties(
+                mod_id, average_reflectance=avg_ref, average_transmittance=trans,
+                is_specular=self.construction.is_specular, is_diffusing=False)
+
+    def ToString(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'ShadeMesh Energy Properties: [host: {}]'.format(self.host.display_name)

honeybee_energy/reader.py

@@ -0,0 +1,48 @@
+"""Methods to read from idf."""
+import re
+import os
+
+
+def clean_idf_file_contents(idf_file):
+    """Get the contents of an IDF file without any commented lines.
+
+    These comment lines might interfere with regex parsing if they are present.
+
+    Args:
+        idf_file: A path to an IDF file containing objects to be parsed.
+
+    Returns:
+        A single string for the clean IDF file contents.
+    """
+    assert os.path.isfile(idf_file), 'Cannot find an idf file at {}'.format(idf_file)
+    file_lines = []
+    with open(idf_file, 'r') as ep_file:
+        for line in ep_file:
+            if not line.startswith('!'):
+                file_lines.append(line)
+    return ''.join(file_lines)
+
+
+def parse_idf_string(idf_string, expected_type=None):
+    """Parse an EnergyPlus string of a single object into a list of values.
+
+    Args:
+        idf_string: An IDF string for a single EnergyPlus object.
+        expected_type: Text representing the expected start of the IDF object.
+            (ie. WindowMaterial:Glazing). If None, no type check will be performed.
+
+    Returns:
+        ep_fields -- A list of strings with each item in the list as a separate field.
+        Note that this list does NOT include the string for the start of the IDF
+        object. (ie. WindowMaterial:Glazing)
+    """
+    idf_string = idf_string.strip()
+    if expected_type is not None:
+        assert idf_string.startswith(expected_type), 'Expected EnergyPlus {} ' \
+            'but received a different object: {}'.format(expected_type, idf_string)
+    idf_strings = idf_string.split(';')
+    assert len(idf_strings) == 2, 'Received more than one object in idf_string.'
+    idf_string = re.sub(r'!.*\n', '', idf_strings[0])
+    ep_fields = [e_str.strip() for e_str in idf_string.split(',')]
+    ep_fields.pop(0)  # remove the EnergyPlus object name
+    return ep_fields

honeybee_energy/result/__init__.py

@@ -0,0 +1 @@
+"""honeybee-energy simulation settings."""