openstudio-common-measures 0.2.1 → 0.3.0

data/lib/measures/ReduceSpaceInfiltrationByPercentage/measure.xml

@@ -0,0 +1,181 @@
+<measure>
+  <schema_version>3.0</schema_version>
+  <name>reduce_space_infiltration_by_percentage</name>
+  <uid>6e9de4b1-aa97-4010-80c8-529e53ffe943</uid>
+  <version_id>9ef672ce-f7a6-479d-9f4c-8efa80b39f5b</version_id>
+  <version_modified>20200229T024316Z</version_modified>
+  <xml_checksum>EACB548E</xml_checksum>
+  <class_name>ReduceSpaceInfiltrationByPercentage</class_name>
+  <display_name>ReduceSpaceInfiltrationByPercentage</display_name>
+  <description>This measure will reduce space infiltration rates by the requested percentage. A cost per square foot of building area can be added to the model.</description>
+  <modeler_description>This can be run across a space type or the entire building. Costs will be associated with the building. If infiltration objects are removed at a later date, the costs will remain.</modeler_description>
+  <arguments>
+    <argument>
+      <name>space_type</name>
+      <display_name>Apply the Measure to a Specific Space Type or to the Entire Model.</display_name>
+      <type>Choice</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>*Entire Building*</default_value>
+      <choices>
+        <choice>
+          <value>{d0d83664-f46a-42ef-aeb8-e4554efbee21}</value>
+          <display_name>*Entire Building*</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>space_infiltration_reduction_percent</name>
+      <display_name>Space Infiltration Power Reduction</display_name>
+      <type>Double</type>
+      <units>%</units>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>30</default_value>
+    </argument>
+    <argument>
+      <name>constant_coefficient</name>
+      <display_name>Constant Coefficient</display_name>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>1</default_value>
+    </argument>
+    <argument>
+      <name>temperature_coefficient</name>
+      <display_name>Temperature Coefficient</display_name>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0</default_value>
+    </argument>
+    <argument>
+      <name>wind_speed_coefficient</name>
+      <display_name>Wind Speed Coefficient</display_name>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0</default_value>
+    </argument>
+    <argument>
+      <name>wind_speed_squared_coefficient</name>
+      <display_name>Wind Speed Squared Coefficient</display_name>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0</default_value>
+    </argument>
+    <argument>
+      <name>alter_coef</name>
+      <display_name>Alter constant temperature and wind speed coefficients.</display_name>
+      <description>Setting this to false will result in infiltration objects that maintain the coefficients from the initial model. Setting this to true replaces the existing coefficients with the values entered for the coefficient arguments in this measure</description>
+      <type>Boolean</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>true</default_value>
+      <choices>
+        <choice>
+          <value>true</value>
+          <display_name>true</display_name>
+        </choice>
+        <choice>
+          <value>false</value>
+          <display_name>false</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>material_and_installation_cost</name>
+      <display_name>Increase in Material and Installation Costs for Building per Affected Floor Area</display_name>
+      <type>Double</type>
+      <units>$/ft^2</units>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0</default_value>
+    </argument>
+    <argument>
+      <name>om_cost</name>
+      <display_name>O &amp; M Costs for Construction per Affected Floor Area</display_name>
+      <type>Double</type>
+      <units>$/ft^2</units>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0</default_value>
+    </argument>
+    <argument>
+      <name>om_frequency</name>
+      <display_name>O &amp; M Frequency</display_name>
+      <type>Integer</type>
+      <units>whole years</units>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>1</default_value>
+    </argument>
+  </arguments>
+  <outputs/>
+  <provenances/>
+  <tags>
+    <tag>Envelope.Infiltration</tag>
+  </tags>
+  <attributes>
+    <attribute>
+      <name>Measure Type</name>
+      <value>ModelMeasure</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Uses SketchUp API</name>
+      <value>false</value>
+      <datatype>boolean</datatype>
+    </attribute>
+  </attributes>
+  <files>
+    <file>
+      <filename>EnvelopeAndLoadTestModel_01.osm</filename>
+      <filetype>osm</filetype>
+      <usage_type>test</usage_type>
+      <checksum>E64096CB</checksum>
+    </file>
+    <file>
+      <filename>EnvelopeAndLoadTestModel_01_FullyCosted.osm</filename>
+      <filetype>osm</filetype>
+      <usage_type>test</usage_type>
+      <checksum>38E06CA8</checksum>
+    </file>
+    <file>
+      <filename>README.md.erb</filename>
+      <filetype>erb</filetype>
+      <usage_type>readmeerb</usage_type>
+      <checksum>703C9964</checksum>
+    </file>
+    <file>
+      <filename>README.md</filename>
+      <filetype>md</filetype>
+      <usage_type>readme</usage_type>
+      <checksum>864A4EE3</checksum>
+    </file>
+    <file>
+      <filename>ReduceSpaceInfiltrationByPercentage_Test.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>test</usage_type>
+      <checksum>1B488447</checksum>
+    </file>
+    <file>
+      <filename>LICENSE.md</filename>
+      <filetype>md</filetype>
+      <usage_type>license</usage_type>
+      <checksum>E0468DD6</checksum>
+    </file>
+    <file>
+      <version>
+        <software_program>OpenStudio</software_program>
+        <identifier>2.0.0</identifier>
+        <min_compatible>2.0.0</min_compatible>
+      </version>
+      <filename>measure.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>script</usage_type>
+      <checksum>80A67D65</checksum>
+    </file>
+  </files>
+</measure>

