honeybee-core 1.64.12__py3-none-any.whl

honeybee/boundarycondition.py

@@ -0,0 +1,358 @@
+"""Boundary Condition for Face, Aperture, Door."""
+import re
+
+from .typing import float_in_range, tuple_with_length
+from .altnumber import autocalculate
+
+
+class _BoundaryCondition(object):
+    """Base boundary condition class."""
+
+    __slots__ = ()
+
+    def __init__(self):
+        """Initialize Boundary condition."""
+
+    @property
+    def name(self):
+        """Get the name of the boundary condition (ie. 'Outdoors', 'Ground')."""
+        return self.__class__.__name__
+
+    @property
+    def view_factor(self):
+        """Get the view factor to the ground."""
+        return 'autocalculate'
+
+    @property
+    def sun_exposure_idf(self):
+        """Get a text string for sun exposure, which is write-able into an IDF."""
+        return 'NoSun'
+
+    @property
+    def wind_exposure_idf(self):
+        """ Get a text string for wind exposure, which is write-able into an IDF."""
+        return 'NoWind'
+
+    def to_dict(self):
+        """Get the boundary condition as a dictionary."""
+        return {'type': self.name}
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return self.name
+
+
+class Outdoors(_BoundaryCondition):
+    """Outdoor boundary condition.
+
+    Args:
+        sun_exposure: A boolean noting whether the boundary is exposed to sun.
+            Default: True.
+        wind_exposure: A boolean noting whether the boundary is exposed to wind.
+            Default: True.
+        view_factor: A number between 0 and 1 for the view factor to the ground.
+            This input can also be an Autocalculate object to signify that the view
+            factor automatically calculated.  Default: autocalculate.
+    """
+
+    __slots__ = ('_sun_exposure', '_wind_exposure', '_view_factor')
+
+    def __init__(self, sun_exposure=True, wind_exposure=True,
+                 view_factor=autocalculate):
+        """Initialize Outdoors boundary condition."""
+        assert isinstance(sun_exposure, bool), \
+            'Input sun_exposure must be a Boolean. Got {}.'.format(type(sun_exposure))
+        self._sun_exposure = sun_exposure
+        assert isinstance(wind_exposure, bool), \
+            'Input wind_exposure must be a Boolean. Got {}.'.format(type(wind_exposure))
+        self._wind_exposure = wind_exposure
+        if view_factor == autocalculate:
+            self._view_factor = autocalculate
+        else:
+            self._view_factor = float_in_range(
+                view_factor, 0.0, 1.0, 'view factor to ground')
+
+    @classmethod
+    def from_dict(cls, data):
+        """Initialize Outdoors BoundaryCondition from a dictionary.
+
+        Args:
+            data: A dictionary representation of the boundary condition.
+        """
+        assert data['type'] == 'Outdoors', 'Expected dictionary for Outdoors boundary ' \
+            'condition. Got {}.'.format(data['type'])
+        sun_exposure = True if 'sun_exposure' not in data else data['sun_exposure']
+        wind_exposure = True if 'wind_exposure' not in data else data['wind_exposure']
+        view_factor = autocalculate if 'view_factor' not in data or \
+            data['view_factor'] == autocalculate.to_dict() else data['view_factor']
+        return cls(sun_exposure, wind_exposure, view_factor)
+
+    @property
+    def sun_exposure(self):
+        """Get a boolean noting whether the boundary is exposed to sun."""
+        return self._sun_exposure
+
+    @property
+    def wind_exposure(self):
+        """Get a boolean noting whether the boundary is exposed to wind."""
+        return self._wind_exposure
+
+    @property
+    def view_factor(self):
+        """Get the view factor to the ground as a number or 'autocalculate'."""
+        return self._view_factor
+
+    @property
+    def sun_exposure_idf(self):
+        """Get a text string for sun exposure, which is write-able into an IDF."""
+        return 'NoSun' if not self.sun_exposure else 'SunExposed'
+
+    @property
+    def wind_exposure_idf(self):
+        """Get a text string for wind exposure, which is write-able into an IDF."""
+        return 'NoWind' if not self.wind_exposure else 'WindExposed'
+
+    def to_dict(self, full=False):
+        """Get the boundary condition as a dictionary.
+
+        Args:
+            full: Set to True to get the full dictionary which includes energy
+                simulation specific keys such as sun_exposure, wind_exposure and
+                view_factor. (Default: False).
+        """
+        bc_dict = {'type': self.name}
+        if full:
+            bc_dict['sun_exposure'] = self.sun_exposure
+            bc_dict['wind_exposure'] = self.wind_exposure
+            bc_dict['view_factor'] = autocalculate.to_dict() if \
+                self.view_factor == autocalculate else self.view_factor
+        return bc_dict
+
+    def __key(self):
+        """A tuple based on the object properties, useful for hashing."""
+        return (self.sun_exposure, self.wind_exposure, self.view_factor)
+
+    def __hash__(self):
+        return hash(self.__key())
+
+    def __eq__(self, other):
+        return isinstance(other, Outdoors) and self.__key() == other.__key()
+
+
+class Surface(_BoundaryCondition):
+    """Boundary condition when an object is adjacent to another object."""
+
+    __slots__ = ('_boundary_condition_objects',)
+
+    def __init__(self, boundary_condition_objects, sub_face=False):
+        """Initialize Surface boundary condition.
+
+        Args:
+            boundary_condition_objects: A list of up to 3 object identifiers that are
+                adjacent to this one. The first object is always immediately
+                adjacent and is of the same object type (Face, Aperture, Door). When
+                this boundary condition is applied to a Face, the second object in the
+                tuple will be the parent Room of the adjacent object. When the boundary
+                condition is applied to a sub-face (Door or Aperture), the second object
+                will be the parent Face of the adjacent sub-face and the third object
+                 will be the parent Room of the adjacent sub-face.
+            sub_face: Boolean to note whether this boundary condition is applied to a
+                sub-face (an Aperture or a Door) instead of a Face. (Default: False).
+        """
+        if sub_face:
+            self._boundary_condition_objects = tuple_with_length(
+                boundary_condition_objects, 3, str,
+                'boundary_condition_objects for Apertures or Doors')
+        else:
+            self._boundary_condition_objects = tuple_with_length(
+                boundary_condition_objects, 2, str,
+                'boundary_condition_objects for Faces')
+
+    @classmethod
+    def from_dict(cls, data, sub_face=False):
+        """Initialize Surface BoundaryCondition from a dictionary.
+
+        Args:
+            data: A dictionary representation of the boundary condition.
+            sub_face: Boolean to note whether this boundary condition is applied to a
+                sub-face (an Aperture or a Door) instead of a Face. Default: False.
+        """
+        assert data['type'] == 'Surface', 'Expected dictionary for Surface boundary ' \
+            'condition. Got {}.'.format(data['type'])
+        return cls(data['boundary_condition_objects'], sub_face)
+
+    @classmethod
+    def from_other_object(cls, other_object, sub_face=False):
+        """Initialize Surface boundary condition from an adjacent other object.
+
+        Args:
+            other_object: Another object (Face, Aperture, Door) of the same type
+                that this boundary condition is assigned.  This other_object will be
+                set as the adjacent object in this boundary condition.
+            sub_face: Boolean to note whether this boundary condition is applied to a
+                sub-face (an Aperture or a Door) instead of a Face. Default: False.
+        """
+        error_msg = 'Surface boundary conditions can only be assigned to objects' \
+            ' with parent Rooms.'
+        bc_objects = [other_object.identifier]
+        if other_object.has_parent:
+            bc_objects.append(other_object.parent.identifier)
+            if sub_face:
+                if other_object.parent.has_parent:
+                    bc_objects.append(other_object.parent.parent.identifier)
+                else:
+                    raise AttributeError(error_msg)
+        else:
+            raise AttributeError(error_msg)
+        return cls(bc_objects, sub_face)
+
+    @property
+    def boundary_condition_objects(self):
+        """Get a tuple of up to 3 object identifiers that are adjacent to this one.
+
+        The first object is always the one that is immediately adjacent and is of
+        the same object type (Face, Aperture, Door).
+        When this boundary condition is applied to a Face, the second object in the
+        tuple will be the parent Room of the adjacent object.
+        When the boundary condition is applied to a sub-face (Door or Aperture),
+        the second object will be the parent Face of the sub-face and the third
+        object will be the parent Room of the adjacent sub-face.
+        """
+        return self._boundary_condition_objects
+
+    @property
+    def boundary_condition_object(self):
+        """Get the identifier of the object adjacent to this one."""
+        return self._boundary_condition_objects[0]
+
+    def to_dict(self):
+        """Get the boundary condition as a dictionary.
+
+        Args:
+            full: Set to True to get the full dictionary which includes energy
+                simulation specific keys such as sun_exposure, wind_exposure and
+                view_factor. Default: False.
+        """
+        return {'type': self.name,
+                'boundary_condition_objects': self.boundary_condition_objects}
+
+    def __key(self):
+        """A tuple based on the object properties, useful for hashing."""
+        return self.boundary_condition_objects
+
+    def __hash__(self):
+        return hash(self.__key())
+
+    def __eq__(self, other):
+        return isinstance(other, Surface) and self.__key() == other.__key()
+
+
+class Ground(_BoundaryCondition):
+    """Ground boundary condition.
+
+    Args:
+        data: A dictionary representation of the boundary condition.
+    """
+    __slots__ = ()
+
+    @classmethod
+    def from_dict(cls, data):
+        """Initialize Ground BoundaryCondition from a dictionary."""
+        assert data['type'] == 'Ground', 'Expected dictionary for Ground boundary ' \
+            'condition. Got {}.'.format(data['type'])
+        return cls()
+
+    def __eq__(self, other):
+        return isinstance(other, Ground)
+
+
+class _BoundaryConditions(object):
+    """Boundary conditions."""
+
+    def __init__(self):
+        self._outdoors = Outdoors()
+        self._ground = Ground()
+        self._bc_name_dict = None
+
+    @property
+    def outdoors(self):
+        """Default outdoor boundary condition."""
+        return self._outdoors
+
+    @property
+    def ground(self):
+        """Default ground boundary condition."""
+        return self._ground
+
+    def surface(self, other_object, sub_face=False):
+        """Get a Surface boundary condition.
+
+        Args:
+            other_object: The other object that is adjacent to the one that will
+                bear this Surface boundary condition.
+            sub_face: Boolean to note whether the boundary condition is for a
+                sub-face (Aperture or Door) instead of a Face. (Default: False).
+        """
+        return Surface.from_other_object(other_object, sub_face)
+
+    def by_name(self, bc_name):
+        """Get a boundary condition object instance by its name.
+
+        This method will correct for capitalization as well as the presence of
+        spaces and underscores. Note that this method only works for boundary
+        conditions with all of their inputs defaulted.
+
+        Args:
+            bc_name: A boundary condition name.
+        """
+        if self._bc_name_dict is None:
+            self._build_bc_name_dict()
+        try:
+            return self._bc_name_dict[re.sub(r'[\s_]', '', bc_name.lower())]
+        except KeyError:
+            raise ValueError(
+                '"{}" is not a valid boundary condition name.\nChoose from the '
+                'following: {}'.format(bc_name, list(self._bc_name_dict.keys())))
+
+    def _build_bc_name_dict(self):
+        """Build a dictionary that can be used to lookup boundary conditions by name."""
+        attr = [atr for atr in dir(self) if not atr.startswith('_')]
+        clean_attr = [re.sub(r'[\s_]', '', atr.lower()) for atr in attr]
+        self._bc_name_dict = {}
+        for atr_name, atr in zip(clean_attr, attr):
+            try:
+                full_attr = getattr(self, '_' + atr)
+                self._bc_name_dict[atr_name] = full_attr
+            except AttributeError:
+                pass  # callable method that has no static default object
+
+    def __contains__(self, value):
+        return isinstance(value, _BoundaryCondition)
+
+
+boundary_conditions = _BoundaryConditions()
+
+
+def get_bc_from_position(positions, ground_depth=0):
+    """Return a boundary condition based on the relationship to a ground plane.
+
+    Positions that are entirely at or below the ground_depth will get a Ground
+    boundary condition. If there are any positions above the ground_depth, an
+    Outdoors boundary condition will be returned.
+
+    args:
+        positions: A list of ladybug_geometry Point3D objects representing the
+            vertices of an object.
+        ground_depth: The Z value above which positions are considered Outdoors
+            instead of Ground.
+
+    Returns:
+        Face type instance.
+    """
+    for position in positions:
+        if position.z > ground_depth:
+            return boundary_conditions.outdoors
+    return boundary_conditions.ground

