urbanopt-cli 0.10.0 → 0.11.0

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/README.md

@@ -0,0 +1,96 @@
+
+###### (Automatically generated documentation)
+
+# Schedule File Builder
+
+## Description
+Builds a residential schedule file.
+
+Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data.
+
+## Arguments
+
+
+**HPXML File Path**
+
+Absolute/relative path of the HPXML file.
+
+- **Name:** ``hpxml_path``
+- **Type:** ``String``
+
+- **Required:** ``true``
+
+<br/>
+
+**Schedules: Column Names**
+
+A comma-separated list of the column names to generate. If not provided, defaults to all columns. Possible column names are: occupants, lighting_interior, lighting_garage, cooking_range, dishwasher, clothes_washer, clothes_dryer, ceiling_fan, plug_loads_other, plug_loads_tv, hot_water_dishwasher, hot_water_clothes_washer, hot_water_fixtures.
+
+- **Name:** ``schedules_column_names``
+- **Type:** ``String``
+
+- **Required:** ``false``
+
+<br/>
+
+**Schedules: Random Seed**
+
+This numeric field is the seed for the random number generator. Only applies if the schedules type is 'stochastic'.
+
+- **Name:** ``schedules_random_seed``
+- **Type:** ``Integer``
+
+- **Units:** ``#``
+
+- **Required:** ``false``
+
+<br/>
+
+**Schedules: Output CSV Path**
+
+Absolute/relative path of the CSV file containing occupancy schedules. Relative paths are relative to the HPXML output path.
+
+- **Name:** ``output_csv_path``
+- **Type:** ``String``
+
+- **Required:** ``true``
+
+<br/>
+
+**HPXML Output File Path**
+
+Absolute/relative output path of the HPXML file. This HPXML file will include the output CSV path.
+
+- **Name:** ``hpxml_output_path``
+- **Type:** ``String``
+
+- **Required:** ``true``
+
+<br/>
+
+**Debug Mode?**
+
+Applicable when schedules type is stochastic. If true: Write extra state column(s).
+
+- **Name:** ``debug``
+- **Type:** ``Boolean``
+
+- **Required:** ``false``
+
+<br/>
+
+**BuildingID**
+
+The ID of the HPXML Building. Only required if there are multiple Building elements in the HPXML file. Use 'ALL' to apply schedules to all the HPXML Buildings (dwelling units) of a multifamily building.
+
+- **Name:** ``building_id``
+- **Type:** ``String``
+
+- **Required:** ``false``
+
+<br/>
+
+
+
+
+

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/README.md.erb

@@ -0,0 +1,41 @@
+<%#= README.md.erb is used to auto-generate README.md. %>
+###### (Automatically generated documentation)
+
+# <%= name %>
+
+## Description
+<%= description %>
+
+<%= modelerDescription %>
+
+## Arguments
+
+<% arguments.each do |argument| %>
+**<%= argument[:display_name] %>**
+
+<%= argument[:description] %>
+
+- **Name:** ``<%= argument[:name] %>``
+- **Type:** ``<%= argument[:type] %>``
+<% if argument[:units] %>
+- **Units:** ``<%= argument[:units] %>``
+<% end %>
+- **Required:** ``<%= argument[:required] %>``
+<% if argument[:type] == "Choice" %>
+- **Choices:** `<%= argument[:choice_values].join("`, `") %>`
+<% end %>
+<br/>
+<% end %>
+
+<% if arguments.size == 0 %>
+<%= "This measure does not have any user arguments" %>
+<% end %>
+
+<% if outputs.size > 0 %>
+## Outputs
+All possible measure outputs are listed below. Actual outputs depend on measure argument values provided.
+
+<% outputs.each do |output| %>
+- ``<%= output[:display_name] %>``
+<% end %>
+<% end %>

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/measure.rb

@@ -1,3 +1,8 @@
+# *********************************************************************************
+# URBANopt (tm), Copyright (c) Alliance for Sustainable Energy, LLC.
+# See also https://github.com/urbanopt/urbanopt-cli/blob/develop/LICENSE.md
+# *********************************************************************************
+
 # frozen_string_literal: true
 
 # see the URL below for information on how to write OpenStudio measures
@@ -68,6 +73,11 @@ class BuildResidentialScheduleFile < OpenStudio::Measure::ModelMeasure
     arg.setDefaultValue(false)
     args << arg
 
+    arg = OpenStudio::Measure::OSArgument.makeStringArgument('building_id', false)
+    arg.setDisplayName('BuildingID')
+    arg.setDescription("The ID of the HPXML Building. Only required if there are multiple Building elements in the HPXML file. Use 'ALL' to apply schedules to all the HPXML Buildings (dwelling units) of a multifamily building.")
+    args << arg
+
     return args
   end
 
