honeybee-schema 1.59.1__py3-none-any.whl

honeybee_schema/__init__.py

@@ -0,0 +1 @@
+

honeybee_schema/__main__.py

@@ -0,0 +1,4 @@
+from honeybee_schema.cli import main
+
+if __name__ == '__main__':
+    main()

honeybee_schema/_base.py

@@ -0,0 +1,42 @@
+"""Base class for all objects requiring a valid names for all engines."""
+from pydantic import BaseModel, Field, Extra
+
+
+class NoExtraBaseModel(BaseModel):
+    """Base class for all objects that are not extensible with additional keys.
+
+    This effectively includes all objects except for the Properties classes
+    that are assigned to geometry objects.
+    """
+
+    class Config:
+        extra = Extra.forbid
+
+
+class IDdBaseModel(NoExtraBaseModel):
+    """Base class for all objects requiring a identifiers acceptable for all engines."""
+
+    identifier: str = Field(
+        ...,
+        regex=r'^[.A-Za-z0-9_-]+$',
+        min_length=1,
+        max_length=100,
+        description='Text string for a unique object ID. This identifier remains '
+        'constant as the object is mutated, copied, and serialized to different '
+        'formats (eg. dict, idf, rad). This identifier is also used to reference '
+        'the object across a Model. It must be < 100 characters and not contain '
+        'any spaces or special characters.'
+    )
+
+    display_name: str = Field(
+        default=None,
+        description='Display name of the object with no character restrictions.'
+    )
+
+    user_data: dict = Field(
+        default=None,
+        description='Optional dictionary of user data associated with the object.'
+        'All keys and values of this dictionary should be of a standard data '
+        'type to ensure correct serialization of the object (eg. str, float, '
+        'int, list).'
+    )

honeybee_schema/altnumber.py

@@ -0,0 +1,18 @@
+"""Objects used as alternatives to numerical properties."""
+from pydantic import constr
+from ._base import NoExtraBaseModel
+
+
+class NoLimit(NoExtraBaseModel):
+
+    type: constr(regex='^NoLimit$') = 'NoLimit'
+
+
+class Autocalculate(NoExtraBaseModel):
+
+    type: constr(regex='^Autocalculate$') = 'Autocalculate'
+
+
+class Autosize(NoExtraBaseModel):
+
+    type: constr(regex='^Autosize$') = 'Autosize'

honeybee_schema/boundarycondition.py

@@ -0,0 +1,81 @@
+"""Boundary condition schemas."""
+from pydantic import Field, constr
+from typing import List, Union
+
+from ._base import NoExtraBaseModel
+from .altnumber import Autocalculate
+
+
+class Outdoors(NoExtraBaseModel):
+
+    type: constr(regex='^Outdoors$') = 'Outdoors'
+
+    sun_exposure: bool = Field(
+        True,
+        description='A boolean noting whether the boundary is exposed to sun.'
+    )
+
+    wind_exposure: bool = Field(
+        True,
+        description='A boolean noting whether the boundary is exposed to wind.'
+    )
+
+    view_factor: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        le=1,
+        description='A number for the view factor to the ground. This can also be '
+        'an Autocalculate object to have the view factor automatically calculated.'
+    )
+
+
+class Surface(NoExtraBaseModel):
+
+    type: constr(regex='^Surface$') = 'Surface'
+
+    boundary_condition_objects: List[str] = Field(
+        ...,
+        min_items=2,
+        max_items=3,
+        description='A list 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 adjacent sub-face and the third object will be the parent Room '
+        'of the adjacent sub-face.'
+    )
+
+
+class Ground(NoExtraBaseModel):
+
+    type: constr(regex='^Ground$') = 'Ground'
+
+
+class Adiabatic(NoExtraBaseModel):
+
+    type: constr(regex='^Adiabatic$') = 'Adiabatic'
+
+
+class OtherSideTemperature(NoExtraBaseModel):
+
+    type: constr(regex='^OtherSideTemperature$') = 'OtherSideTemperature'
+
+    heat_transfer_coefficient: float = Field(
+        0,
+        ge=0,
+        description='A value in W/m2-K to indicate the combined convective/radiative '
+        'film coefficient. If equal to 0, then the specified temperature above is '
+        'equal to the exterior surface temperature. Otherwise, the temperature above '
+        'is considered the outside air temperature and this coefficient is used to '
+        'determine the difference between this outside air temperature and the '
+        'exterior surface temperature.'
+    )
+
+    temperature: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        description='A temperature value in Celsius to note the temperature on the '
+        'other side of the object. This input can also be an Autocalculate object '
+        'to signify that the temperature is equal to the outdoor air temperature.'
+    )

