fix(loads): Expose property for setpoint cutout_difference

honeybee_grasshopper_energy/json/HB_Apply_Setpoint_Values.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.0", 
+  "version": "1.7.1", 
   "nickname": "ApplySetpointVals", 
   "outputs": [
     [
@@ -47,10 +47,17 @@
       "description": "A numerical value for a single constant value for the\ndehumidifying setpoint [%].", 
       "type": "double", 
       "default": null
+    }, 
+    {
+      "access": "list", 
+      "name": "cutout_difference_", 
+      "description": "An optional positive number for the temperature difference between the\ncutout temperature and the setpoint temperature. Specifying a non-zero\nnumber here is useful for modeling the throttling range associated\nwith a given setup of setpoint controls and HVAC equipment. Throttling\nranges describe the range where a zone is slightly over-cooled or\nover-heated beyond the thermostat setpoint. They are used to avoid\nsituations where HVAC systems turn on only to turn off a few minutes later,\nthereby wearing out the parts of mechanical systems faster. They can\nhave a minor impact on energy consumption and can often have significant\nimpacts on occupant thermal comfort, though using the default value\nof zero will often yield results that are close enough when trying\nto estimate the annual heating/cooling energy use. Specifying a value\nof zero effectively assumes that the system will turn on whenever\nconditions are outside the setpoint range and will cut out as soon\nas the setpoint is reached. (Default: 0).", 
+      "type": "double", 
+      "default": null
     }
   ], 
   "subcategory": "3 :: Loads", 
