dragonfly-doe2 0.11.3__py2.py3-none-any.whl → 0.12.1__py2.py3-none-any.whl

dragonfly_doe2/__init__.py

@@ -1 +1 @@
-"""dragonfly-doe2 library."""
+import dragonfly_doe2._extend_dragonfly

dragonfly_doe2/__main__.py

@@ -1,5 +1,4 @@
 from dragonfly_doe2.cli import doe2
 
-
 if __name__ == '__main__':
     doe2()

dragonfly_doe2/_extend_dragonfly.py

@@ -0,0 +1,33 @@
+# coding=utf-8
+from dragonfly.properties import ModelProperties, Room2DProperties
+import dragonfly.writer.model as model_writer
+
+from .properties.model import ModelDoe2Properties
+from .properties.room2d import Room2DDoe2Properties
+from .writer import model_to_inp
+
+
+# set a hidden doe2 attribute on each core geometry Property class to None
+# define methods to produce doe2 property instances on each Property instance
+ModelProperties._doe2 = None
+Room2DProperties._doe2 = None
+
+
+def model_doe2_properties(self):
+    if self._doe2 is None:
+        self._doe2 = ModelDoe2Properties(self.host)
+    return self._doe2
+
+
+def room2d_doe2_properties(self):
+    if self._doe2 is None:
+        self._doe2 = Room2DDoe2Properties(self.host)
+    return self._doe2
+
+
+# add doe2 property methods to the Properties classes
+ModelProperties.doe2 = property(model_doe2_properties)
+Room2DProperties.doe2 = property(room2d_doe2_properties)
+
+# add writers to the honeybee-core modules
+model_writer.inp = model_to_inp

dragonfly_doe2/cli/__init__.py

@@ -1,18 +1,18 @@
-"""dragonfly-doe2 commands which will be added to dragonfly command line interface."""
+"""dragonfly-doe2 commands which will be added to the dragonfly CLI."""
 import click
-from dragonfly.cli import main
 
+from dragonfly.cli import main
 from .translate import translate
 
 
 # command group for all doe2 extension commands.
 @click.group(help='dragonfly doe2 commands.')
-@click.version_option()
 def doe2():
     pass
 
 
+# add sub-commands for doe2
 doe2.add_command(translate)
 
-# add doe2 sub-commands to df CLI
+# add doe2 sub-commands to dragonfly CLI
 main.add_command(doe2)

dragonfly_doe2/cli/translate.py

@@ -1,68 +1,163 @@
-"""Dragonfly DOE2 Translation Commands"""
+"""dragonfly doe2 translation commands."""
 import click
 import sys
-import pathlib
 import logging
+import json
 
-from ..writer import model_to_inp
+from ladybug.commandutil import process_content_to_output
+from honeybee_doe2.simulation import SimulationPar
 from dragonfly.model import Model
-from honeybee.model import Model as HBModel
 
 
 _logger = logging.getLogger(__name__)
 
 
-@click.group(help='Commands for translating Dragonfly JSON files to *.inp files.')
+@click.group(help='Commands for translating Dragonfly files to DOE-2.')
 def translate():
     pass
 
 