@@ -97,44 +107,84 @@ class BuildResidentialScheduleFile < OpenStudio::Measure::ModelMeasure
     end
     args[:hpxml_output_path] = hpxml_output_path
 
-    hpxml = HPXML.new(hpxml_path: hpxml_path)
+    building_id = nil
+    building_id = args[:building_id].get if args[:building_id].is_initialized
+    hpxml = HPXML.new(hpxml_path: hpxml_path, building_id: building_id)
+
+    debug = false
+    if args[:debug].is_initialized
+      debug = args[:debug].get
+    end
+    args[:debug] = debug
 
-    # exit if number of occupants is zero
-    if hpxml.building_occupancy.number_of_residents == 0
-      runner.registerInfo('Number of occupants set to zero; skipping generation of stochastic schedules.')
-      return true
+    # random seed
+    if args[:schedules_random_seed].is_initialized
+      args[:random_seed] = args[:schedules_random_seed].get
+      runner.registerInfo("Retrieved the schedules random seed; setting it to #{args[:random_seed]}.")
+    else
+      args[:random_seed] = 1
+      runner.registerInfo('Unable to retrieve the schedules random seed; setting it to 1.')
     end
 
     # create EpwFile object
-    epw_path = Location.get_epw_path(hpxml, hpxml_path)
+    epw_path = Location.get_epw_path(hpxml.buildings[0], hpxml_path)
     epw_file = OpenStudio::EpwFile.new(epw_path)
 
-    # create the schedules
-    success = create_schedules(runner, hpxml, epw_file, args)
-    return false if not success
+    output_csv_basename, _ = args[:output_csv_path].split('.csv')
 
-    # modify the hpxml with the schedules path
     doc = XMLHelper.parse_file(hpxml_path)
-    extension = XMLHelper.create_elements_as_needed(XMLHelper.get_element(doc, '/HPXML'), ['SoftwareInfo', 'extension'])
-    schedules_filepaths = XMLHelper.get_values(extension, 'SchedulesFilePath', :string)
-    if !schedules_filepaths.include?(args[:output_csv_path])
-      XMLHelper.add_element(extension, 'SchedulesFilePath', args[:output_csv_path], :string)
+    hpxml_doc = XMLHelper.get_element(doc, '/HPXML')
+    doc_buildings = XMLHelper.get_elements(hpxml_doc, 'Building')
+    doc_buildings.each_with_index do |building, i|
+      doc_building_id = XMLHelper.get_attribute_value(XMLHelper.get_element(building, 'BuildingID'), 'id')
+
+      next if doc_buildings.size > 1 && building_id != 'ALL' && building_id != doc_building_id
+
+      # deterministically vary schedules across building units
+      args[:random_seed] *= (i + 1)
+
+      # get hpxml_bldg
+      hpxml_bldg = hpxml.buildings.find { |hb| hb.building_id == doc_building_id }
+
+      # exit if number of occupants is zero
+      if hpxml_bldg.building_occupancy.number_of_residents == 0
+        runner.registerInfo("#{doc_building_id}: Number of occupants set to zero; skipping generation of stochastic schedules.")
+        next
+      end
+
+      # output csv path
+      args[:output_csv_path] = "#{output_csv_basename}.csv"
+      args[:output_csv_path] = "#{output_csv_basename}_#{i + 1}.csv" if i > 0 && building_id == 'ALL'
+
+      # create the schedules
+      success = create_schedules(runner, hpxml, hpxml_bldg, epw_file, args)
+      return false if not success
+
+      # modify the hpxml with the schedules path
+      extension = XMLHelper.create_elements_as_needed(building, ['BuildingDetails', 'BuildingSummary', 'extension'])
+      schedules_filepaths = XMLHelper.get_values(extension, 'SchedulesFilePath', :string)
+      if !schedules_filepaths.include?(args[:output_csv_path])
+        XMLHelper.add_element(extension, 'SchedulesFilePath', args[:output_csv_path], :string)
+      end
+      write_modified_hpxml(runner, doc, hpxml_path, hpxml_output_path, schedules_filepaths, args)
     end
 
+    return true
+  end
+
+  def write_modified_hpxml(runner, doc, hpxml_path, hpxml_output_path, schedules_filepaths, args)
     # write out the modified hpxml
     if (hpxml_path != hpxml_output_path) || !schedules_filepaths.include?(args[:output_csv_path])
       XMLHelper.write_file(doc, hpxml_output_path)
       runner.registerInfo("Wrote file: #{hpxml_output_path}")
     end