honeybee_schema/cli.py

@@ -0,0 +1,115 @@
+"""Command Line Interface (CLI) entry point for honeybee schema."""
+
+try:
+    import click
+except ImportError:
+    raise ImportError(
+        'click module is not installed. Try `pip install honeybee-schema[cli]` command.'
+    )
+
+import sys
+import logging
+import json
+import importlib
+from inspect import getmembers, isfunction
+import pkgutil
+
+from honeybee_schema import updater
+
+
+@click.group()
+@click.version_option()
+def main():
+    pass
+
+
+_logger = logging.getLogger(__name__)
+
+
+@main.command('update-model')
+@click.argument('model-json', type=click.Path(
+    exists=True, file_okay=True, dir_okay=False, resolve_path=True))
+@click.option('--version', '-v', help='Text to indicate the version to which the model '
+              'JSON will be updated (eg. 1.41.2). Versions must always consist of '
+              'three integers separated b periods. If None, the Model JSON will '
+              'be updated to the last release that included a breaking change.',
+              type=str, default=None)
+@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 update_model(model_json, version, output_file):
+    """Update a Honeybee Model JSON to a newer version of honeybee-schema.
+
+    \b
+    Args:
+        model_json: Full path to a Model JSON file.
+    """
+    try:
+        # get the version to which the model will be updated
+        up_version = (999, 999, 999) if version is None else \
+            tuple(int(v) for v in version.split('.'))
+
+        # load the model dictionary from the json file and get the version of it
+        with open(model_json) as json_file:
+            model_dict = json.load(json_file)
+        assert 'version' in model_dict, 'No version was found in the input model ' \
+            'JSON. Update process cannot be run.'
+        print(f'Input model version: {model_dict["version"]}', file=sys.stderr)
+        model_version = tuple(int(v) for v in model_dict['version'].split('.'))
+
+        if model_version >= up_version:
+            # no point for updating. Normally we should assert here but by writing
+            # the same file to a new file we make this command more flexible for cases
+            # that we don't know the version for the input model and we want to update
+            # it just in case.
+            mv = '.'.join(map(str, model_version))
+            uv = '.'.join(map(str, up_version))
+            print(
+                f'The input file has a higher version ({mv}) than the target version'
+                f' ({uv}).', file=sys.stderr
+            )
+            output_file.write(json.dumps(model_dict))
+            # let's consider exporting the same file as success
+            sys.exit(0)
+
+        # get functions with a higher version than model_version
+        updaters = []
+
+        for sub_module in pkgutil.walk_packages(updater.__path__):
+            if not sub_module.name.startswith('version_'):
+                continue
+            module = importlib.import_module(f'honeybee_schema.updater.{sub_module.name}')
+            for name, func in getmembers(module, isfunction):
+                if not name.startswith('version_'):
+                    continue
+                func_version = tuple(int(v) for v in name.split('_')[1:])
+                if model_version > func_version or func_version > up_version:
+                    continue
+                updaters.append((func_version, func))
+
+        # sort updaters based on version
+        updaters = sorted(updaters, key=lambda x: x[0])
+
+        # update the dictionary
+        for func_version, up_func in updaters:
+            print(
+                f'Updating to version {".".join(map(str, func_version))}',
+                file=sys.stderr
+            )
+            model_dict = up_func(model_dict)
+
+        # update the model dictionary version and write it to log file
+        if version:
+            model_dict['version'] = version
+        elif updaters:
+            model_dict['version'] = '.'.join((str(i) for i in updaters[-1][0]))
+        output_file.write(json.dumps(model_dict))
+    except Exception as e:
+        _logger.exception('Failed to update Honeybee Model JSON.\n{}'.format(e))
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