honeybee/checkdup.py

@@ -0,0 +1,173 @@
+# coding=utf-8
+"""Utilities to check whether there are any duplicate values in a list of ids."""
+
+import collections
+
+
+def check_duplicate_identifiers(
+        objects_to_check, raise_exception=True, obj_name='', detailed=False,
+        code='000000', extension='Core', error_type='Duplicate Object Identifier'):
+    """Check whether there are duplicated identifiers across a list of objects.
+
+    Args:
+        objects_to_check: A list of honeybee objects across which duplicate
+            identifiers will be checked.
+        raise_exception: Boolean to note whether an exception should be raised if
+            duplicated identifiers are found. (Default: True).
+        obj_name: An optional name for the object to be included in the error
+            message. Fro example, 'Room', 'Face', 'Aperture'.
+        detailed: Boolean for whether the returned object is a detailed list of
+            dicts with error info or a string with a message. (Default: False).
+        code: Text for the error code. (Default: 0000).
+        extension: Text for the name of the Honeybee extension for which duplicate
+            identifiers are being evaluated. (Default: Core).
+        error_type: Text for the type of error. This should be directly linked
+            to the error code and should simply be a human-readable version of
+            the error code. (Default: Unknown Error).
+
+    Returns:
+        A message string indicating the duplicated identifiers (if detailed is False)
+        or a list of dictionaries with information about the duplicated identifiers
+        (if detailed is True). This string (or list) will be empty if no duplicates
+        were found.
+    """
+    detailed = False if raise_exception else detailed
+    obj_id_iter = (obj.identifier for obj in objects_to_check)
+    dup = [t for t, c in collections.Counter(obj_id_iter).items() if c > 1]
+    if len(dup) != 0:
+        if detailed:
+            # find the object display names
+            dis_names = []
+            for obj_id in dup:
+                dis_name = None
+                for obj in objects_to_check:
+                    if obj.identifier == obj_id:
+                        dis_name = obj.display_name
+                dis_names.append(dis_name)
+            err_list = []
+            for dup_id, dis_name in zip(dup, dis_names):
+                msg = 'There is a duplicated {} identifier: {}'.format(obj_name, dup_id)
+                dup_dict = {
+                    'type': 'ValidationError',
+                    'code': code,
+                    'error_type': error_type,
+                    'extension_type': extension,
+                    'element_type': obj_name,
+                    'element_id': [dup_id],
+                    'message': msg
+                }
+                if dis_name is not None:
+                    dup_dict['element_name'] = [dis_name]
+                err_list.append(dup_dict)
+            return err_list
+        msg = 'The following duplicated {} identifiers were found:\n{}'.format(
+            obj_name, '\n'.join(dup))
+        if raise_exception:
+            raise ValueError(msg)
+        return msg
+    return [] if detailed else ''
+
+
+def check_duplicate_identifiers_parent(
+        objects_to_check, raise_exception=True, obj_name='', detailed=False,
+        code='000000', extension='Core', error_type='Duplicate Object Identifier'):
+    """Check whether there are duplicated identifiers across a list of objects.
+
+    The error message will include the identifiers of top-level parents in order
+    to make it easier to find the duplicated objects in the model.
+
+    Args:
+        objects_to_check: A list of honeybee objects across which duplicate
+            identifiers will be checked. These objects must have the ability to
+            have parents for this method to run correctly.
+        raise_exception: Boolean to note whether an exception should be raised if
+            duplicated identifiers are found. (Default: True).
+        obj_name: An optional name for the object to be included in the error
+            message. For example, 'Room', 'Face', 'Aperture'.
+        detailed: Boolean for whether the returned object is a detailed list of
+            dicts with error info or a string with a message. (Default: False).
+        code: Text for the error code. (Default: 0000).
+        extension: Text for the name of the Honeybee extension for which duplicate
+            identifiers are being evaluated. (Default: Core).
+        error_type: Text for the type of error. This should be directly linked
+            to the error code and should simply be a human-readable version of
+            the error code. (Default: Unknown Error).
+
+    Returns:
+        A message string indicating the duplicated identifiers (if detailed is False)
+        or a list of dictionaries with information about the duplicated identifiers
+        (if detailed is True). This string (or list) will be empty if no duplicates
+        were found.
+    """
+    detailed = False if raise_exception else detailed
+    obj_id_iter = (obj.identifier for obj in objects_to_check)
+    dup = [t for t, c in collections.Counter(obj_id_iter).items() if c > 1]
+    if len(dup) != 0:
+        # find the relevant top-level parents
+        top_par, dis_names = [], []
+        for obj_id in dup:
+            rel_parents, dis_name = [], None
+            for obj in objects_to_check:
+                if obj.identifier == obj_id:
+                    dis_name = obj.display_name
+                    if obj.has_parent:
+                        try:
+                            par_obj = obj.top_level_parent
+                        except AttributeError:
+                            par_obj = obj.parent
+                        rel_parents.append(par_obj)
+            top_par.append(rel_parents)
+            dis_names.append(dis_name)
+        # if a detailed dictionary is requested, then create it
+        if detailed:
+            err_list = []
+            for dup_id, dis_name, rel_par in zip(dup, dis_names, top_par):
+                dup_dict = {
+                    'type': 'ValidationError',
+                    'code': code,
+                    'error_type': error_type,
+                    'extension_type': extension,
+                    'element_type': obj_name,
+                    'element_id': [dup_id]
+                }
+                if dis_name is not None:
+                    dup_dict['element_name'] = [dis_name]
+                msg = 'There is a duplicated {} identifier: {}'.format(obj_name, dup_id)
+                if len(rel_par) != 0:
+                    dup_dict['top_parents'] = []
+                    msg += '\n  Relevant Top-Level Parents:\n'
+                    for par_o in rel_par:
+                        par_dict = {
+                            'parent_type': par_o.__class__.__name__,
+                            'id': par_o.identifier,
+                            'name': par_o.display_name
+                        }
+                        dup_dict['top_parents'].append(par_dict)
+                        msg += '    {} "{}"\n'.format(
+                            par_o.__class__.__name__, par_o.full_id)
+                dup_dict['message'] = msg
+                err_list.append(dup_dict)
+            return err_list
+        # if just an error message is requested, then build it from the information
+        msg = 'The following duplicated {} identifiers were found:\n'.format(obj_name)
+        for obj_id, rel_par in zip(dup, top_par):
+            obj_msg = obj_id + '\n'
+            if len(rel_par) != 0:
+                obj_msg += '  Relevant Top-Level Parents:\n'
+                for par_o in rel_par:
+                    obj_msg += '    {} "{}"\n'.format(
+                        par_o.__class__.__name__, par_o.full_id)
+            msg += obj_msg
+        msg = msg.strip()
+        if raise_exception:
+            raise ValueError(msg)
+        return msg
+    return [] if detailed else ''
+
+
+def is_equivalent(object_1, object_2):
+    """Check if two objects are equal with an initial check for the same instance.
+    """
+    if object_1 is object_2:  # first see if they're the same instance
+        return True
+    return object_1 == object_2  # two objects that should have == operators