-@translate.command('dfjson-to-inp')
-@click.argument('df-json', type=click.Path(
-    exists=True, file_okay=True, dir_okay=False, resolve_path=True)
-)
-@click.option('--name', '-n', help='Name of the output file.', default="model",
-              show_default=True
-              )
-@click.option('--folder', '-f', help='Path to target folder.', type=click.Path(
-    exists=False, file_okay=False, resolve_path=True, dir_okay=True),
-    default='.', show_default=True
-)
-def df_model_to_inp_file(df_json, name, folder):
-    """Translate a DFJSON into a doe2 *.inp file."""
-    try:
-        model = Model.from_dfjson(dfjson_file=df_json)
-        folder = pathlib.Path(folder)
-        folder.mkdir(parents=True, exist_ok=True)
-        model_to_inp(model, folder=folder, name=name)
-    except Exception as e:
-        _logger.exception(f'Model translation failed.\n{e}')
-        sys.exit(1)
-    else:
-        sys.exit(0)
+@translate.command('model-to-inp')
+@click.argument('model-file', type=click.Path(
+    exists=True, file_okay=True, dir_okay=False, resolve_path=True))
+@click.option(
+    '--multiplier/--full-geometry', ' /-fg', help='Flag to note if the '
+    'multipliers on each Building story will be passed along to the '
+    'generated Honeybee Room objects or if full geometry objects should be '
+    'written for each story in the building.', default=True, show_default=True)
+@click.option(
+    '--plenum/--no-plenum', '-p/-np', help='Flag to indicate whether '
+    'ceiling/floor plenum depths assigned to Room2Ds should generate '
+    'distinct 3D Rooms in the translation.', default=True, show_default=True)
+@click.option(
+    '--ceil-adjacency/--no-ceil-adjacency', '-a/-na', help='Flag to indicate '
+    'whether adjacencies should be solved between interior stories when '
+    'Room2Ds perfectly match one another in their floor plate. This ensures '
+    'that Surface boundary conditions are used instead of Adiabatic ones. '
+    'Note that this input has no effect when the object-per-model is Story.',
+    default=True, show_default=True)
+@click.option(
+    '--sim-par-json', '-sp', help='Full path to a honeybee-doe2 SimulationPar '
+    'JSON that describes all of the settings for the simulation. If unspecified, '
+    'default parameters will be generated.', default=None, show_default=True,
+    type=click.Path(exists=True, file_okay=True, dir_okay=False, resolve_path=True))
+@click.option(
+    '--hvac-mapping', '-hm', help='Text to indicate how HVAC systems should be '
+    'assigned to the exported model. Story will assign one HVAC system for each '
+    'distinct level polygon, Model will use only one HVAC system for the whole model '
+    'and AssignedHVAC will follow how the HVAC systems have been assigned to the'
+    'Rooms.properties.energy.hvac. Choose from: Room, Story, Model, AssignedHVAC',
+    default='Story', show_default=True, type=str)
+@click.option(
+    '--include-interior-walls/--exclude-interior-walls', ' /-xw', help='Flag to note '
+    'whether interior walls should be excluded from the export.',
+    default=True, show_default=True)
+@click.option(
+    '--include-interior-ceilings/--exclude-interior-ceilings', ' /-xc', help='Flag to '
+    'note whether interior ceilings should be excluded from the export.',
+    default=True, show_default=True)
+@click.option(
+    '--equest-version', '-eq', help='Optional text string to denote the version '
+    'of eQuest for which the INP definition will be generated. If unspecified '
+    'or unrecognized, the latest version of eQuest will be used.',
+    default='3.65', show_default=True, type=str)
+@click.option(
+    '--output-file', '-o', help='Optional INP file path to output the INP string '
+    'of the translation. By default this will be printed out to stdout.',
+    type=click.File('w'), default='-', show_default=True)
+def model_to_inp_cli(
+    model_file, multiplier, plenum, ceil_adjacency, sim_par_json, hvac_mapping,
+    include_interior_walls, include_interior_ceilings, equest_version, output_file
+):
+    """Translate a Dragonfly Model file to a Radiance string.
 
+    The resulting string will include all geometry and all modifiers.
 
-@translate.command('hbjson-to-inp')
-@click.argument('hb-json', type=click.Path(
-    exists=True, file_okay=True, dir_okay=False, resolve_path=True)
-)
-@click.option('--name', '-n', help='Name of the output file.', default="model",
-              show_default=True
-              )
-@click.option('--folder', '-f', help='Path to target folder.', type=click.Path(
-    exists=False, file_okay=False, resolve_path=True, dir_okay=True),
-    default='.', show_default=True
-)
-def hb_model_to_inp_file(hb_json, name, folder):
-    """Translate a HBJSON into a doe2 *.inp file."""
+    \b
+    Args:
+        model_file: Full path to a Dragonfly Model JSON or Pkl file.
+    """
     try:
-        hb_model = HBModel.from_file(hb_json)
-        model = Model.from_honeybee(hb_model)
-        folder = pathlib.Path(folder)
-        folder.mkdir(parents=True, exist_ok=True)
-        model_to_inp(model, folder=folder, name=name)
+        full_geometry = not multiplier
+        no_plenum = not plenum
+        no_ceil_adjacency = not ceil_adjacency
+        exclude_interior_walls = not include_interior_walls
+        exclude_interior_ceilings = not include_interior_ceilings
+        model_to_inp(
+            model_file, full_geometry, no_plenum, no_ceil_adjacency,
+            sim_par_json, hvac_mapping,
+            exclude_interior_walls, exclude_interior_ceilings,
+            equest_version, output_file)
     except Exception as e:
-        _logger.exception(f'Model translation failed.\n{e}')
+        _logger.exception('Model translation failed.\n{}\n'.format(e))
         sys.exit(1)
     else:
         sys.exit(0)
+
+
+def model_to_inp(
+    model_file, full_geometry=False, no_plenum=False, no_ceil_adjacency=False,
+    sim_par_json=None, hvac_mapping='Story', exclude_interior_walls=False,
+    exclude_interior_ceilings=False, equest_version=None, output_file=None,
+    multiplier=True, plenum=True, ceil_adjacency=True,
+    include_interior_walls=True, include_interior_ceilings=True
+):
+    """Translate a Model file to an INP string.
+
+    Args:
+        model_file: Full path to a Model JSON file (DFJSON) or a Model pkl (DFpkl) file.
+        full_geometry: Boolean to note if the multipliers on each Building story
+            will be passed along to the generated Honeybee Room objects or if
+            full geometry objects should be written for each story in the
+            building. (Default: False).
+        no_plenum: Boolean to indicate whether ceiling/floor plenum depths
+            assigned to Room2Ds should generate distinct 3D Rooms in the
+            translation. (Default: False).
+        ceil_adjacency: Boolean to indicate whether adjacencies should be solved
+            between interior stories when Room2Ds perfectly match one another
+            in their floor plate. This ensures that Surface boundary conditions
+            are used instead of Adiabatic ones. Note that this input has no
+            effect when the object-per-model is Story. (Default: False).
+        simulation_par: A honeybee-doe2 SimulationPar object to specify how the
+            DOE-2 simulation should be run. If None, default simulation
+            parameters will be generated, which will run the simulation for the
+            full year. (Default: None).
+        hvac_mapping: Text to indicate how HVAC systems should be assigned to the
+            exported model. Story will assign one HVAC system for each distinct
+            level polygon, Model will use only one HVAC system for the whole model
+            and AssignedHVAC will follow how the HVAC systems have been assigned
+            to the Rooms.properties.energy.hvac. Choose from the options
+            below. (Default: Story).
+
+            * Room
+            * Story
+            * Model
+            * AssignedHVAC
+
+        exclude_interior_walls: Boolean to note whether interior wall Faces
+            should be excluded from the resulting string. (Default: False).
+        exclude_interior_ceilings: Boolean to note whether interior ceiling
+            Faces should be excluded from the resulting string. (Default: False).
+        equest_version: An optional text string to denote the version of eQuest
+            for which the INP definition will be generated. If unspecified
+            or unrecognized, the latest version of eQuest will be used.
+        output_file: Optional INP file to output the INP string of the translation.
+            If None, the string will be returned from this method. (Default: None).
+    """
+    # re-serialize the Dragonfly Model
+    model = Model.from_file(model_file)
+
+    # load simulation parameters if specified
+    sim_par = None
+    if sim_par_json is not None:
+        with open(sim_par_json) as json_file:
+            data = json.load(json_file)
+        sim_par = SimulationPar.from_dict(data)
+
+    # create the strings for the model
+    inp_str = model.to.inp(
+        model, multiplier, no_plenum, ceil_adjacency, sim_par, hvac_mapping,
+        exclude_interior_walls, exclude_interior_ceilings, equest_version)
+
+    # write out the INP file
+    return process_content_to_output(inp_str, output_file)

dragonfly_doe2/properties/__init__.py

@@ -0,0 +1 @@
+"""dragonfly-radiance properties."""

dragonfly_doe2/properties/model.py