honeybee_schema/comparison.py

@@ -0,0 +1,208 @@
+"""Schema for the comparison object returned by the comparison command"""
+from pydantic import BaseModel, Field, constr
+from typing import List
+from enum import Enum
+
+
+class GeometryObjectTypes(str, Enum):
+    """Types of Honeybee geometry objects."""
+    shade = 'Shade'
+    aperture = 'Aperture'
+    door = 'Door'
+    face = 'Face'
+    room = 'Room'
+
+
+class _DiffObjectBase(BaseModel):
+
+    element_type: GeometryObjectTypes = Field(
+        ...,
+        description='Text for the type of object that has been changed.'
+    )
+
+    element_id: str = Field(
+        ...,
+        regex=r'^[^,;!\n\t]+$',
+        min_length=1,
+        max_length=100,
+        description='Text string for the unique object ID that has changed.'
+    )
+
+    element_name: str = Field(
+        None,
+        description='Text string for the display name of the object that has changed.'
+    )
+
+
+class ChangedObject(_DiffObjectBase):
+
+    type: constr(regex='^ChangedObject$') = 'ChangedObject'
+
+    geometry_changed: bool = Field(
+        ...,
+        description='A boolean to note whether the geometry of the object has changed '
+        '(True) or not (False). For the case of a Room, any change in the geometry of '
+        'child Faces, Apertures or Doors will cause this property to be True. Note that '
+        'this property is only True if the change in geometry produces a visible '
+        'change greater than the base model tolerance. So converting the model '
+        'between different unit systems, removing colinear vertices, or doing '
+        'other transformations that are common for export to simulation engines '
+        'will not trigger this property to become True.'
+    )
+
+    energy_changed: bool = Field(
+        False,
+        description='A boolean to note whether the energy properties of the object '
+        'have changed (True) or not (False) such that it is possible for the '
+        'properties of the changed object to be applied to the base model. '
+        'For Rooms, this property will only be true if the energy property '
+        'assigned to the Room has changed and will not be true if a property '
+        'assigned to an individual child Face or Aperture has changed.'
+    )
+
+    radiance_changed: bool = Field(
+        False,
+        description='A boolean to note whether the radiance properties of the object '
+        'have changed (True) or not (False) such that it is possible for the '
+        'properties of the changed object to be applied to the base model. '
+        'For Rooms, this property will only be true if the radiance property '
+        'assigned to the Room has changed and will not be true if a property '
+        'assigned to an individual child Face or Aperture has changed.'
+    )
+
+    geometry: List[dict] = Field(
+        ...,
+        description='A list of DisplayFace3D dictionaries for the new, changed '
+        'geometry. The schema of DisplayFace3D can be found in the ladybug-display-'
+        'schema documentation (https://www.ladybug.tools/ladybug-display-schema) '
+        'and these objects can be used to generate visualizations of individual '
+        'objects that have been changed. Note that this attribute is always '
+        'included in the ChangedObject, even when geometry_changed is False.'
+    )
+
+    existing_geometry: List[dict] = Field(
+        default=None,
+        description='A list of DisplayFace3D dictionaries for the existing (base) '
+        'geometry. The schema of DisplayFace3D can be found in the ladybug-display-'
+        'schema documentation (https://www.ladybug.tools/ladybug-display-schema) '
+        'and these objects can be used to generate visualizations of individual '
+        'objects that have been changed. This attribute is optional and will '
+        'NOT be output if geometry_changed is False.'
+    )
+
+
+class DeletedObject(_DiffObjectBase):
+
+    type: constr(regex='^DeletedObject$') = 'DeletedObject'
+
+    geometry: List[dict] = Field(
+        ...,
+        description='A list of DisplayFace3D dictionaries for the deleted '
+        'geometry. The schema of DisplayFace3D can be found in the ladybug-display-'
+        'schema documentation (https://www.ladybug.tools/ladybug-display-schema) '
+        'and these objects can be used to generate visualizations of individual '
+        'objects that have been deleted.'
+    )
+
+
+class AddedObject(_DiffObjectBase):
+
+    type: constr(regex='^AddedObject$') = 'AddedObject'
+
+    geometry: List[dict] = Field(
+        ...,
+        description='A list of DisplayFace3D dictionaries for the added '
+        'geometry. The schema of DisplayFace3D can be found in the ladybug-display-'
+        'schema documentation (https://www.ladybug.tools/ladybug-display-schema) '
+        'and these objects can be used to generate visualizations of individual '
+        'objects that have been added.'
+    )
+
+
+class ComparisonReport(BaseModel):
+
+    type: constr(regex='^ComparisonReport$') = 'ComparisonReport'
+
+    changed_objects: List[ChangedObject] = Field(
+        default=None,
+        description='A list of ChangedObject definitions for each top-level object '
+        'that has changed in the model. To be a changed object, the object identifier '
+        'must be the same in both models but some other property (either geometry '
+        'or extension attributes) has experienced a meaningful change.'
+    )
+
+    deleted_objects: List[DeletedObject] = Field(
+        default=None,
+        description='A list of DeletedObject definitions for each top-level object '
+        'that has been deleted in the process of going from the base model to the '
+        'new model.'
+    )
+
+    added_objects: List[AddedObject] = Field(
+        default=None,
+        description='A list of AddedObject definitions for each top-level object '
+        'that has been added in the process of going from the base model to the '
+        'new model.'
+    )
+
+
+class ChangedInstruction(_DiffObjectBase):
+
+    type: constr(regex='^ChangedInstruction$') = 'ChangedInstruction'
+
+    update_geometry: bool = Field(
+        True,
+        description='A boolean to note whether the geometry of the object in the '
+        'new/updated model should replace the base/existing geometry (True) or '
+        'the existing geometry should be kept (False).'
+    )
+
+    update_energy: bool = Field(
+        True,
+        description='A boolean to note whether the energy properties of the '
+        'object in the new/updated model should replace the base/existing energy '
+        'properties (True) or the base/existing energy properties should '
+        'be kept (False).'
+    )
+
+    update_radiance: bool = Field(
+        True,
+        description='A boolean to note whether the radiance properties of the '
+        'object in the new/updated model should replace the base/existing radiance '
+        'properties (True) or the base/existing radiance properties should '
+        'be kept (False).'
+    )
+
+
+class DeletedInstruction(_DiffObjectBase):
+
+    type: constr(regex='^DeletedInstruction$') = 'DeletedInstruction'
+
+
+class AddedInstruction(_DiffObjectBase):
+
+    type: constr(regex='^AddedInstruction$') = 'AddedInstruction'
+
+
+class SyncInstructions(BaseModel):
+
+    type: constr(regex='^SyncInstructions$') = 'SyncInstructions'
+
+    changed_objects: List[ChangedInstruction] = Field(
+        default=None,
+        description='A list of ChangedInstruction definitions for each top-level '
+        'object with properties to transfer from the new/updated model to the '
+        'base/existing model.'
+    )
+
+    deleted_objects: List[DeletedInstruction] = Field(
+        default=None,
+        description='A list of DeletedInstruction definitions for each top-level object '
+        'to be deleted from the base/existing model.'
+    )
+
+    added_objects: List[AddedInstruction] = Field(
+        default=None,
+        description='A list of AddedInstruction definitions for each top-level object '
+        'to be added to the base/existing model from the new/updated model.'
+    )

