honeybee-energy 1.116.106__py3-none-any.whl

honeybee_energy/internalmass.py

@@ -0,0 +1,310 @@
+# coding=utf-8
+"""Room internal mass, including construction and surface area."""
+from __future__ import division
+
+from honeybee._lockable import lockable
+from honeybee.typing import valid_ep_string, float_positive
+from honeybee.units import conversion_factor_to_meters
+
+from .construction.opaque import OpaqueConstruction
+from .material.opaque import EnergyMaterialVegetation
+from .reader import parse_idf_string
+from .writer import generate_idf_string
+
+
+@lockable
+class InternalMass(object):
+    """Room internal mass, including construction and surface area.
+
+    Note that internal masses assigned this way cannot "see" solar radiation that
+    may potentially hit them and, as such, caution should be taken when using this
+    component with internal mass objects that are not always in shade. Masses are
+    factored into the the thermal calculations of the Room by undergoing heat
+    transfer with the indoor air.
+
+    Args:
+        identifier: Text string for a unique InternalMass ID. Must be < 100 characters
+            and not contain any EnergyPlus special characters. This will be used to
+            identify the object across a model and in the exported IDF.
+        construction: An OpaqueConstruction object that represents the material
+            that the internal thermal mass is composed of.
+        area: A number representing the surface area of the internal mass that
+            is exposed to the Room air. This value should always be in square
+            meters regardless of what units system the parent model is a part of.
+
+
+    Properties:
+        * identifier
+        * display_name
+        * construction
+        * area
+        * user_data
+    """
+    __slots__ = ('_identifier', '_display_name', '_construction', '_area',
+                 '_locked', '_user_data')
+
+    def __init__(self, identifier, construction, area):
+        self._locked = False  # unlocked by default
+        self.identifier = identifier
+        self._display_name = None
+        self.construction = construction
+        self.area = area
+        self._user_data = None
+
+    @property
+    def identifier(self):
+        """Get or set the text string for object identifier."""
+        return self._identifier
+
+    @identifier.setter
+    def identifier(self, identifier):
+        self._identifier = valid_ep_string(identifier)
+
+    @property
+    def display_name(self):
+        """Get or set a string for the object name without any character restrictions.
+
+        If not set, this will be equal to the identifier.
+        """
+        if self._display_name is None:
+            return self._identifier
+        return self._display_name
+
+    @display_name.setter
+    def display_name(self, value):
+        if value is not None:
+            try:
+                value = str(value)
+            except UnicodeEncodeError:  # Python 2 machine lacking the character set
+                pass  # keep it as unicode
+        self._display_name = value
+
+    @property
+    def construction(self):
+        """Get or set a Construction for the material the internal mass is composed of.
+        """
+        return self._construction
+
+    @construction.setter
+    def construction(self, value):
+        assert isinstance(value, OpaqueConstruction), \
+            'Expected Opaque Construction for InternalMass. Got {}'.format(type(value))
+        assert not isinstance(value.materials[0], EnergyMaterialVegetation), \
+            'InternalMass constructions cannot contain vegetation materials'
+        value.lock()  # lock editing in case construction has multiple references
+        self._construction = value
+
+    @property
+    def area(self):
+        """Get or set a number for the surface area of the mass exposed to the Room air.
+        """
+        return self._area
+
+    @area.setter
+    def area(self, value):
+        self._area = float_positive(value, 'internal mass area')
+
+    @property
+    def user_data(self):
+        """Get or set an optional dictionary for additional meta data for this object.
+
+        This will be None until it has been set. All keys and values of this
+        dictionary should be of a standard Python type to ensure correct
+        serialization of the object to/from JSON (eg. str, float, int, list, dict)
+        """
+        if self._user_data is not None:
+            return self._user_data
+
+    @user_data.setter
+    def user_data(self, value):
+        if value is not None:
+            assert isinstance(value, dict), 'Expected dictionary for honeybee_energy' \
+                'object user_data. Got {}.'.format(type(value))
+        self._user_data = value
+
+    @classmethod
+    def from_geometry(cls, identifier, construction, geometry, units='Meters'):
+        """Create an InternalMass object from a list of geometries.
+
+        Args:
+            identifier: Text string for a unique InternalMass ID. Must be < 100
+                characters and not contain any EnergyPlus special characters. This
+                will be used to identify the object across a model and in the
+                exported IDF.
+            construction: An OpaqueConstruction object that represents the material
+                that the internal thermal mass is composed of.
+            geometry: An array of Face3D representing the exposed surface of the
+                internal mass. Note that these Face3D are assumed to be one-sided
+                so, if they are meant to represent a 2-sided object, the Face3D
+                should be duplicated and offset.
+            units: Text for the units system of the geometry. Choose from the following:
+
+                * Meters
+                * Millimeters
+                * Feet
+                * Inches
+                * Centimeters
+        """
+        area = sum(geo.area for geo in geometry) * conversion_factor_to_meters(units)
+        return cls(identifier, construction, area)
+
+    @classmethod
+    def from_idf(cls, idf_string, construction_dict):
+        """Create an InternalMass object from an EnergyPlus IDF text string.
+
+        Args:
+            idf_string: A text string fully describing an EnergyPlus InternalMass
+                definition.
+            construction_dict: A dictionary with construction identifiers as keys
+                and honeybee construction objects as values. This will be used
+                to assign the construction to the InternalMass object.
+
+        Returns:
+            An InternalMass object loaded from the idf_string.
+        """
+        ep_strs = parse_idf_string(idf_string, 'InternalMass,')
+        obj_id = ep_strs[0].split('..')[0]
+        return cls(obj_id, construction_dict[ep_strs[1]], ep_strs[4])
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create an InternalMass object from a dictionary.
+
+        Note that the dictionary must be a non-abridged version for this
+        classmethod to work.
+
+        Args:
+            data: An InternalMass dictionary in following the format below.
+
+        .. code-block:: python
+
+            {
+            "type": 'InternalMass',
+            "identifier": 'Kitchen_Table_Wood_050',
+            "display_name": 'Kitchen Table',
+            "construction": {},  # OpaqueConstruction definition
+            "area": 5  # surface area of internal mass in square meters
+            }
+        """
+        assert data['type'] == 'InternalMass', \
+            'Expected InternalMass dictionary. Got {}.'.format(data['type'])
+        constr = OpaqueConstruction.from_dict(data['construction'])
+        new_obj = cls(data['identifier'], constr, data['area'])
+        if 'display_name' in data and data['display_name'] is not None:
+            new_obj.display_name = data['display_name']
+        if 'user_data' in data and data['user_data'] is not None:
+            new_obj.user_data = data['user_data']
+        return new_obj
+
+    @classmethod
+    def from_dict_abridged(cls, data, construction_dict):
+        """Create a InternalMass from an abridged dictionary.
+
+        Args:
+            data: An InternalMassAbridged dictionary.
+            construction_dict: A dictionary with construction identifiers as keys
+                and honeybee construction objects as values. This will be used
+                to assign the construction to the InternalMass object.
+
+        .. code-block:: python
+
+            {
+            "type": 'InternalMassAbridged',
+            "identifier": 'Kitchen_Table_Wood_050',
+            "display_name": 'Kitchen Table',
+            "construction": 'Hardwood_050'  # OpaqueConstruction identifier
+            "area": 5  # surface area of internal mass in square meters
+            }
+        """
+        assert data['type'] == 'InternalMassAbridged', \
+            'Expected InternalMassAbridged dictionary. Got {}.'.format(data['type'])
+        new_obj = cls(
+            data['identifier'], construction_dict[data['construction']], data['area'])
+        if 'display_name' in data and data['display_name'] is not None:
+            new_obj.display_name = data['display_name']
+        if 'user_data' in data and data['user_data'] is not None:
+            new_obj.user_data = data['user_data']
+        return new_obj
+
+    def to_idf(self, room_identifier, is_zone=True):
+        """IDF string representation of InternalMass object.
+
+        Note that this method only outputs a single string for the InternalMass
+        object and, to write everything needed to describe the object into an IDF,
+        this object's construction must also be written.
+
+        Args:
+            room_identifier: Text for the Room identifier that the InternalMass
+                object is assigned to.
+            is_zone: Boolean for whether the room_identifier refers to a Zone
+                object or a Space object. (Default: True).
+
+        .. code-block:: shell
+
+            InternalMass,
+                Zn002:IntM001,                !- Surface Name
+                INTERIOR,                     !- Construction Name
+                DORM ROOMS AND COMMON AREAS,  !- Zone or ZoneList Name
+                ,                             !- Space or SpaceList Name
+                408.7734;                     !- Total area exposed to Zone {m2}
+        """
+        int_m_id = '{}..{}'.format(self.identifier, room_identifier)
+        values = [int_m_id, self.construction.identifier]
+        if is_zone:
+            values.extend([room_identifier, '', self.area])
+        else:
+            values.extend(['', room_identifier, self.area])
+        comments = ('name', 'construction name', 'zone name', 'space name',
+                    'surface area')
+        return generate_idf_string('InternalMass', values, comments)
+
+    def to_dict(self, abridged=False):
+        """InternalMass dictionary representation.
+
+        Args:
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version
+                (True), which only specifies the identifiers of the
+                construction. (Default: False).
+        """
+        base = {'type': 'InternalMass'} if not abridged \
+            else {'type': 'InternalMassAbridged'}
+        base['identifier'] = self.identifier
+        base['construction'] = self.construction.to_dict() if not \
+            abridged else self.construction.identifier
+        base['area'] = self.area
+        if self._display_name is not None:
+            base['display_name'] = self.display_name
+        if self._user_data is not None:
+            base['user_data'] = self.user_data
+        return base
+
+    def duplicate(self):
+        """Get a copy of this object."""
+        return self.__copy__()
+
+    def __copy__(self):
+        new_obj = InternalMass(self.identifier, self.construction, self.area)
+        new_obj._display_name = self._display_name
+        new_obj._user_data = None if self._user_data is None else self._user_data.copy()
+        return new_obj
+
+    def __key(self):
+        """A tuple based on the object properties, useful for hashing."""
+        return (self.identifier, hash(self.construction), self.area)
+
+    def __hash__(self):
+        return hash(self.__key())
+
+    def __eq__(self, other):
+        return isinstance(other, InternalMass) and self.__key() == other.__key()
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'InternalMass: {}'.format(self.display_name)

honeybee_energy/lib/__init__.py

@@ -0,0 +1 @@
+"""Library of schedules, constructions, and other template objects."""

honeybee_energy/lib/_loadconstructions.py

@@ -0,0 +1,194 @@
+"""Load all materials and constructions from the IDF libraries."""
+from honeybee_energy.config import folders
+from honeybee_energy.construction.opaque import OpaqueConstruction
+from honeybee_energy.construction.window import WindowConstruction
+from honeybee_energy.construction.windowshade import WindowConstructionShade
+from honeybee_energy.construction.dynamic import WindowConstructionDynamic
+from honeybee_energy.construction.air import AirBoundaryConstruction
+from honeybee_energy.construction.dictutil import dict_abridged_to_construction, \
+    dict_to_construction
+
+from ._loadmaterials import _opaque_materials, _window_materials, _default_mats
+from ._loadschedules import _schedules
+
+import os
+import json
+
+
+# dictionary of all materials loaded from JSON
+_all_materials = _opaque_materials.copy()  # start with opaque materials
+_all_materials.update(_window_materials)  # add window constructions
+
+
+# empty dictionaries to hold idf-loaded materials and constructions
+_opaque_constructions = {}
+_window_constructions = {}
+_shade_constructions = {}
+
+# groups useful for construction classification
+_opa_types = (OpaqueConstruction, AirBoundaryConstruction)
+_win_types = (WindowConstruction, WindowConstructionShade, WindowConstructionDynamic)
+
+
+# first load the honeybee defaults
+with open(folders.defaults_file) as json_file:
+    default_data = json.load(json_file)['constructions']
+for con_dict in default_data:
+    constr = dict_abridged_to_construction(con_dict, _all_materials, _schedules, False)
+    constr.lock()
+    if isinstance(constr, _opa_types):
+        _opaque_constructions[con_dict['identifier']] = constr
+    elif isinstance(constr, _win_types):
+        _window_constructions[con_dict['identifier']] = constr
+    else:  # it's a shade construction
+        _shade_constructions[con_dict['identifier']] = constr
+_default_constrs = set(
+    list(_opaque_constructions.keys()) + list(_window_constructions.keys()) +
+    list(_shade_constructions.keys()))
+
+
+# then load honeybee extension data into a dictionary but don't make the objects yet
+_opaque_constr_standards_dict = {}
+_window_constr_standards_dict = {}
+_shade_constr_standards_dict = {}
+
+for ext_folder in folders.standards_extension_folders:
+    _data_dir = os.path.join(ext_folder, 'constructions')
+    _opaque_dir = os.path.join(_data_dir, 'opaque_construction.json')
+    if os.path.isfile(_opaque_dir):
+        with open(_opaque_dir, 'r') as f:
+            _opaque_constr_standards_dict.update(json.load(f))
+    _window_dir = os.path.join(_data_dir, 'window_construction.json')
+    if os.path.isfile(_window_dir):
+        with open(_window_dir, 'r') as f:
+            _window_constr_standards_dict.update(json.load(f))
+    _shade_dir = os.path.join(_data_dir, 'shade_construction.json')
+    if os.path.isfile(_shade_dir):
+        with open(_shade_dir, 'r') as f:
+            _shade_constr_standards_dict.update(json.load(f))
+
+
+# then load materials and constructions from the user-supplied files
+def lock_and_check_material(mat):
+    """Lock a material and check that it's not overwriting a default."""
+    mat.lock()
+    assert mat.identifier not in _default_mats, 'Cannot overwrite ' \
+        'default material "{}".'.format(mat.identifier)
+
+
+def lock_and_check_construction(constr):
+    """Lock a construction and check that it's not overwriting a default."""
+    constr.lock()
+    assert constr.identifier not in _default_constrs, 'Cannot overwrite ' \
+        'default construction "{}".'.format(constr.identifier)
+
+
+def load_construction_object(
+        con_dict, load_mats, load_sch, opaque_cons, window_cons, shade_cons,
+        misc_mats, misc_sch):
+    """Load a construction object from a dictionary and add it to the library dict."""
+    try:
+        constr = dict_abridged_to_construction(con_dict, load_mats, load_sch, False)
+        if constr is None:
+            constr = dict_to_construction(con_dict, False)
+            try:
+                misc_mats.extend(constr.materials)
+                if constr.has_frame:
+                    misc_mats.append(constr.frame)
+                if constr.has_shade:
+                    if constr.is_switchable_glazing:
+                        misc_mats.append(constr.switched_glass_material)
+            except AttributeError:  # construction without materials
+                pass
+            if isinstance(constr, (WindowConstructionShade, WindowConstructionDynamic)):
+                if constr.schedule is not None:
+                    misc_sch.append(constr.schedule)
+            elif isinstance(constr, AirBoundaryConstruction):
+                if constr.air_mixing_schedule is not None:
+                    misc_sch.append(constr.air_mixing_schedule)
+        if constr is not None:
+            lock_and_check_construction(constr)
+            if isinstance(constr, _opa_types):
+                opaque_cons[con_dict['identifier']] = constr
+            elif isinstance(constr, _win_types):
+                window_cons[con_dict['identifier']] = constr
+            else:  # it's a shade construction
+                shade_cons[con_dict['identifier']] = constr
+    except (TypeError, KeyError, ValueError):
+        try:  # see if the construction set is built with constructions in standards
+            import honeybee_energy.lib.materials as _m
+            if 'materials' in con_dict:
+                if con_dict['type'] == 'OpaqueConstructionAbridged':
+                    for mat in con_dict['materials']:
+                        load_mats[mat] = _m.opaque_material_by_identifier(mat)
+                    constr = dict_abridged_to_construction(
+                        con_dict, load_mats, load_sch, False)
+                    opaque_cons[con_dict['identifier']] = constr
+                elif con_dict['type'] == 'WindowConstructionAbridged':
+                    for mat in con_dict['materials']:
+                        load_mats[mat] = _m.window_material_by_identifier(mat)
+                    constr = dict_abridged_to_construction(
+                        con_dict, load_mats, load_sch, False)
+                    window_cons[con_dict['identifier']] = constr
+        except Exception:
+            pass  # not a Honeybee Construction JSON; possibly a comment
+
+
+def load_constructions_from_folder(
+        construction_lib_folder, loaded_materials, loaded_schedules):
+    """Load all of the construction objects from a construction standards folder.
+
+    Args:
+        construction_lib_folder: Path to a constructions sub-folder within a
+            honeybee standards folder.
+        loaded_materials: A dictionary of materials that have already been loaded
+            from the library.
+        loaded_schedules: A dictionary of materials that have already been loaded
+            from the library.
+    """
+    opaque_mats, window_mats = {}, {}
+    opaque_cons, window_cons, shade_cons = {}, {}, {}
+    misc_mats, misc_sch = [], []
+    for f in os.listdir(construction_lib_folder):
+        f_path = os.path.join(construction_lib_folder, f)
+        if os.path.isfile(f_path):
+            if f_path.endswith('.idf'):
+                constructions, materials = \
+                    OpaqueConstruction.extract_all_from_idf_file(f_path)
+                for mat in materials:
+                    lock_and_check_material(mat)
+                    opaque_mats[mat.identifier] = mat
+                for cnstr in constructions:
+                    lock_and_check_construction(cnstr)
+                    opaque_cons[cnstr.identifier] = cnstr
+                constructions, materials = \
+                    WindowConstruction.extract_all_from_idf_file(f_path)
+                for mat in materials:
+                    lock_and_check_material(mat)
+                    window_mats[mat.identifier] = mat
+                for cnstr in constructions:
+                    lock_and_check_construction(cnstr)
+                    window_cons[cnstr.identifier] = cnstr
+            if f_path.endswith('.json'):
+                with open(f_path) as json_file:
+                    data = json.load(json_file)
+                if 'type' in data:  # single object
+                    load_construction_object(
+                        data, loaded_materials, loaded_schedules,
+                        opaque_cons, window_cons, shade_cons, misc_mats, misc_sch)
+                else:  # a collection of several objects
+                    for constr_identifier in data:
+                        load_construction_object(
+                            data[constr_identifier], loaded_materials, loaded_schedules,
+                            opaque_cons, window_cons, shade_cons, misc_mats, misc_sch)
+    return opaque_cons, window_cons, shade_cons, opaque_mats, window_mats, \
+        misc_mats, misc_sch
+
+
+opaque_c, window_c, shade_c, opaque_m, window_m, misc_m, misc_s = \
+    load_constructions_from_folder(folders.construction_lib, _all_materials, _schedules)
+_opaque_materials.update(opaque_m)
+_window_materials.update(window_m)
+_opaque_constructions.update(opaque_c)
+_window_constructions.update(window_c)
+_shade_constructions.update(shade_c)

