More ruby documentation

HPXMLtoOpenStudio/measure.rb

@@ -11,6 +11,7 @@
 
   require resource_file
 end
+require_relative '../ReportUtilityBills/resources/utility_bills.rb'
 
 # start the measure
 class HPXMLtoOpenStudio < OpenStudio::Measure::ModelMeasure

HPXMLtoOpenStudio/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>hpxm_lto_openstudio</name>
   <uid>b1543b30-9465-45ff-ba04-1d1f85e763bc</uid>
-  <version_id>aaee2f7c-073d-437d-8b97-6c97345aa926</version_id>
-  <version_modified>2024-07-12T17:42:07Z</version_modified>
+  <version_id>e84e42c2-5250-463b-81b0-85271bcd3325</version_id>
+  <version_modified>2024-07-12T18:27:29Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -183,7 +183,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>2CD1EC85</checksum>
+      <checksum>504D929D</checksum>
     </file>
     <file>
       <filename>airflow.rb</filename>
@@ -587,12 +587,6 @@
       <usage_type>resource</usage_type>
       <checksum>75562A9A</checksum>
     </file>
-    <file>
-      <filename>utility_bills.rb</filename>
-      <filetype>rb</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>A97AC39E</checksum>
-    </file>
     <file>
       <filename>version.rb</filename>
       <filetype>rb</filetype>

ReportUtilityBills/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>report_utility_bills</name>
   <uid>ca88a425-e59a-4bc4-af51-c7e7d1e960fe</uid>
-  <version_id>ab8ea7e3-c3a8-4893-ae5f-ddf1abb58bec</version_id>
-  <version_modified>2024-07-12T14:33:34Z</version_modified>
+  <version_id>e4784574-5643-421f-b77f-6ce87ba57784</version_id>
+  <version_modified>2024-07-12T18:27:33Z</version_modified>
   <xml_checksum>15BF4E57</xml_checksum>
   <class_name>ReportUtilityBills</class_name>
   <display_name>Utility Bills Report</display_name>
@@ -308,6 +308,12 @@
       <usage_type>resource</usage_type>
       <checksum>6990D619</checksum>
     </file>
+    <file>
+      <filename>utility_bills.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>40519C35</checksum>
+    </file>
     <file>
       <filename>Contains Demand Charges.json</filename>
       <filetype>json</filetype>

HPXMLtoOpenStudio/resources/utility_bills.rb → ReportUtilityBills/resources/utility_bills.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# TODO
+# Collection of methods related to getting units by fuel type, EIA average and marginal rates by state, and household consumptions by state.
 class UtilityBills
-  # TODO
+  # Get type of unit according to HPXML fuel type.
   #
-  # @param fuel_type [TODO] TODO
-  # @return [TODO] TODO
+  # @param fuel_type [String] HPXML fuel type
+  # @return [String] type of unit as stored in unit_conversions.rb
   def self.get_fuel_units(fuel_type)
     return { HPXML::FuelTypeElectricity => 'kwh',
              HPXML::FuelTypeNaturalGas => 'therm',
@@ -16,14 +16,14 @@ def self.get_fuel_units(fuel_type)
              HPXML::FuelTypeWoodPellets => 'kbtu' }[fuel_type]
   end
 
-  # TODO
+  # Get marginal and average rates from EIA data.
   #
   # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
-  # @param state_code [TODO] TODO
-  # @param fuel_type [TODO] TODO
-  # @param fixed_charge [TODO] TODO
-  # @param marginal_rate [TODO] TODO
-  # @return [TODO] TODO
+  # @param state_code [String] State code from the HPXML file
+  # @param fuel_type [String] HPXML fuel type
+  # @param fixed_charge [Double] the monthly fixed charge (USD/month)
+  # @param marginal_rate [Double] the marginal flat rate (USD/kWh or USD/therm, etc.)
+  # @return [Array<Double, Double>] the marginal and average rates (USD/kWh or USD/therm, etc., USD/month)
   def self.get_rates_from_eia_data(runner, state_code, fuel_type, fixed_charge, marginal_rate = nil)
     msn_codes = Constants.StateCodesMap.keys
     msn_codes << 'US'
@@ -49,11 +49,11 @@ def self.get_rates_from_eia_data(runner, state_code, fuel_type, fixed_charge, ma
     return marginal_rate, average_rate
   end
 
-  # TODO
+  # Get the average household consumption (kWh or therm per home per year) by state.
   #
-  # @param state_code [TODO] TODO
-  # @param fuel_type [TODO] TODO
-  # @return [TODO] TODO
+  # @param state_code [String] State code from the HPXML file
+  # @param fuel_type [String] HPXML fuel type
+  # @return [Double] average household electricity or natural gas consumption (kWh/home/yr or therms/home/yr)
   def self.get_household_consumption(state_code, fuel_type)
     rows = CSV.read(File.join(File.dirname(__FILE__), '../../ReportUtilityBills/resources/simple_rates/HouseholdConsumption.csv'))
     rows.each do |row|
@@ -67,32 +67,32 @@ def self.get_household_consumption(state_code, fuel_type)
     end
   end
 
-  # TODO
+  # Get the marginal rate given fixed charge and average household consumption.
   #
-  # @param average_rate [TODO] TODO
-  # @param fixed_charge [TODO] TODO
-  # @param household_consumption [TODO] TODO
-  # @return [TODO] TODO
+  # @param average_rate [Double] the fuel rate averaged over both fixed and marginal annual costs (USD/kWh or USD/therm, etc.)
+  # @param fixed_charge [Double] the monthly fixed charge (USD/month)
+  # @param household_consumption [Double] average household electricity or natural gas consumption (kWh/home/yr or therms/home/yr)
+  # @return [Double] the marginal flat rate (USD/kWh or USD/therm, etc.)
   def self.average_rate_to_marginal_rate(average_rate, fixed_charge, household_consumption)
     return average_rate - 12.0 * fixed_charge / household_consumption
   end
 
-  # TODO
+  # Get the average rate given fixed charge and average household consumption.
   #
-  # @param marginal_rate [TODO] TODO
-  # @param fixed_charge [TODO] TODO
-  # @param household_consumption [TODO] TODO
-  # @return [TODO] TODO
+  # @param marginal_rate [Double] the marginal flat rate (USD/kWh or USD/therm, etc.)
+  # @param fixed_charge [Double] the monthly fixed charge (USD/month)
+  # @param household_consumption [Double] average household electricity or natural gas consumption (kWh/home/yr or therms/home/yr)
+  # @return [Double] the fuel rate averaged over both fixed and marginal annual costs (USD/kWh or USD/therm, etc.)
   def self.marginal_rate_to_average_rate(marginal_rate, fixed_charge, household_consumption)
     return marginal_rate + 12.0 * fixed_charge / household_consumption
   end
 
-  # TODO
+  # Get the EIA SEDS prices by state and fuel type.
   #
   # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
-  # @param state_code [TODO] TODO
-  # @param fuel_type [TODO] TODO
-  # @return [TODO] TODO
+  # @param state_code [String] State code from the HPXML file
+  # @param fuel_type [String] HPXML fuel type
+  # @return [Double] average rate for electricity or natural gas, and marginal rate for all other fuel types (USD/kWh or USD/therm, etc.)
   def self.get_eia_seds_rate(runner, state_code, fuel_type)
     msn_code_map = {
       HPXML::FuelTypeElectricity => 'ESRCD',