-
-    return true
   end
 
-  def create_schedules(runner, hpxml, epw_file, args)
+  def create_schedules(runner, hpxml, hpxml_bldg, epw_file, args)
     info_msgs = []
 
     get_simulation_parameters(hpxml, epw_file, args)
-    get_generator_inputs(hpxml, epw_file, args)
+    get_generator_inputs(hpxml_bldg, epw_file, args)
 
     args[:resources_path] = File.join(File.dirname(__FILE__), 'resources')
     schedule_generator = ScheduleGenerator.new(runner: runner, epw_file: epw_file, **args)
@@ -177,26 +227,18 @@ class BuildResidentialScheduleFile < OpenStudio::Measure::ModelMeasure
     args[:total_days_in_year] = Constants.NumDaysInYear(calendar_year)
   end
 
-  def get_generator_inputs(hpxml, epw_file, args)
+  def get_generator_inputs(hpxml_bldg, epw_file, args)
     args[:state] = 'CO'
     args[:state] = epw_file.stateProvinceRegion if Constants.StateCodesMap.keys.include?(epw_file.stateProvinceRegion)
-    args[:state] = hpxml.header.state_code if !hpxml.header.state_code.nil?
-
-    args[:random_seed] = args[:schedules_random_seed].get if args[:schedules_random_seed].is_initialized
+    args[:state] = hpxml_bldg.state_code if !hpxml_bldg.state_code.nil?
     args[:column_names] = args[:schedules_column_names].get.split(',').map(&:strip) if args[:schedules_column_names].is_initialized
 
-    if hpxml.building_occupancy.number_of_residents.nil?
-      args[:geometry_num_occupants] = Geometry.get_occupancy_default_num(hpxml.building_construction.number_of_bedrooms)
+    if hpxml_bldg.building_occupancy.number_of_residents.nil?
+      args[:geometry_num_occupants] = Geometry.get_occupancy_default_num(hpxml_bldg.building_construction.number_of_bedrooms)
     else
-      args[:geometry_num_occupants] = hpxml.building_occupancy.number_of_residents
+      args[:geometry_num_occupants] = hpxml_bldg.building_occupancy.number_of_residents
     end
     args[:geometry_num_occupants] = Float(Integer(args[:geometry_num_occupants]))
-
-    debug = false
-    if args[:debug].is_initialized
-      debug = args[:debug].get
-    end
-    args[:debug] = debug
   end
 end
 

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/measure.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0"?>
 <measure>
-  <schema_version>3.0</schema_version>
+  <schema_version>3.1</schema_version>
   <name>build_residential_schedule_file</name>
   <uid>f770b2db-1a9f-4e99-99a7-7f3161a594b1</uid>
-  <version_id>35b84be2-dc0f-4773-a72a-1da40dcaab8c</version_id>
-  <version_modified>20230421T211336Z</version_modified>
+  <version_id>48439a72-2880-4934-b216-38a24bf684b7</version_id>
+  <version_modified>2023-11-02T14:39:58Z</version_modified>
   <xml_checksum>03F02484</xml_checksum>
   <class_name>BuildResidentialScheduleFile</class_name>
   <display_name>Schedule File Builder</display_name>
@@ -71,6 +71,14 @@
         </choice>
       </choices>
     </argument>
+    <argument>
+      <name>building_id</name>
+      <display_name>BuildingID</display_name>
+      <description>The ID of the HPXML Building. Only required if there are multiple Building elements in the HPXML file. Use 'ALL' to apply schedules to all the HPXML Buildings (dwelling units) of a multifamily building.</description>
+      <type>String</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
   </arguments>
   <outputs />
   <provenances />
@@ -85,6 +93,35 @@
     </attribute>
   </attributes>
   <files>
+    <file>
+      <filename>README.md</filename>
+      <filetype>md</filetype>
+      <usage_type>readme</usage_type>
+      <checksum>824BFECD</checksum>
+    </file>
+    <file>
+      <filename>README.md.erb</filename>
+      <filetype>erb</filetype>
+      <usage_type>readmeerb</usage_type>
+      <checksum>513F28E9</checksum>
+    </file>
+    <file>
+      <version>
+        <software_program>OpenStudio</software_program>
+        <identifier>3.2.0</identifier>
+        <min_compatible>3.2.0</min_compatible>
+      </version>
+      <filename>measure.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>script</usage_type>
+      <checksum>6445A4FB</checksum>
+    </file>
+    <file>
+      <filename>README.md</filename>
+      <filetype>md</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>A8A141BE</checksum>
+    </file>
     <file>
       <filename>clothes_dryer_consumption_dist.csv</filename>
       <filetype>csv</filetype>