honeybee_energy/lib/_loadconstructionsets.py

@@ -0,0 +1,117 @@
+"""Load all construction sets from the JSON libraries."""
+from honeybee_energy.config import folders
+from honeybee_energy.constructionset import ConstructionSet
+
+from ._loadconstructions import _opaque_constructions, _window_constructions, \
+    _shade_constructions
+
+import os
+import json
+
+
+# make a dictionary of all constructions loaded from JSON
+_all_constructions = _opaque_constructions.copy()  # start with opaque constructions
+_all_constructions.update(_window_constructions)  # add window constructions
+_all_constructions.update(_shade_constructions)  # add shade constructions
+
+# empty dictionary to hold loaded construction sets
+_construction_sets = {}
+
+
+# first load the honeybee defaults
+with open(folders.defaults_file) as json_file:
+    default_data = json.load(json_file)['construction_sets']
+for cset_dict in default_data:
+    constructionset = ConstructionSet.from_dict_abridged(cset_dict, _all_constructions)
+    constructionset.lock()
+    _construction_sets[cset_dict['identifier']] = constructionset
+_default_sets = set(list(_construction_sets.keys()))
+
+
+# then load honeybee extension data into a dictionary but don't make the objects yet
+_construction_set_standards_dict = {}
+
+for ext_folder in folders.standards_extension_folders:
+    _data_dir = os.path.join(ext_folder, 'constructionsets')
+    for _c_set_json in os.listdir(_data_dir):
+        if _c_set_json.endswith('.json'):
+            _c_set_dir = os.path.join(_data_dir, _c_set_json)
+            with open(_c_set_dir, 'r') as f:
+                _construction_set_standards_dict.update(json.load(f))
+
+
+# then load construction sets from the user-supplied files
+def load_construction_set_object(cset_dict, load_cons, con_sets, misc_cons):
+    """Load a construction set object from a dictionary and add it to the lib dict."""
+    try:
+        if cset_dict['type'] == 'ConstructionSetAbridged':
+            cset = ConstructionSet.from_dict_abridged(cset_dict, load_cons)
+        else:
+            cset = ConstructionSet.from_dict(cset_dict)
+            misc_cons.extend(cset.modified_constructions)
+        cset.lock()
+        assert cset_dict['identifier'] not in _default_sets, 'Cannot overwrite ' \
+            'default construction set "{}".'.format(cset_dict['identifier'])
+        con_sets[cset_dict['identifier']] = cset
+    except Exception:
+        try:  # see if the construction set is built with constructions in standards
+            import honeybee_energy.lib.constructions as _c
+            for key in cset_dict:
+                if isinstance(cset_dict[key], dict):
+                    sub_dict = cset_dict[key]
+                    for sub_key in sub_dict:
+                        if sub_key == 'type' or sub_key in load_cons:
+                            continue
+                        if sub_dict[sub_key] is not None and \
+                                sub_dict[sub_key] not in load_cons:
+                            try:
+                                load_cons[sub_dict[sub_key]] = \
+                                    _c.opaque_construction_by_identifier(
+                                        sub_dict[sub_key])
+                            except ValueError:
+                                load_cons[sub_dict[sub_key]] = \
+                                    _c.window_construction_by_identifier(
+                                    sub_dict[sub_key])
+                elif key == 'shade_construction' and cset_dict[key] is not None \
+                        and cset_dict[key] not in load_cons:
+                    load_cons[cset_dict[key]] = \
+                        _c.shade_construction_by_identifier(cset_dict[key])
+                elif key == 'air_boundary_construction' \
+                        and cset_dict[key] is not None \
+                        and cset_dict[key] not in load_cons:
+                    load_cons[cset_dict[key]] = \
+                        _c.opaque_construction_by_identifier(cset_dict[key])
+            con_sets[cset_dict['identifier']] = \
+                ConstructionSet.from_dict_abridged(cset_dict, load_cons)
+        except Exception:
+            pass  # not a Honeybee ConstructionSet JSON; possibly a comment
+
+
+def load_constructionsets_from_folder(constructionset_lib_folder, loaded_constructions):
+    """Load all of the ConstructionSet objects from a constructionset standards folder.
+
+    Args:
+        constructionset_lib_folder: Path to a constructionsets sub-folder within a
+            honeybee standards folder.
+        loaded_constructions: A dictionary of constructions that have already
+            been loaded from the library.
+    """
+    con_sets, misc_cons = {}, []
+    for f in os.listdir(constructionset_lib_folder):
+        f_path = os.path.join(constructionset_lib_folder, f)
+        if os.path.isfile(f_path) and f_path.endswith('.json'):
+            with open(f_path, 'r') as json_file:
+                c_dict = json.load(json_file)
+            if 'type' in c_dict:  # single object
+                load_construction_set_object(
+                    c_dict, loaded_constructions, con_sets, misc_cons)
+            else:  # a collection of several objects
+                for c_id in c_dict:
+                    load_construction_set_object(
+                        c_dict[c_id], loaded_constructions, con_sets, misc_cons)
+    return con_sets, misc_cons
+
+
+loaded_sets, misc_c = \
+    load_constructionsets_from_folder(folders.constructionset_lib, _all_constructions)
+_construction_sets.update(loaded_sets)