-  "code": "\nimport uuid\n\ntry:\n    from honeybee.model import Model\n    from honeybee.room import Room\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee:\\n\\t{}'.format(e))\n\ntry:\n    from honeybee_energy.load.setpoint import Setpoint\n    from honeybee_energy.schedule.ruleset import ScheduleRuleset\n    import honeybee_energy.lib.scheduletypelimits as _type_lib\n    from honeybee_energy.lib.programtypes import program_type_by_identifier, \\\n        building_program_type_by_identifier\n    from honeybee_energy.programtype import ProgramType\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee_energy:\\n\\t{}'.format(e))\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs, longest_list\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\ndef dup_setpoint(hb_obj):\n    \"\"\"Duplicate a setpoint object assigned to a Room or ProgramType.\"\"\"\n    # try to get the setpoint object assgined to the Room or ProgramType\n    try:  # assume it's a Room\n        setpt_obj = hb_obj.properties.energy.setpoint\n    except AttributeError:  # it's a ProgramType\n        setpt_obj = hb_obj.setpoint\n\n    load_id = '{}_Setpoint'.format(hb_obj.identifier)\n    try:  # duplicate the setpoint object\n        dup_load = setpt_obj.duplicate()\n        dup_load.identifier = load_id\n        return dup_load\n    except AttributeError:  # create a new object if it does not exist\n        heat_sch = ScheduleRuleset.from_constant_value(\n            '{}_HtgSetp'.format(hb_obj.identifier), -50, _type_lib.temperature)\n        cool_sch = ScheduleRuleset.from_constant_value(\n            '{}_ClgSetp'.format(hb_obj.identifier), 50, _type_lib.temperature)\n        return Setpoint(load_id, heat_sch, cool_sch)\n\n\ndef assign_setpoint(hb_obj, setpt_obj):\n    \"\"\"Assign a setpoint object to a Room or a ProgramType.\"\"\"\n    try:  # assume it's a Room\n        hb_obj.properties.energy.setpoint = setpt_obj\n    except AttributeError:  # it's a ProgramType\n        hb_obj.setpoint = setpt_obj\n\n\ndef duplicate_and_id_program(program):\n    \"\"\"Duplicate a program and give it a new unique ID.\"\"\"\n    new_prog = program.duplicate()\n    new_prog.identifier = '{}_{}'.format(program.identifier, str(uuid.uuid4())[:8])\n    return new_prog\n\n\nif all_required_inputs(ghenv.Component):\n    # duplicate the initial objects\n    mod_obj, edit_objs = [], []\n    for obj in _room_or_program:\n        if isinstance(obj, Room):\n            new_obj = obj.duplicate()\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        elif isinstance(obj, Model):\n            new_obj = obj.duplicate()\n            mod_obj.append(new_obj)\n            edit_objs.extend(new_obj.rooms)\n        elif isinstance(obj, ProgramType):\n            new_obj = duplicate_and_id_program(obj)\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        elif isinstance(obj, str):\n            try:\n                program = building_program_type_by_identifier(obj)\n            except ValueError:\n                program = program_type_by_identifier(obj)\n            new_obj = duplicate_and_id_program(program)\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        else:\n            raise TypeError('Expected Honeybee Room, Model or ProgramType. '\n                            'Got {}.'.format(type(obj)))\n\n    # assign the cooling_setpt_\n    if len(cooling_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.cooling_setpoint = longest_list(cooling_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the heating_setpt_\n    if len(heating_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.heating_setpoint = longest_list(heating_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the humid_setpt_\n    if len(humid_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.humidifying_setpoint = longest_list(humid_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the dehumid_setpt_\n    if len(dehumid_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.dehumidifying_setpoint = longest_list(dehumid_setpt_, i)\n            assign_setpoint(obj, setpoint)\n", 
+  "code": "\nimport uuid\n\ntry:\n    from honeybee.model import Model\n    from honeybee.room import Room\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee:\\n\\t{}'.format(e))\n\ntry:\n    from honeybee_energy.load.setpoint import Setpoint\n    from honeybee_energy.schedule.ruleset import ScheduleRuleset\n    import honeybee_energy.lib.scheduletypelimits as _type_lib\n    from honeybee_energy.lib.programtypes import program_type_by_identifier, \\\n        building_program_type_by_identifier\n    from honeybee_energy.programtype import ProgramType\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee_energy:\\n\\t{}'.format(e))\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs, longest_list\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\ndef dup_setpoint(hb_obj):\n    \"\"\"Duplicate a setpoint object assigned to a Room or ProgramType.\"\"\"\n    # try to get the setpoint object assgined to the Room or ProgramType\n    try:  # assume it's a Room\n        setpt_obj = hb_obj.properties.energy.setpoint\n    except AttributeError:  # it's a ProgramType\n        setpt_obj = hb_obj.setpoint\n\n    load_id = '{}_Setpoint'.format(hb_obj.identifier)\n    try:  # duplicate the setpoint object\n        dup_load = setpt_obj.duplicate()\n        dup_load.identifier = load_id\n        return dup_load\n    except AttributeError:  # create a new object if it does not exist\n        heat_sch = ScheduleRuleset.from_constant_value(\n            '{}_HtgSetp'.format(hb_obj.identifier), -50, _type_lib.temperature)\n        cool_sch = ScheduleRuleset.from_constant_value(\n            '{}_ClgSetp'.format(hb_obj.identifier), 50, _type_lib.temperature)\n        return Setpoint(load_id, heat_sch, cool_sch)\n\n\ndef assign_setpoint(hb_obj, setpt_obj):\n    \"\"\"Assign a setpoint object to a Room or a ProgramType.\"\"\"\n    try:  # assume it's a Room\n        hb_obj.properties.energy.setpoint = setpt_obj\n    except AttributeError:  # it's a ProgramType\n        hb_obj.setpoint = setpt_obj\n\n\ndef duplicate_and_id_program(program):\n    \"\"\"Duplicate a program and give it a new unique ID.\"\"\"\n    new_prog = program.duplicate()\n    new_prog.identifier = '{}_{}'.format(program.identifier, str(uuid.uuid4())[:8])\n    return new_prog\n\n\nif all_required_inputs(ghenv.Component):\n    # duplicate the initial objects\n    mod_obj, edit_objs = [], []\n    for obj in _room_or_program:\n        if isinstance(obj, Room):\n            new_obj = obj.duplicate()\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        elif isinstance(obj, Model):\n            new_obj = obj.duplicate()\n            mod_obj.append(new_obj)\n            edit_objs.extend(new_obj.rooms)\n        elif isinstance(obj, ProgramType):\n            new_obj = duplicate_and_id_program(obj)\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        elif isinstance(obj, str):\n            try:\n                program = building_program_type_by_identifier(obj)\n            except ValueError:\n                program = program_type_by_identifier(obj)\n            new_obj = duplicate_and_id_program(program)\n            mod_obj.append(new_obj)\n            edit_objs.append(new_obj)\n        else:\n            raise TypeError('Expected Honeybee Room, Model or ProgramType. '\n                            'Got {}.'.format(type(obj)))\n\n    # assign the cooling_setpt_\n    if len(cooling_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.cooling_setpoint = longest_list(cooling_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the heating_setpt_\n    if len(heating_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.heating_setpoint = longest_list(heating_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the humid_setpt_\n    if len(humid_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.humidifying_setpoint = longest_list(humid_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the dehumid_setpt_\n    if len(dehumid_setpt_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.dehumidifying_setpoint = longest_list(dehumid_setpt_, i)\n            assign_setpoint(obj, setpoint)\n\n    # assign the cutout_difference_\n    if len(cutout_difference_) != 0:\n        for i, obj in enumerate(edit_objs):\n            setpoint = dup_setpoint(obj)\n            setpoint.setpoint_cutout_difference = longest_list(cutout_difference_, i)\n            assign_setpoint(obj, setpoint)\n", 
   "category": "HB-Energy", 
   "name": "HB Apply Setpoint Values", 
   "description": "Apply values for setpoints to a Room or ProgramType.\n-"