honeybee_schema/doe2/properties.py

@@ -0,0 +1,75 @@
+"""Model DOE-2 properties."""
+from pydantic import Field, constr
+from typing import Union
+
+from .._base import NoExtraBaseModel
+from ..altnumber import Autocalculate
+from ..geometry import Face3D
+
+
+class RoomDoe2Properties(NoExtraBaseModel):
+
+    type: constr(regex='^RoomDoe2Properties$') = \
+        'RoomDoe2Properties'
+
+    assigned_flow: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        description='A number for the design supply air flow rate for the zone '
+        'the Room is assigned to (cfm). This establishes the minimum allowed '
+        'design air flow. Note that the actual design flow may be larger. If '
+        'Autocalculate, this parameter will not be written into the INP.'
+    )
+
+    flow_per_area: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        description='A number for the design supply air flow rate to the zone '
+        'per unit floor area (cfm/ft2). If Autocalculate, this parameter will '
+        'not be written into the INP.'
+    )
+
+    min_flow_ratio: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        le=1,
+        description='A number between 0 and 1 for the minimum allowable zone '
+        'air supply flow rate, expressed as a fraction of design flow rate. Applicable '
+        'to variable-volume type systems only. If Autocalculate, this parameter will '
+        'not be written into the INP.'
+    )
+
+    min_flow_per_area: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        description='A number for the minimum air flow per square foot of '
+        'floor area (cfm/ft2). This is an alternative way of specifying the '
+        'min_flow_ratio. If Autocalculate, this parameter will not be written '
+        'into the INP.'
+    )
+
+    hmax_flow_ratio: Union[Autocalculate, float] = Field(
+        Autocalculate(),
+        ge=0,
+        le=1,
+        description='A number between 0 and 1 for the ratio of the maximum (or fixed) '
+        'heating airflow to the cooling airflow. The specific meaning varies according '
+        'to the type of zone terminal. If Autocalculate, this parameter will '
+        'not be written into the INP.'
+    )
+
+    space_polygon_geometry: Face3D = Field(
+        default=None,
+        description='An optional horizontal Face3D object, which will '
+        'be used to set the SPACE polygon during export to INP. If None, '
+        'the SPACE polygon is auto-calculated from the 3D Room geometry. '
+        'Specifying a geometry here can help overcome some limitations of '
+        'this auto-calculation, particularly for cases where the floors '
+        'of the Room are composed of AirBoundaries.'
+    )
+
+
+class ModelDoe2Properties(NoExtraBaseModel):
+
+    type: constr(regex='^ModelDoe2Properties$') = \
+        'ModelDoe2Properties'