@@ -109,6 +146,12 @@
       <usage_type>resource</usage_type>
       <checksum>7F0BFEDA</checksum>
     </file>
+    <file>
+      <filename>constants.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>EED44A60</checksum>
+    </file>
     <file>
       <filename>cooking_consumption_dist.csv</filename>
       <filetype>csv</filetype>
@@ -157,6 +200,18 @@
       <usage_type>resource</usage_type>
       <checksum>419E598E</checksum>
     </file>
+    <file>
+      <filename>schedules.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>8365F2E1</checksum>
+    </file>
+    <file>
+      <filename>schedules_config.md</filename>
+      <filetype>md</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>916BF4C3</checksum>
+    </file>
     <file>
       <filename>shower_cluster_size_probability.csv</filename>
       <filetype>csv</filetype>
@@ -854,45 +909,10 @@
       <checksum>5FC694CF</checksum>
     </file>
     <file>
-      <filename>README.md</filename>
-      <filetype>md</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>AAB89065</checksum>
-    </file>
-    <file>
-      <filename>schedules_config.md</filename>
-      <filetype>md</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>916BF4C3</checksum>
-    </file>
-    <file>
-      <filename>constants.rb</filename>
-      <filetype>rb</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>EED44A60</checksum>
-    </file>
-    <file>
-      <filename>schedules.rb</filename>
-      <filetype>rb</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>51D9D15E</checksum>
-    </file>
-    <file>
-      <version>
-        <software_program>OpenStudio</software_program>
-        <identifier>3.2.0</identifier>
-        <min_compatible>3.2.0</min_compatible>
-      </version>
-      <filename>measure.rb</filename>
-      <filetype>rb</filetype>
-      <usage_type>script</usage_type>
-      <checksum>7FA6CE2D</checksum>
-    </file>
-    <file>
-      <filename>build_residential_schedule_file_test.rb</filename>
+      <filename>test_build_residential_schedule_file.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>1903613C</checksum>
+      <checksum>BF7A1992</checksum>
     </file>
   </files>
 </measure>

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/resources/README.md

@@ -1,44 +1,69 @@
-The Stochastic Occupancy Modeling introduces major change to most occupant-related schedules.
-Occupant activities are now generated on-the-fly and saved to .csv files used by Schedule:File objects.
+Stochastic Occupancy Modeling introduces major changes to most occupant-related schedules.
+Occupant activities are now generated on-the-fly and saved to CSV files used by `OpenStudio` Schedule:File objects.
 Schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data.
 
-It outputs a schedule.csv file (which will be available inside generated_files folder of each building simulation output).
-The schedule.csv file contains the following columns: occupants, cooking_range, plug_loads, lighting_interior, lighting_exterior, lighting_garage, lighting_exterior_holiday, clothes_washer, clothes_dryer, dishwasher, baths, showers, sinks, ceiling_fan, clothes_dryer_exhaust, clothes_washer_power, dishwasher_power, sleep, vacancy.
-
-Each of the columns, except the occupants, sleep, and vacancy represent schedule values (kW for power schedules, and gallons per minute for water schedules) normalized using universal maximum values found in constants.rb.
-
-The occupants column represents the fractional percent of occupants present out of the total number of occupants assigned to the unit.
-The sleep column represents the fractional percent of the total number of occupants who are sleeping.
-And the vacancy column will either be 0 or 1 depending upon if the vacancy period is in effect.
-
-There are the same number of rows as the total simulation time-step (e.g., 35040 if 15-min, 8760 if hourly (8784, if leap year)).
-
-The ScheduleGenerator class uses Markov chain based simulation to generate the schedule.csv. To support that, several pre-generated set of files are used:
-
-`weekday`
-`weekend`
+The `BuildResidentialScheduleFile` measure outputs a schedule CSV file (available inside the `run` folder of each building simulation output).
+The schedule CSV file contains the following columns:
+* `occupants`
+* `lighting_interior`
+* `lighting_garage`
+* `cooking_range`
+* `dishwasher`
+* `clothes_washer`
+* `clothes_dryer`
+* `ceiling_fan`
+* `plug_loads_other`
+* `plug_loads_tv`
+* `hot_water_dishwasher`
+* `hot_water_clothes_washer`
+* `hot_water_fixtures`
+* `sleep`*
+
+*Column `sleep` is optionally exported only when "debug" mode is enabled.
+
+Each of the columns, except `occupants`, represent schedule values (kW for power schedules, and gallons per minute for water schedules) normalized using universal maximum values found in `constants.rb`.
+
+The `occupants` column represents the fractional percent of occupants present out of the total number of occupants assigned to the unit.
+The `sleep` column represents the fractional percent of the total number of occupants who are sleeping.
+
+There are the same number of rows as the total simulation time-step (e.g., 35040 if 15-min, 8760 if hourly [8784, if leap year]).
+
+The `ScheduleGenerator` class uses Markov chain based simulation to generate the schedule.csv.
+To support that, several pre-generated set of files are used, contained in the following folders:
+* `weekday`
+* `weekend`
 
 These two folders contain the Markov chain initial probability, Markov chain transition and also appliance duration probabilities csv files.
 The appliance duration probabilities here are used during the Markov chain simulation to determine duration of various appliances.