honeybee_grasshopper_energy/json/HB_Setpoint.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.0", 
+  "version": "1.7.1", 
   "nickname": "Setpoint", 
   "outputs": [
     [
@@ -47,10 +47,17 @@
       "description": "A numerical value between 0 and 100 for the relative humidity\ndehumidifying setpoint [%]. This value will be constant throughout the\nyear. If None, no dehumidification will occur beyond that which is needed\nto create air at the cooling supply temperature.", 
       "type": "double", 
       "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "cutout_difference_", 
+      "description": "An optional positive number for the temperature difference between the\ncutout temperature and the setpoint temperature. Specifying a non-zero\nnumber here is useful for modeling the throttling range associated\nwith a given setup of setpoint controls and HVAC equipment. Throttling\nranges describe the range where a zone is slightly over-cooled or\nover-heated beyond the thermostat setpoint. They are used to avoid\nsituations where HVAC systems turn on only to turn off a few minutes later,\nthereby wearing out the parts of mechanical systems faster. They can\nhave a minor impact on energy consumption and can often have significant\nimpacts on occupant thermal comfort, though using the default value\nof zero will often yield results that are close enough when trying\nto estimate the annual heating/cooling energy use. Specifying a value\nof zero effectively assumes that the system will turn on whenever\nconditions are outside the setpoint range and will cut out as soon\nas the setpoint is reached. (Default: 0).", 
+      "type": "double", 
+      "default": null
     }
   ], 
   "subcategory": "3 :: Loads", 