honeybee/cli/__init__.py

@@ -0,0 +1,118 @@
+"""
+Command Line Interface (CLI) entry point for honeybee and honeybee extensions.
+
+Use this file only to add command related to honeybee-core. For adding extra commands
+from each extention see below.
+
+Note:
+
+    Do not import this module in your code directly unless you are extending the command
+    line interface. For running the commands execute them from the command line or as a
+    subprocess (e.g. ``subprocess.call(['honeybee', 'viz'])``)
+
+Honeybee is using click (https://click.palletsprojects.com/en/7.x/) for creating the CLI.
+You can extend the command line interface from inside each extention by following these
+steps:
+
+1. Create a ``cli.py`` file in your extension.
+2. Import the ``main`` function from this ``honeybee.cli``.
+3. Add your commands and command groups to main using add_command method.
+4. Add ``import [your-extention].cli`` to ``__init__.py`` file to the commands are added
+   to the cli when the module is loaded.
+
+The good practice is to group all your extention commands in a command group named after
+the extension. This will make the commands organized under extension namespace. For
+instance commands for `honeybee-radiance` will be called like
+``honeybee radiance [radiance-command]``.
+
+
+.. code-block:: python
+
+    import click
+    from honeybee.cli import main
+
+    @click.group()
+    def radiance():
+        pass
+
+    # add commands to radiance group
+    @radiance.command('daylight-factor')
+    # ...
+    def daylight_factor():
+        pass
+
+
+    # finally add the newly created commands to honeybee cli
+    main.add_command(radiance)
+
+    # do not forget to import this module in __init__.py otherwise it will not be added
+    # to honeybee commands.
+
+Note:
+
+    For extension with several commands you can use a folder structure instead
+    of a single file. Refer to ``honeybee-radiance`` for an example.
+
+"""
+import click
+import sys
+import logging
+import json
+
+from ..config import folders
+from honeybee.cli.setconfig import set_config
+from honeybee.cli.validate import validate
+from honeybee.cli.compare import compare
+from honeybee.cli.create import create
+from honeybee.cli.edit import edit
+from honeybee.cli.lib import lib
+
+_logger = logging.getLogger(__name__)
+
+
+@click.group()
+@click.version_option()
+def main():
+    pass
+
+
+@main.command('config')
+@click.option('--output-file', help='Optional file to output the JSON string of '
+              'the config object. By default, it will be printed out to stdout',
+              type=click.File('w'), default='-', show_default=True)
+def config(output_file):
+    """Get a JSON object with all configuration information"""
+    try:
+        config_dict = {
+            'default_simulation_folder': folders.default_simulation_folder,
+            'honeybee_schema_version': folders.honeybee_schema_version_str,
+            'python_package_path': folders.python_package_path,
+            'python_scripts_path': folders.python_scripts_path,
+            'python_exe_path': folders.python_exe_path,
+            'python_version': folders.python_version_str,
+            'default_standards_folder': folders.default_standards_folder
+        }
+        output_file.write(json.dumps(config_dict, indent=4))
+    except Exception as e:
+        _logger.exception('Failed to retrieve configurations.\n{}'.format(e))
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+@main.command('viz')
+def viz():
+    """Check if honeybee is flying!"""
+    click.echo('viiiiiiiiiiiiizzzzzzzzz!')
+
+
+main.add_command(set_config, name='set-config')
+main.add_command(validate)
+main.add_command(compare)
+main.add_command(create)
+main.add_command(edit)
+main.add_command(lib)
+
+
+if __name__ == "__main__":
+    main()