@@ -0,0 +1,255 @@
+# coding=utf-8
+"""Model DOE-2 Properties."""
+from honeybee_doe2.grouping import _grouped_floor_boundary
+
+
+class ModelDoe2Properties(object):
+    """DOE-2 Properties for Dragonfly Model.
+
+    Args:
+        host: A dragonfly_core Model object that hosts these properties.
+
+    Properties:
+        * host
+    """
+
+    def __init__(self, host):
+        """Initialize ModelDoe2Properties."""
+        self._host = host
+
+    @property
+    def host(self):
+        """Get the Model object hosting these properties."""
+        return self._host
+
+    def check_for_extension(self, raise_exception=True, detailed=False):
+        """Check that the Model is valid for DOE-2 simulation.
+
+        This process includes all relevant dragonfly-core checks as well as checks
+        that apply only for DOE-2.
+
+        Args:
+            raise_exception: Boolean to note whether a ValueError should be raised
+                if any errors are found. If False, this method will simply
+                return a text string with all errors that were found. (Default: True).
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+
+        Returns:
+            A text string with all errors that were found or a list if detailed is True.
+            This string (or list) will be empty if no errors were found.
+        """
+        # set up defaults to ensure the method runs correctly
+        detailed = False if raise_exception else detailed
+        msgs = []
+        tol = self.host.tolerance
+        ang_tol = self.host.angle_tolerance
+
+        # perform checks for duplicate identifiers, which might mess with other checks
+        msgs.append(self.host.check_all_duplicate_identifiers(False, detailed))
+
+        # perform checks for key dragonfly model schema rules
+        msgs.append(self.host.check_degenerate_room_2ds(tol, False, detailed))
+        msgs.append(self.host.check_self_intersecting_room_2ds(tol, False, detailed))
+        msgs.append(self.host.check_plenum_depths(tol, False, detailed))
+        msgs.append(self.host.check_window_parameters_valid(tol, False, detailed))
+        msgs.append(self.host.check_no_room2d_overlaps(tol, False, detailed))
+        msgs.append(self.host.check_collisions_between_stories(tol, False, detailed))
+        msgs.append(self.host.check_roofs_above_rooms(tol, False, detailed))
+        msgs.append(self.host.check_room2d_floor_heights_valid(False, detailed))
+        msgs.append(self.host.check_missing_adjacencies(False, detailed))
+        msgs.append(self.host.check_all_room3d(tol, ang_tol, False, detailed))
+
+        # perform checks that are specific to DOE-2
+        msgs.append(self.check_room_2d_floor_plate_vertex_count(False, detailed))
+        msgs.append(self.check_no_room_2d_floor_plate_holes(False, detailed))
+        msgs.append(self.check_no_story_courtyards(tol, False, detailed))
+
+        # output a final report of errors or raise an exception
+        full_msgs = [msg for msg in msgs if msg]
+        if detailed:
+            return [m for msg in full_msgs for m in msg]
+        full_msg = '\n'.join(full_msgs)
+        if raise_exception and len(full_msgs) != 0:
+            raise ValueError(full_msg)
+        return full_msg
+
+    def check_all(self, raise_exception=True, detailed=False):
+        """Check all of the aspects of the Model DOE-2 properties.
+
+        Args:
+            raise_exception: Boolean to note whether a ValueError should be raised
+                if any errors are found. If False, this method will simply
+                return a text string with all errors that were found.
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+
+        Returns:
+            A text string with all errors that were found or a list if detailed is True.
+            This string (or list) will be empty if no errors were found.
+        """
+        # set up defaults to ensure the method runs correctly
+        detailed = False if raise_exception else detailed
+        msgs = []
+        # perform checks for specific energy simulation rules
+        msgs.append(self.check_room_2d_floor_plate_vertex_count(False, detailed))
+        # output a final report of errors or raise an exception
+        full_msgs = [msg for msg in msgs if msg]
+        if detailed:
+            return [m for msg in full_msgs for m in msg]
+        full_msg = '\n'.join(full_msgs)
+        if raise_exception and len(full_msgs) != 0:
+            raise ValueError(full_msg)
+        return full_msg
+
+    def check_room_2d_floor_plate_vertex_count(
+            self, raise_exception=True, detailed=False):
+        """Check whether any Room2Ds floor geometry exceeds the maximum vertex count.
+
+        The DOE-2 engine currently does not support such rooms and limits the
+        total number of vertices to 120.
+
+        Args:
+            raise_exception: If True, a ValueError will be raised if the Room2D
+                floor plate exceeds the maximum number of vertices supported by
+                DOE-2. (Default: True).
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+
+        Returns:
+            A string with the message or a list with a dictionary if detailed is True.
+        """
+        detailed = False if raise_exception else detailed
+        msgs = []
+        for room in self.host.room_2ds:
+            msg = room.properties.doe2.check_floor_plate_vertex_count(False, detailed)
+            if detailed:
+                msgs.extend(msg)
+            elif msg != '':
+                msgs.append(msg)
+        if detailed:
+            return msgs
+        full_msg = '\n'.join(msgs)
+        if raise_exception and len(msgs) != 0:
+            raise ValueError(full_msg)
+        return full_msg
+
+    def check_no_room_2d_floor_plate_holes(self, raise_exception=True, detailed=False):
+        """Check whether any Room2D floor geometry has holes.
+
+        EQuest currently has no way to represent such rooms so, if the issue
+        is not addressed, the hole will simply be removed as part of the
+        process of exporting to an INP file.
+
+        Args:
+            raise_exception: If True, a ValueError will be raised if the Room2D
+                floor plate has one or more holes. (Default: True).
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+
+        Returns:
+            A string with the message or a list with a dictionary if detailed is True.
+        """
+        detailed = False if raise_exception else detailed
+        msgs = []
+        for room in self.host.room_2ds:
+            msg = room.properties.doe2.check_no_floor_plate_holes(False, detailed)
+            if detailed:
+                msgs.extend(msg)
+            elif msg != '':
+                msgs.append(msg)
+        if detailed:
+            return msgs
+        full_msg = '\n'.join(msgs)
+        if raise_exception and len(msgs) != 0:
+            raise ValueError(full_msg)
+        return full_msg
+
+    def check_no_story_courtyards(
+            self, tolerance=None, raise_exception=True, detailed=False):
+        """Check that Story floor plates do not contain courtyards.
+
+        EQuest currently has no way to represent such courtyards so, if the issue
+        is not addressed, the courtyards will simply be removed as part of the
+        process of exporting to an INP file.
+
+        Args:
+            tolerance: The tolerance to be used when joining the Room2D floor
+                plates together into a Story floor plate. If None, the Model
+                tolerance will be used. (Default: None).
+            raise_exception: Boolean to note whether a ValueError should be raised
+                if the story contains a courtyard. (Default: True).
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+
+        Returns:
+            A string with the message or a list with a dictionary if detailed is True.
+        """
+        tolerance = self.host.tolerance if tolerance is None else tolerance
+        story_msgs = []
+        for bldg in self.host.buildings:
+            for story in bldg.unique_stories:
+                floor_geos = [room.floor_geometry for room in story.room_2ds]
+                joined_geos = _grouped_floor_boundary(floor_geos, tolerance)
+                if any(geo.has_holes for geo in joined_geos):
+                    c_count = max(len(geo.holes) for geo in joined_geos if geo.has_holes)
+                    hole_msg = 'a courtyard' if c_count == 1 \
+                        else '{} courtyards'.format(c_count)
+                    msg = 'The geometry of Story "{}" contains {}, which eQuest ' \
+                        'cannot represent.'.format(story.display_name, hole_msg)
+                    if detailed:
+                        msg = {
+                            'type': 'ValidationError',
+                            'code': '030103',
+                            'error_type': 'Story Floor Plate Contains Courtyards',
+                            'extension_type': 'DOE2',
+                            'element_type': 'Room2D',
+                            'element_id': [r.identifier for r in story.room_2ds],
+                            'element_name': [r.display_name for r in story.room_2ds],
+                            'message': msg
+                        }
+                    story_msgs.append(msg)
+        if detailed:
+            return story_msgs
+        if story_msgs != []:
+            msg = 'The following Stories have courtyards in their floor plates' \
+                ':\n{}'.format('\n'.join(story_msgs))
+            if raise_exception:
+                raise ValueError(msg)
+            return msg
+        return ''
+
+    def to_dict(self):
+        """Return Model DOE-2 properties as a dictionary."""
+        return {'doe2': {'type': 'ModelDoe2Properties'}}
+
+    def apply_properties_from_dict(self, data):
+        """Apply the energy properties of a dictionary to the host Model of this object.
+
+        Args:
+            data: A dictionary representation of an entire dragonfly-core Model.
+                Note that this dictionary must have ModelEnergyProperties in order
+                for this method to successfully apply the energy properties.
+        """
+        assert 'doe2' in data['properties'], \
+            'Dictionary possesses no ModelDoe2Properties.'
+        room_doe2_dicts = []
+        if 'buildings' in data and data['buildings'] is not None:
+            for b_dict in data['buildings']:
+                if 'unique_stories' in b_dict and b_dict['unique_stories'] is not None:
+                    for story_dict in b_dict['unique_stories']:
+                        for room_dict in story_dict['room_2ds']:
+                            try:
+                                room_doe2_dicts.append(room_dict['properties']['doe2'])
+                            except KeyError:
+                                room_doe2_dicts.append(None)
+        if len(room_doe2_dicts) != 0:
+            for room, r_dict in zip(self.host.room_2ds, room_doe2_dicts):
+                if r_dict is not None:
+                    room.properties.doe2.apply_properties_from_dict(r_dict)
+
+    def ToString(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Model DOE2 Properties: [host: {}]'.format(self.host.display_name)