-The files are divided into four clusters (cluster0 to cluster3), for 4 types of occupant behavior types.
+The files are divided into four clusters (cluster0 to cluster3), for 4 occupant behavior types.
 
-`<enduse>_power_consumption_dist.csv`
+`<enduse>_consumption_dist.csv`
 
 These files contain the 15-min power consumption kWh samples for the given end use, obtained from RBSA (average 15-min end use kWh for each submetered home; N=number of homes with that end use).
 The schedule generator randomly picks one of these values to determine the power level of the appliance schedule.
 
-`<enduse>_power_duration_dist.csv`
+`<enduse>_duration_dist.csv`
 
 These files contain the samples of runtime duration of different end uses, in 15-min increments, generated from the RBSA dataset.
-So, a value of 3 means, 45 minutes.
+So, a value of 3 means 45 minutes.
 Each row is for one household, and each column is the duration of one instance of the appliance running.
 
+For the above `<enduse>_consumption_dist.csv` and `<enduse>_duration_dist.csv` files, `<enduse>` may be:
+* `clothes_dryer`
+* `clothes_washer`
+* `cooking`
+* `dishwasher`
+
 `<enduse>_cluster_size_probability.csv`
 
 These files contain the probability distribution of the event cluster size for different domestic hot water end uses, obtained from the HotWaterEventScheduleGenerator Excel file.
 The first row is the probability of a cluster size of 1 event, second row for probability of cluster size of 2 events and so on.
 
-`schedule_config.json`
+For the above `<enduse>_cluster_size_probability.csv` files, `<enduse>` may be:
+* `hot_water_clothes_washer`
+* `hot_water_dishwasher`
+* `shower`
 
-This JSON file contains various miscellaneous configurations for the schedule generator, and their meanings and sources are defined within the file.
+`constants.rb`
 
+This file contains various miscellaneous configurations for the schedule generator, and their meanings and sources are defined within the file.

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/resources/constants.rb

@@ -1,3 +1,8 @@
+# *********************************************************************************
+# URBANopt (tm), Copyright (c) Alliance for Sustainable Energy, LLC.
+# See also https://github.com/urbanopt/urbanopt-cli/blob/develop/LICENSE.md
+# *********************************************************************************
+
 # frozen_string_literal: true
 
 class Constants

data/example_files/resources/hpxml-measures/BuildResidentialScheduleFile/resources/schedules.rb

@@ -1,3 +1,8 @@
+# *********************************************************************************
+# URBANopt (tm), Copyright (c) Alliance for Sustainable Energy, LLC.
+# See also https://github.com/urbanopt/urbanopt-cli/blob/develop/LICENSE.md
+# *********************************************************************************
+
 # frozen_string_literal: true
 
 require 'csv'
@@ -33,17 +38,6 @@ class ScheduleGenerator
     @debug = debug
   end
 
-  def get_random_seed
-    if @random_seed.nil?
-      @runner.registerInfo('Unable to retrieve the schedules random seed; setting it to 1.')
-      seed = 1
-    else
-      @runner.registerInfo("Retrieved the schedules random seed; setting it to #{@random_seed}.")
-      seed = @random_seed
-    end
-    return seed
-  end
-
   def self.export_columns
     return [SchedulesFile::ColumnOccupants,
             SchedulesFile::ColumnLightingInterior,
@@ -89,7 +83,7 @@ class ScheduleGenerator
 
   def create_stochastic_schedules(args:)
     # initialize a random number generator
-    prng = Random.new(get_random_seed)
+    prng = Random.new(@random_seed)
 
     # pre-load the probability distribution csv files for speed
     cluster_size_prob_map = read_activity_cluster_size_probs(resources_path: args[:resources_path])