honeybee_schema/energy/_base.py

@@ -0,0 +1,64 @@
+"""Base class used by various schema objects."""
+from pydantic import Field
+import datetime
+
+from .._base import NoExtraBaseModel
+
+
+class EnergyBaseModel(NoExtraBaseModel):
+    """Base class for all objects requiring a valid EnergyPlus identifier."""
+
+    identifier: str = Field(
+        ...,
+        regex=r'^[^,;!\n\t]+$',
+        min_length=1,
+        max_length=100,
+        description='Text string for a unique object ID. This identifier remains '
+        'constant as the object is mutated, copied, and serialized to different '
+        'formats (eg. dict, idf, osm). This identifier is also used to reference '
+        'the object across a Model. It must be < 100 characters, use only '
+        'ASCII characters and exclude (, ; ! \\n \\t).'
+    )
+
+    display_name: str = Field(
+        default=None,
+        description='Display name of the object with no character restrictions.'
+    )
+
+
+class IDdEnergyBaseModel(EnergyBaseModel):
+    """Base class for all objects requiring an EnergyPlus identifier and user_data."""
+
+    user_data: dict = Field(
+        default=None,
+        description='Optional dictionary of user data associated with the object.'
+        'All keys and values of this dictionary should be of a standard data '
+        'type to ensure correct serialization of the object (eg. str, float, '
+        'int, list).'
+    )
+
+
+class DatedBaseModel(NoExtraBaseModel):
+    """Base class for all objects needing to check for a valid Date."""
+
+    @staticmethod
+    def check_date(v, leap_pear_override=None):
+        """Ensure valid date.
+
+        Args:
+            v: The Date array to be validated.
+            leap_pear_override: Boolean to override the typical check for
+                leap year serialization of date arrays. If not None, this
+                boolean wil dictate whether the date is a leap year or not.
+        """
+        if (len(v) == 3 and v[2]) or leap_pear_override:
+            try:
+                datetime.date(2016, v[0], v[1])
+            except ValueError:
+                raise ValueError('{}/{} is not a valid date.'.format(v[0], v[1]))
+        else:
+            try:
+                datetime.date(2017, v[0], v[1])
+            except ValueError:
+                raise ValueError('{}/{} is not a valid date.'.format(v[0], v[1]))
+        return v