data/lib/measures/ReduceVentilationByPercentage/LICENSE.md

@@ -0,0 +1,27 @@
+OpenStudio(R), Copyright (c) 2008-2020, Alliance for Sustainable Energy, LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted 
+provided that the following conditions are met:
+
+(1) Redistributions of source code must retain the above copyright notice, this list of conditions 
+and the following disclaimer.
+
+(2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions
+and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+(3) Neither the name of the copyright holder nor the names of any contributors may be used to endorse 
+or promote products derived from this software without specific prior written permission from the 
+respective party.
+
+(4) Other than as required in clauses (1) and (2), distributions in any form of modifications or other 
+derivative works may not use the "OpenStudio" trademark, "OS", "os", or any other confusingly similar 
+designation without specific prior written permission from Alliance for Sustainable Energy, LLC.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED 
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER, THE UNITED STATES GOVERNMENT, 
+OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/measures/ReduceVentilationByPercentage/README.md

@@ -0,0 +1,40 @@
+
+
+###### (Automatically generated documentation)
+
+# ReduceVentilationByPercentage
+
+## Description
+
+
+## Modeler Description
+
+
+## Measure Type
+ModelMeasure
+
+## Taxonomy
+
+
+## Arguments
+
+
+### Apply the Measure to a Specific Space Type or to the Entire Model.
+
+**Name:** space_type,
+**Type:** Choice,
+**Units:** ,
+**Required:** true,
+**Model Dependent:** false
+
+### Design Specification Outdoor Air Reduction (%).
+
+**Name:** design_spec_outdoor_air_reduction_percent,
+**Type:** Double,
+**Units:** ,
+**Required:** true,
+**Model Dependent:** false
+
+
+
+

data/lib/measures/ReduceVentilationByPercentage/README.md.erb

@@ -0,0 +1,42 @@
+<%#= README.md.erb is used to auto-generate README.md. %>
+<%#= To manually maintain README.md throw away README.md.erb and manually edit README.md %>
+###### (Automatically generated documentation)
+
+# <%= name %>
+
+## Description
+<%= description %>
+
+## Modeler Description
+<%= modelerDescription %>
+
+## Measure Type
+<%= measureType %>
+
+## Taxonomy
+<%= taxonomy %>
+
+## Arguments
+
+<% arguments.each do |argument| %>
+### <%= argument[:display_name] %>
+<%= argument[:description] %>
+**Name:** <%= argument[:name] %>,
+**Type:** <%= argument[:type] %>,
+**Units:** <%= argument[:units] %>,
+**Required:** <%= argument[:required] %>,
+**Model Dependent:** <%= argument[:model_dependent] %>
+<% end %>
+
+<% if arguments.size == 0 %>
+<%= "This measure does not have any user arguments" %>
+<% end %>
+
+<% if outputs.size > 0 %>
+## Outputs
+<% output_names = [] %>
+<% outputs.each do |output| %>
+<% output_names << output[:display_name] %>
+<% end %>
+<%= output_names.join(", ") %>
+<% end %>

data/lib/measures/ReduceVentilationByPercentage/measure.rb

@@ -0,0 +1,291 @@
+# *******************************************************************************
+# OpenStudio(R), Copyright (c) 2008-2020, Alliance for Sustainable Energy, LLC.
+# All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# (1) Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# (2) Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# (3) Neither the name of the copyright holder nor the names of any contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission from the respective party.
+#
+# (4) Other than as required in clauses (1) and (2), distributions in any form
+# of modifications or other derivative works may not use the "OpenStudio"
+# trademark, "OS", "os", or any other confusingly similar designation without
+# specific prior written permission from Alliance for Sustainable Energy, LLC.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) AND ANY CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), ANY CONTRIBUTORS, THE
+# UNITED STATES GOVERNMENT, OR THE UNITED STATES DEPARTMENT OF ENERGY, NOR ANY OF
+# THEIR EMPLOYEES, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+# OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# *******************************************************************************
+
+# see the URL below for information on how to write OpenStudio measures
+# http://openstudio.nrel.gov/openstudio-measure-writing-guide
+
+# see the URL below for information on using life cycle cost objects in OpenStudio
+# http://openstudio.nrel.gov/openstudio-life-cycle-examples
+
+# see the URL below for access to C++ documentation on model objects (click on "model" in the main window to view model objects)
+# http://openstudio.nrel.gov/sites/openstudio.nrel.gov/files/nv_data/cpp_documentation_it/model/html/namespaces.html
+
+# start the measure
+class ReduceVentilationByPercentage < OpenStudio::Measure::ModelMeasure
+  # define the name that a user will see, this method may be deprecated as
+  # the display name in PAT comes from the name field in measure.xml
+  def name
+    return 'ReduceVentilationByPercentage'
+  end
+
+  # define the arguments that the user will input
+  def arguments(model)
+    args = OpenStudio::Measure::OSArgumentVector.new
+
+    # make a choice argument for model objects
+    space_type_handles = OpenStudio::StringVector.new
+    space_type_display_names = OpenStudio::StringVector.new
+
+    # putting model object and names into hash
+    space_type_args = model.getSpaceTypes
+    space_type_args_hash = {}
+    space_type_args.each do |space_type_arg|
+      space_type_args_hash[space_type_arg.name.to_s] = space_type_arg
+    end
+
+    # looping through sorted hash of model objects
+    space_type_args_hash.sort.map do |key, value|
+      # only include if space type is used in the model
+      if !value.spaces.empty?
+        space_type_handles << value.handle.to_s
+        space_type_display_names << key
+      end
+    end
+
+    # add building to string vector with space type
+    building = model.getBuilding
+    space_type_handles << building.handle.to_s
+    space_type_display_names << '*Entire Building*'
+
+    # make a choice argument for space type
+    space_type = OpenStudio::Measure::OSArgument.makeChoiceArgument('space_type', space_type_handles, space_type_display_names)
+    space_type.setDisplayName('Apply the Measure to a Specific Space Type or to the Entire Model.')
+    space_type.setDefaultValue('*Entire Building*') # if no space type is chosen this will run on the entire building
+    args << space_type
+
+    # make an argument for reduction percentage
+    design_spec_outdoor_air_reduction_percent = OpenStudio::Measure::OSArgument.makeDoubleArgument('design_spec_outdoor_air_reduction_percent', true)
+    design_spec_outdoor_air_reduction_percent.setDisplayName('Design Specification Outdoor Air Reduction (%).')
+    design_spec_outdoor_air_reduction_percent.setDefaultValue(30.0)
+    args << design_spec_outdoor_air_reduction_percent
+
+    # no cost required to reduce required amount of outdoor air. Cost increase or decrease will relate to system sizing and ongoing energy use due to change in outdoor air provided.
+
+    return args
+  end
+
+  # define what happens when the measure is run
+  def run(model, runner, user_arguments)
+    super(model, runner, user_arguments)
+
+    # use the built-in error checking
+    if !runner.validateUserArguments(arguments(model), user_arguments)
+      return false
+    end
+
+    # assign the user inputs to variables
+    object = runner.getOptionalWorkspaceObjectChoiceValue('space_type', user_arguments, model)
+    design_spec_outdoor_air_reduction_percent = runner.getDoubleArgumentValue('design_spec_outdoor_air_reduction_percent', user_arguments)
+
+    # check the space_type for reasonableness and see if measure should run on space type or on the entire building
+    apply_to_building = false
+    space_type = nil
+    if object.empty?
+      handle = runner.getStringArgumentValue('space_type', user_arguments)
+      if handle.empty?
+        runner.registerError('No space type was chosen.')
+      else
+        runner.registerError("The selected space type with handle '#{handle}' was not found in the model. It may have been removed by another measure.")
+      end
+      return false
+    else
+      if !object.get.to_SpaceType.empty?
+        space_type = object.get.to_SpaceType.get
+      elsif !object.get.to_Building.empty?
+        apply_to_building = true
+      else
+        runner.registerError('Script Error - argument not showing up as space type or building.')
+        return false
+      end
+    end
+
+    # check the design_spec_outdoor_air_reduction_percent and for reasonableness
+    if design_spec_outdoor_air_reduction_percent > 100
+      runner.registerError('Please enter a value less than or equal to 100 for the Outdoor Air Requirement reduction percentage.')
+      return false
+    elsif design_spec_outdoor_air_reduction_percent == 0
+      runner.registerInfo('No Outdoor Air Requirement adjustment requested, but some life cycle costs may still be affected.')
+    elsif (design_spec_outdoor_air_reduction_percent < 1) && (design_spec_outdoor_air_reduction_percent > -1)
+      runner.registerWarning("A Outdoor Air Requirement reduction percentage of #{design_spec_outdoor_air_reduction_percent} percent is abnormally low.")
+    elsif design_spec_outdoor_air_reduction_percent > 90
+      runner.registerWarning("A Outdoor Air Requirement reduction percentage of #{design_spec_outdoor_air_reduction_percent} percent is abnormally high.")
+    elsif design_spec_outdoor_air_reduction_percent < 0
+      runner.registerInfo('The requested value for Outdoor Air Requirement reduction percentage was negative. This will result in an increase in the Outdoor Air Requirement.')
+    end
+
+    # helper to make numbers pretty (converts 4125001.25641 to 4,125,001.26 or 4,125,001). The definition be called through this measure.
+    def neat_numbers(number, roundto = 2) # round to 0 or 2)
+      if roundto == 2
+        number = format '%.2f', number
+      else
+        number = number.round
+      end
+      # regex to add commas
+      number.to_s.reverse.gsub(/([0-9]{3}(?=([0-9])))/, '\\1,').reverse
+    end
+
+    # get space design_spec_outdoor_air_objects objects used in the model
+    design_spec_outdoor_air_objects = model.getDesignSpecificationOutdoorAirs
+    # TODO: - it would be nice to give ranges for different calculation methods but would take some work.
+
+    # counters needed for measure
+    altered_instances = 0
+
+    # reporting initial condition of model
+    if !design_spec_outdoor_air_objects.empty?
+      runner.registerInitialCondition("The initial model contained #{design_spec_outdoor_air_objects.size} design specification outdoor air objects.")
+    else
+      runner.registerInitialCondition('The initial model did not contain any design specification outdoor air.')
+    end
+
+    # get space types in model
+    building = model.building.get
+    if apply_to_building
+      space_types = model.getSpaceTypes
+      affected_area_si = building.floorArea
+    else
+      space_types = []
+      space_types << space_type # only run on a single space type
+      affected_area_si = space_type.floorArea
+    end
+
+    # split apart any shared uses of design specification outdoor air
+    design_spec_outdoor_air_objects.each do |design_spec_outdoor_air_object|
+      direct_use_count = design_spec_outdoor_air_object.directUseCount
+      next if direct_use_count <= 1
+      direct_uses = design_spec_outdoor_air_object.sources
+      original_cloned = false
+
+      # adjust count test for direct uses that are component data
+      direct_uses.each do |direct_use|
+        component_data_source = direct_use.to_ComponentData
+        if !component_data_source.empty?
+          direct_use_count -= 1
+        end
+      end
+      next if direct_use_count <= 1
+
+      direct_uses.each do |direct_use|
+        # clone and hookup design spec OA
+        space_type_source = direct_use.to_SpaceType
+        if !space_type_source.empty?
+          space_type_source = space_type_source.get
+          cloned_object = design_spec_outdoor_air_object.clone
+          space_type_source.setDesignSpecificationOutdoorAir(cloned_object.to_DesignSpecificationOutdoorAir.get)
+          original_cloned = true
+        end
+
+        space_source = direct_use.to_Space
+        if !space_source.empty?
+          space_source = space_source.get
+          cloned_object = design_spec_outdoor_air_object.clone
+          space_source.setDesignSpecificationOutdoorAir(cloned_object.to_DesignSpecificationOutdoorAir.get)
+          original_cloned = true
+        end
+      end
+
+      # delete the now unused design spec OA
+      if original_cloned
+        runner.registerInfo("Making shared object #{design_spec_outdoor_air_object.name} unique.")
+        design_spec_outdoor_air_object.remove
+      end
+    end
+
+    # def to alter performance and life cycle costs of objects
+    def alter_performance(object, design_spec_outdoor_air_reduction_percent, runner)
+      # edit instance based on percentage reduction
+      instance = object
+
+      # not checking if fields are empty because these are optional like values for space infiltration are.
+      new_outdoor_air_per_person = instance.setOutdoorAirFlowperPerson(instance.outdoorAirFlowperPerson - instance.outdoorAirFlowperPerson * design_spec_outdoor_air_reduction_percent * 0.01)
+      new_outdoor_air_per_floor_area = instance.setOutdoorAirFlowperFloorArea(instance.outdoorAirFlowperFloorArea - instance.outdoorAirFlowperFloorArea * design_spec_outdoor_air_reduction_percent * 0.01)
+      new_outdoor_air_ach = instance.setOutdoorAirFlowAirChangesperHour(instance.outdoorAirFlowAirChangesperHour - instance.outdoorAirFlowAirChangesperHour * design_spec_outdoor_air_reduction_percent * 0.01)
+      new_outdoor_air_rate = instance.setOutdoorAirFlowRate(instance.outdoorAirFlowRate - instance.outdoorAirFlowRate * design_spec_outdoor_air_reduction_percent * 0.01)
+    end
+
+    # array of instances to change
+    instances_array = []
+
+    # loop through space types
+    space_types.each do |space_type|
+      next if space_type.spaces.size <= 0
+      instances_array << space_type.designSpecificationOutdoorAir
+    end
+
+    # get spaces in model
+    if apply_to_building
+      spaces = model.getSpaces
+    else
+      if !space_type.spaces.empty?
+        spaces = space_type.spaces # only run on a single space type
+      end
+    end
+
+    spaces.each do |space|
+      instances_array << space.designSpecificationOutdoorAir
+    end
+
+    instance_processed = []
+
+    instances_array.each do |instance|
+      next if instance.empty?
+      instance = instance.get
+
+      # only continue if this instance has not been processed yet
+      next if instance_processed.include? instance
+      instance_processed << instance
+
+      # call def to alter performance and life cycle costs
+      alter_performance(instance, design_spec_outdoor_air_reduction_percent, runner)
+
+      # rename
+      updated_instance_name = instance.setName("#{instance.name} (#{design_spec_outdoor_air_reduction_percent} percent reduction)")
+      altered_instances += 1
+    end
+
+    if altered_instances == 0
+      runner.registerAsNotApplicable('No design specification outdoor air objects were found in the specified space type(s).')
+    end
+
+    # report final condition
+    affected_area_ip = OpenStudio.convert(affected_area_si, 'm^2', 'ft^2').get
+    runner.registerFinalCondition("#{altered_instances} design specification outdoor air objects in the model were altered affecting #{neat_numbers(affected_area_ip, 0)}(ft^2).")
+
+    return true
+  end
+end
+
+# this allows the measure to be use by the application
+ReduceVentilationByPercentage.new.registerWithApplication