-  "code": "\ntry:  # import the core honeybee dependencies\n    from honeybee.typing import clean_and_id_ep_string, clean_ep_string\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee:\\n\\t{}'.format(e))\n\ntry:\n    from honeybee_energy.load.setpoint import Setpoint\n    from honeybee_energy.lib.schedules import schedule_by_identifier\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee_energy:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\nif all_required_inputs(ghenv.Component):\n    # make a default Setpoint name if none is provided\n    name = clean_and_id_ep_string('Setpoint') if _name_ is None else \\\n        clean_ep_string(_name_)\n\n    # get the schedules\n    if isinstance(_heating_sch, str):\n        _heating_sch = schedule_by_identifier(_heating_sch)\n    if isinstance(_cooling_sch, str):\n        _cooling_sch = schedule_by_identifier(_cooling_sch)\n\n    # create the Setpoint object\n    setpoint = Setpoint(name, _heating_sch, _cooling_sch)\n    if _name_ is not None:\n        setpoint.display_name = _name_\n\n    # assign the humidification and dehumidification setpoints if requested\n    if humid_setpt_ is not None:\n        setpoint.humidifying_setpoint = humid_setpt_\n    if dehumid_setpt_ is not None:\n        setpoint.dehumidifying_setpoint = dehumid_setpt_\n", 
+  "code": "\ntry:  # import the core honeybee dependencies\n    from honeybee.typing import clean_and_id_ep_string, clean_ep_string\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee:\\n\\t{}'.format(e))\n\ntry:\n    from honeybee_energy.load.setpoint import Setpoint\n    from honeybee_energy.lib.schedules import schedule_by_identifier\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import honeybee_energy:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\nif all_required_inputs(ghenv.Component):\n    # make a default Setpoint name if none is provided\n    name = clean_and_id_ep_string('Setpoint') if _name_ is None else \\\n        clean_ep_string(_name_)\n\n    # get the schedules\n    if isinstance(_heating_sch, str):\n        _heating_sch = schedule_by_identifier(_heating_sch)\n    if isinstance(_cooling_sch, str):\n        _cooling_sch = schedule_by_identifier(_cooling_sch)\n\n    # create the Setpoint object\n    setpoint = Setpoint(name, _heating_sch, _cooling_sch)\n    if _name_ is not None:\n        setpoint.display_name = _name_\n\n    # assign the humidification and dehumidification setpoints if specified\n    if humid_setpt_ is not None:\n        setpoint.humidifying_setpoint = humid_setpt_\n    if dehumid_setpt_ is not None:\n        setpoint.dehumidifying_setpoint = dehumid_setpt_\n\n    # assign the cutout_difference_ if specified\n    if cutout_difference_ is not None:\n        setpoint.setpoint_cutout_difference = cutout_difference_\n", 
   "category": "HB-Energy", 
   "name": "HB Setpoint", 
   "description": "Create a Setpoint object that can be used to create a ProgramType or be assigned\ndirectly to a Room.\n-"

honeybee_grasshopper_energy/src/HB Apply Setpoint Values.py

@@ -25,6 +25,21 @@
             humidifying setpoint [%].
         dehumid_setpt_: A numerical value for a single constant value for the
             dehumidifying setpoint [%].
+        cutout_difference_: An optional positive number for the temperature difference between the
+            cutout temperature and the setpoint temperature. Specifying a non-zero
+            number here is useful for modeling the throttling range associated
+            with a given setup of setpoint controls and HVAC equipment. Throttling
+            ranges describe the range where a zone is slightly over-cooled or
+            over-heated beyond the thermostat setpoint. They are used to avoid
+            situations where HVAC systems turn on only to turn off a few minutes later,
+            thereby wearing out the parts of mechanical systems faster. They can
+            have a minor impact on energy consumption and can often have significant
+            impacts on occupant thermal comfort, though using the default value
+            of zero will often yield results that are close enough when trying
+            to estimate the annual heating/cooling energy use. Specifying a value
+            of zero effectively assumes that the system will turn on whenever
+            conditions are outside the setpoint range and will cut out as soon
+            as the setpoint is reached. (Default: 0).
 
     Returns:
         report: Reports, errors, warnings, etc.
@@ -33,7 +48,7 @@
 
 ghenv.Component.Name = "HB Apply Setpoint Values"
 ghenv.Component.NickName = 'ApplySetpointVals'
-ghenv.Component.Message = '1.7.0'
+ghenv.Component.Message = '1.7.1'
 ghenv.Component.Category = 'HB-Energy'
 ghenv.Component.SubCategory = '3 :: Loads'
 ghenv.Component.AdditionalHelpFromDocStrings = "2"
@@ -152,3 +167,10 @@ def duplicate_and_id_program(program):
             setpoint = dup_setpoint(obj)
             setpoint.dehumidifying_setpoint = longest_list(dehumid_setpt_, i)
             assign_setpoint(obj, setpoint)
+
+    # assign the cutout_difference_
+    if len(cutout_difference_) != 0:
+        for i, obj in enumerate(edit_objs):
+            setpoint = dup_setpoint(obj)
+            setpoint.setpoint_cutout_difference = longest_list(cutout_difference_, i)
+            assign_setpoint(obj, setpoint)